Find free proxies

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false), the description discloses the actual side effect — new entries written into the "Free proxies" group — plus the user-confirmation requirement and asynchronous background execution. It also states quality caveats (slow, short-lived) and that proxies are never auto-assigned, which an agent cannot infer from the structured fields. This is exactly the kind of context annotations do not carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, front-loaded with purpose, then caveats, then the async follow-up instruction — no filler. Sentence order is logical and the operational follow-up lands where an agent will read it. Minor density in the middle sentence, but nothing worth cutting.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a background, open-world, non-idempotent tool with no output schema, the description covers the important ground: what it does, its side effects, the confirmation requirement, and how to poll the result. The one real hole is parameter meaning, which is scored separately. An agent could invoke it correctly, but would be guessing about what it is filtering or capping.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across three parameters (limit, country, protocol), so the description must compensate and it says nothing about any of them. The schema's own constraints (max 25, two-letter country pattern, http/socks5 enum) convey format but not meaning — notably whether 'limit' caps candidates tested or proxies added. This is a clear gap for a parameterized tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource chain: search public proxy lists, test candidates for working/anonymous/country, and add passing ones to the "Free proxies" group. That is far more than a restatement of the name, and the note that proxies are 'never assigned automatically' implicitly separates it from assign_proxy. It stops short of explicitly naming a sibling to use instead, so a 4 rather than a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete when-not-to-use guidance ('not for logged-in accounts') and an explicit next step ('Runs in the background; follow with get_run_status'). It also flags that the user is asked first, which shapes when an agent may invoke it. What is missing is a direct alternative, e.g. use list_proxies or check_proxy for an existing pool rather than searching for new ones.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.