Designing APIs for Agents

I heard a neat tip recently about API design for agents: give them a way to send you feedback.

The example I heard was an MCP with a "feedback" tool which had a tool description saying that coding agents should call that any time they had trouble figuring out how to use the rest of the MCP.

I really like this. It's super cheap to implement and I expect you'd get a bunch of actionable signal in amongst the noise.

> Defaults are bad. Agents can be expected to read the documentation, register what good starting values are, and fill them all in, in place.

That is pretty bad, when you now need to look at this code, and you have 95% of the output being craft, but sometimes it isn't, and you need to understand the difference between each.

A great example of that is:

    int fd = open("log.txt", O_RDONLY);

Versus:

    // 1. Manually build and initialize the Security Attributes structure
    SECURITY_ATTRIBUTES sa;
    sa.nLength = sizeof(SECURITY_ATTRIBUTES);
    sa.lpSecurityDescriptor = NULL; // Explicitly no custom security descriptor (inherits default)
    sa.bInheritHandle = FALSE;       // Explicitly state this handle cannot be inherited by child processes

    // 2. We need a handle for the template file parameter. 
    // Win32 requires this to be an active file handle opened with GENERIC_READ, or explicitly INVALID_HANDLE_VALUE.
    HANDLE hTemplateFile = INVALID_HANDLE_VALUE; 

    // 3. Now we call CreateFile with every single parameter fully populated
    HANDLE hFile = CreateFile(
        "log.txt",                 // 1. lpFileName: The file we want to open
        GENERIC_READ,              // 2. dwDesiredAccess: Read-only access
        FILE_SHARE_READ,           // 3. dwShareMode: Prevents any other process from writing to it
        &sa,                       // 4. lpSecurityAttributes: Pointer to our explicitly defined struct
        OPEN_EXISTING,             // 5. dwCreationDisposition: Only open if it already exists
        FILE_ATTRIBUTE_NORMAL,     // 6. dwFlagsAndAttributes: Normal file, no special caching or async flags
        hTemplateFile              // 7. hTemplateFile: Passing our explicit invalid handle instead of NULL
    );

An agent can output the second just as well, sure. However... which one do you think is better to read or understand?

Did you catch the fact that this is blocking concurrent writers? Or that we expected the file to exist?

Or what about:

    HFONT hFont = CreateFont(
        12, 0, 0, 0, FW_NORMAL, TRUE, FALSE, FALSE, 
        DEFAULT_CHARSET, OUT_DEFAULT_PRECIS, CLIP_DEFAULT_PRECIS, 
        DEFAULT_QUALITY, DEFAULT_PITCH | FF_DONTCARE, "Arial"
    );

Versus:

    const char* fontPath = "/usr/share/fonts/truetype/msttcorefonts/arial.ttf";
    FT_New_Face(library, fontPath, 0, &face);
    FT_Set_Pixel_Sizes(face, 0,16  );

Same thing, but actually understanding what is going on is orders of magnitude different.

First time I'm hearing about https://agentauthprotocol.com/ and https://workos.com/auth-md

MCP and A2A weren't enough?

>Defaults are bad. Agents can be expected to read the documentation, register what good starting values are, and fill them all in, in place.

This is not what defaults are for.

If, for example, you are writing a replacement CLI for git, *for the love of God and all that is holy* do not force agents to read the entire documentation and pass a value for every possible parameter