I made my Apify Actor an AI agent tool, then read every byte it sent back

Making an Apify Actor an AI Agent Tool

I have about thirty Actors on the Apify Store. Making one of them available to an AI agent through the Apify MCP server took me two minutes: add ?actors=lergassy/jobs-api to the server URL and the Actor shows up as a tool. That part is a footnote. The useful part was what came back.

Talking to the Server without a Client

Every walkthrough I found used Claude Desktop or Cursor. I wanted the traffic, not a chat transcript, so I used curl. The Apify MCP server speaks streamable HTTP: you POST JSON-RPC, you get back server-sent events.

The Schema the Agent Reads is Not the Schema I Wrote

My input_schema.json has 23 properties. The tool definition the agent receives has 24. The server adds one of its own, and it is the single most important field in the whole exchange - I will come back to it. The rest is my schema, rewritten.

Four Things Surprised Me

1. My emoji and my HTML went straight through. The 🔎 in the title and the <code> tags in the description were written for the Apify Console input form, where they render. In a tool definition they are tokens an agent pays for and markup it has to ignore.
2. The server appends Example values: ["python developer"] to the text. That is a genuinely good move - it converts a Console nicety into an instruction - but it means the prefill field is now documentation.
3. The required field is empty. That is my fault, not the server's. My schema requires nothing, so the tool definition tells the agent that a call with zero arguments is valid. It is not: the Actor has no useful default search.
4. The server lists available fields back to the agent in the order the dataset defines them, and a model asked to choose will lean on the first ones it reads.

What I Changed

Four edits, all in the input schema, none in the scraping code:

1. location now states the cross-field constraint in words: it has to agree with country, and a mismatch returns zero rows rather than an error.
2. country leads with the fact that it defaults to us, instead of burying it under a list of sixty country codes.
3. keywords says it is required unless career-site boards or start URLs are filled in.
4. prefill values are real, correct examples everywhere, now that I know the server promotes them into the description the model reads.

The Actor-Author Lesson

If you want to look at the tool your own Actor exposes, it is one request. Point the URL at https://mcp.apify.com/?actors=<username>/<actor>, run tools/list, and read what comes back as if you had never seen your own input form. I did, and I found four things to fix in an afternoon.