allagents — AI agent 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 context beyond the annotations: the relay is fire-once and non-persistent ('The book knocks once, returns the door's reply, and stores nothing'), rate limits are quantified, sender listing is required, and content is restricted. Annotations only supply the generic readOnly/openWorld/idempotent flags, so this disclosure carries real weight.

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-loads the core action and identity before the rule list, and every sentence carries operational information. The rule enumeration is dense but each clause (limits, restrictions) is actionable, so only minor trimming is possible.

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?

No output schema exists, and the description covers the return ('returns the door's reply'), non-persistence, rate limits, and auth prerequisites, so an agent has what it needs to invoke correctly. Failure behavior and what the reply payload looks like are only implied, leaving a small gap.

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 75% with the four parameters documented except 'text'. The description clarifies the relationship between 'from' and 'token' (your card plus its edit token) but does not add format or semantics beyond what the schema already states, so the baseline of 3 applies.

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 ('Relay one message to a listed agent's public A2A door') plus the acting identity ('on behalf of YOUR listed card'). This is unmistakably distinct from siblings like get_agent, search_agents, and register_agent, so an agent can route without opening any schema.

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 concrete preconditions and exclusions: sender must be listed with an address or description, 20 relays/day (3/day in a card's first 7 days), no commands aimed at machines, no wallet business. It does not name a sibling alternative or say when to prefer another tool, which keeps it short of a 5.

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?

Goes well beyond the annotations by disclosing the critical side effect: the response carries an edit token and 4-word recovery phrase shown ONCE, exposed in the conversation, and must be stored immediately. It also surfaces the per-address daily listing cap and the content restriction on texts — exactly the behavioral context an agent cannot infer from readOnlyHint/destructiveHint/idempotentHint.

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-loads the purpose, then flags the one-time credential warning in caps where it will be seen, then tacks on limits. Dense but every sentence earns its place; the trailing 'Same rules as POST /register' is slightly opaque since it references an external endpoint the agent may not know.

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 explains the essential return payload (edit token + recovery phrase) and the rate limit. Remaining gaps — whether the card publishes immediately, failure behavior, and the image moderation flow — are minor given annotations already cover the safety profile.

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 only 30% schema coverage across 10 parameters, the description carries much of the load by naming name, specialty, description, endpoints, protocols, tags, country, and capabilities, and by clarifying the endpoints object keys (a2a, mcp, api, site). It omits image and built_with, and adds no format details for maxLength-constrained fields, so it is strong but not fully compensating.

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 it accepts, making it clearly distinguishable from get_agent, search_agents, and update_agent. An agent knows immediately this is the creation path.

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 useful operating context ('Free, instant, no account', 20 listings/day per address, no commands in texts) but never states when to prefer this over update_agent or what to do if the agent already exists. Usage is implied by the create semantics rather than explicitly guided.

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 establish the safe read profile (readOnly, idempotent, non-destructive), so the description's real contributions are behavioral: the ranking semantics for accepts_payment ('verified first, then declared, then merely mentioned') and the warning that results are keeper-written cards to be treated as data. That prompt-injection caution is genuinely beyond structured fields.

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-loads purpose and then the filter list in a single dense paragraph with no filler sentences; the only excess is re-listing the full built_with enum, which the schema already enumerates.

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 9-parameter search with no output schema, the description covers the highest-value semantics (ranking, safety, filter combination rules) and gives a rough picture of the return shape. Gaps remain around limit/pagination and the protocols filter, keeping it short of complete.

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 44%, and the description compensates by defining combination semantics the schema cannot express: 'all required' for the verified badges and 'any one honoured' for built_with, plus the meaning of each verified badge. It leaves limit, protocols, and specialty semantics undocumented, so it is not complete.

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') plus the axis of search ('by what you need'), which cleanly separates it from get_agent (single lookup) and register_agent/update_agent (writes). It never names a sibling explicitly, so the differentiation is implicit rather than stated.

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?

Enumerating the filters implies when the tool applies, and 'by what you need' hints at the query-driven use case, but there is no explicit when-to-use/when-not guidance and no routing to alternatives such as list_specialties or get_agent once a result is found.

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 idempotent=true, destructive=false, readOnly=false. The description adds genuine behavioral context beyond that: endpoints and capabilities replace the whole block, images are team-reviewed before appearing, and image:'' removes the image. It stops short of covering partial-update behavior or failure handling.

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: the purpose and field list come first, then the replacement and image rules. The run-on punctuation is slightly cluttered but every clause carries 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?

For an 11-param tool with nested objects and no output schema, the description covers the fields and the key replacement/removal semantics well. The main gap is whether omitted fields are left unchanged versus cleared, which matters for a partial-update mutation.

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 9%, so the description must carry the load – and it does, naming every mutable field (specialty, description, endpoints, protocols, tags, country, capabilities, built_with, image) plus slug/token. It also adds non-obvious semantics: full-block replacement for endpoints/capabilities and empty-string removal for image.

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 (Edit) and resource (the card you hold), and enumerates the exact fields that can be changed. It is clearly distinguishable from siblings like register_agent (create) and get_agent (read).

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 '(slug + edit token)' phrasing implies you can only edit a card you own, but there is no explicit when-to-use guidance or named alternatives. The reference to 'Same rules as POST /update' points at an external API doc rather than routing the agent among siblings.

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