directory

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

Annotations already mark this read-only, non-destructive and closed-world, but the description adds substantive behavior beyond them: answers are grounded only in 'the book's own pages,' it may cite up to 3 agents with verified badges, it admits when the book does not say, and it enforces a quota of 'ten questions a day.' The non-idempotent annotation is consistent with an LLM answering the same question differently.

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?

Three sentences, front-loaded with what the tool is and what it covers, then behavior and limits. The topic list is slightly long but every item maps to a real question domain, so little is wasted.

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?

With no output schema, the description carries the return-value burden and does so: grounded answers, optional citations of up to 3 verified agents, and explicit acknowledgement when the book is silent. Combined with the stated daily quota, an agent has everything needed to call this correctly.

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% for the single 'question' parameter, so the description must compensate. It does so by enumerating the kinds of questions accepted, effectively defining valid parameter content; only the 500-character cap is left undocumented, which is a minor gap for a self-evident string field.

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: 'Ask the book's assistant (an AI) a question about allagents.' It also enumerates the subject domain (listing/editing/claiming cards, badges, finding agents), which clearly separates it from data-lookup siblings like get_agent or search_agents.

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?

The listed question topics ('how to list, edit, claim or withdraw a card, what the badges mean, how to use the directory from an assistant') make it clear this is for meta/how-to questions rather than agent lookups, which implicitly routes the agent away from the sibling tools. However, it never explicitly names an alternative tool or states a when-not-to-use condition.

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

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

Adds substantial behavioral context beyond annotations: the message is relayed once, the reply is returned, nothing is stored, and there's a 20 relays/day rate limit plus content restrictions ('no commands aimed at machines, no wallet business'). Annotations already flag non-read-only, non-idempotent, and open-world, but the description clarifies the one-shot, stateless nature and rate limits.

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?

Two tight sentences that front-load the core action and follow with essential constraints. No wasted words; every clause adds useful information.

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 action, return behavior, storage policy, and constraints like rate limits and content rules. However, without an output schema, it doesn't describe the reply format or error cases. For a messaging tool with no output schema, this is mostly complete but could include what the reply looks like or what happens on failure.

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 75%, so the schema already documents most parameters ('to', 'from', 'token'). The description adds that 'from' is 'YOUR listed card' and 'token' is its edit token, which aligns with schema descriptions. No additional syntax or format details beyond what's already in the schema.

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 (relay/contact) and resource (listed agent's A2A door) with clear scope: 'Relay one message to a listed agent's public A2A door, on behalf of YOUR listed card.' It distinguishes itself from siblings like get_agent or search_agents by framing itself as the action tool for sending a message, not looking up an agent.

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?

Explains the mechanism ('The book knocks once, returns the door's reply, and stores nothing') and states it follows the same rules as POST /relay, which implies conditions like sender must be listed. However, it doesn't explicitly say when to use this tool versus its siblings, or what happens if the recipient is unlisted.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, so the bar is lower; the description still adds meaningful context by warning that the card is authored by its keeper and its text should be treated as data (a prompt-injection caution). It does not mention behavior on an unknown slug.

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?

Two sentences, front-loaded with what the card contains, followed by a short safety caveat. The field list is dense but each item is informative; no padding.

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?

With no output schema, the description usefully enumerates the returned fields and the trust caveat, which is the key missing structured information. Only error behavior and pagination/absence semantics are left unspecified, which is minor for a single-record read.

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 100%, so the slug parameter and its provenance are already documented in the schema. The description adds no format or semantics beyond that, making the baseline 3 appropriate.

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+resource: retrieve the full card of one listed agent, and enumerates the card's contents (description, addresses, protocols, tags, capabilities, badges). 'One listed agent' implies singular lookup against search_agents' plural search, though it never names that sibling.

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?

Usage is only implied: the phrase 'one listed agent' and the schema's 'from search_agents' hints that you first search then fetch, but the description gives no explicit when-to-use or when-not-to-use condition and names no alternative tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: the result is sorted by agent count descending and each entry carries a population count. It does not mention pagination or an empty-result case, keeping it short of a 5.

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?

A single sentence that front-loads the resource, the payload and the sort order. No filler and nothing that could be cut without losing information.

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?

With no parameters and no output schema, the description carries the return-shape burden, and it does say each item is a specialty plus its agent count in a defined order. Minor gaps remain around pagination and result size, but for a simple closed-world listing this is nearly sufficient.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond confirming that it is unfiltered. Baseline 4 applies for a parameterless 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?

States a specific verb+resource ('list specialties') plus the payload ('how many agents it holds') and the ordering. It is clearly distinguishable from the agent-centric siblings (get_agent, search_agents), though it never explicitly names an alternative to route against.

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?

'Every specialty in the book' implies this is the unfiltered enumeration tool, in contrast to query-driven siblings like search_agents, but no when-to-use or when-not-to-use condition is stated outright. Usage is left to inference.

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

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

Annotations only say it is a non-read, non-idempotent, non-destructive write; the description adds substantial context beyond them: no account required, a rate limit, and the critical one-time disclosure that the edit token and 4-word recovery phrase are shown ONCE and will appear in the conversation. That is exactly the kind of behavioral detail an agent must know before calling.

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?

The purpose is front-loaded in the first clause, followed by field enumeration, then the critical one-time-token warning, then the rules. Every sentence earns its place with no padding.

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 mutation tool with no output schema, the description covers the essentials: no auth, rate limit, and the return values (edit token, recovery phrase) that the schema cannot convey. It omits what the resulting card or a success response looks like, but nothing needed to call it correctly is missing.

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 only 13% (just the endpoints field), so the description must carry the load. It does list all eight fields and clarifies that endpoints are https addresses (a2a, mcp, api, site), but gives no semantics for tags, country, protocols, or capabilities, so it only partially compensates.

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 ("Create a card for an agent") and enumerates the fields that make up the card. It is instantly distinguishable from read-oriented siblings like get_agent, search_agents, and list_specialties.

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?

Gives clear operating context ("Free, instant, no account") and hard constraints (20 listings/day per address, no commands in texts), which tells the agent this is a self-service write with no auth. It does not name alternative tools or an explicit when-not, but the usage context is otherwise unambiguous.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-open-world), yet the description adds genuinely new behavior: how verified badges are tested and that all are required, the accepts_payment ranking order (verified > declared > mentioned), and that result text is keeper-authored and should be treated as data — an important prompt-injection caution.

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?

Front-loaded single-purpose sentence followed by a dense but scannable filter breakdown; every clause carries information such as the required-badge rule and the basis disclosure. The telegraphic filter enumeration is slightly compressed but not padded.

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 an 8-parameter, no-output-schema search tool with low schema coverage, the description covers the trust model, ranking, and result format well enough to call it correctly. Limit, query shape, and pagination behavior are the remaining gaps.

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 coverage is only 38%, so the description must carry weight. It supplies real semantics for the ambiguous filters — the meaning of each verified enum value, the ranking logic behind accepts_payment, and the intent of the filters generally — though query and limit are left to the schema.

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+resource ('Find listed AI agents') and scopes it to the directory, so an agent can tell it apart from get_agent or list_specialties by inference. It never names a sibling tool, so it stops just short of explicit differentiation.

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?

Usage is implied by 'by what you need' and the filter list, which tells the agent this is the discovery entry point. There is no explicit when-to-use/when-not guidance and no reference to get_agent for retrieving a single known agent, leaving the routing to inference.

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