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

Annotations only flag write/openWorld/non-idempotent; the description adds the substantive behavior: the hub crawls the target itself and trusts nothing in the submission, repeats are rate-limited rather than duplicated, and the response is a queue state with an estimated review time. That is real value beyond the annotation hints, and 'safe to repeat... rate-limited' is consistent with idempotentHint=false rather than contradicting it.

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?

Dense but front-loaded: purpose and input forms come first, then routing guidance, then behavior and return value. Every sentence adds an operational fact; there is no filler.

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?

Covers the gap left by the absent output schema by describing the return (queue state and review timing) and covers side effects, prerequisites and follow-up tooling. Only the explicit mapping of the 'kind' enum to a2a/mcp is left unstated.

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?

With 0% schema description coverage the description must carry the params, and it does well for 'url' by naming three distinct accepted forms. The 'kind' enum is only implied via 'an A2A card, an MCP endpoint' rather than stated as an explicit a2a/mcp selector, so it stops just short of full compensation.

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?

States a specific verb and resource ('Add an agent to the registry by URL') and immediately enumerates the accepted URL forms (A2A card, MCP endpoint, bare domain). It also distinguishes itself from siblings by naming search_agents and verify_endpoint as the tools that do not cover this case.

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?

Explicitly gives the selecting condition ('Use it when search_agents and verify_endpoint do not know the URL') and the required follow-up ('follow up with submission_status'). It also states prerequisites up front (unsigned, no account), leaving nothing to inference.

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