wellknown

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

With no annotations provided, the description carries the behavioral disclosure burden. It adds a meaningful semantic contract: results are observed, never guessed, and 'unknown' specifically means no evidence exists. It does not cover permissions, caching, or error behavior, but for a status lookup these are secondary.

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 short sentences, with the return values front-loaded and the critical evidence rule stated immediately after. Every sentence earns its place and 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?

For a single-parameter tool with no output schema, the description covers the main return components and the meaning of 'unknown'. It would be slightly stronger with explicit status vocabulary or an example identifier, but the essential selection and invocation cues are present.

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%, so the description needed to explain idOrHandle, but it does not. The parameter name and tool title imply it is an agent identifier, but accepted formats, how handles are resolved, and what identifier types are valid are left unspecified.

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 clearly states the tool returns observed status, reason, and a 30-day reliability summary, making its purpose specific and recognizable. However, it does not explicitly distinguish itself from siblings like get_agent or resolve_agent, so differentiation is left to inference.

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 phrase 'Never a guess' implies this should be used for evidence-backed liveness checks rather than inferred or estimated status. There is no explicit when-to-use, when-not-to-use, or alternative-sibling guidance, so usage context is only implied.

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?

With no annotations, the description carries the full disclosure burden and performs well: it reveals that proof targets are derived from the record and 'never chosen freely', that a secret is returned, and that verification is a prerequisite for unlocking benefits. It omits edge-case behaviors such as what happens when a record is already claimed or when claiming fails, preventing 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?

The description front-loads its purpose and constraint before the output and workflow details, with every sentence earning its place. The closing benefit chain ('owner edits... 15-minute checks, status alerts, the status badge, and an owner-scoped API key') is slightly long but informative, as it conveys why an agent should complete the claim flow.

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?

Despite having no output schema, the description narratively covers the return contract (proof, claim id, and secret) and the full success-path workflow. Missing failure-mode and precondition details (e.g., auth requirements, already-claimed records) are the main gap, but nothing critical is absent for a moderate 3-parameter tool.

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%, setting a baseline of 3, and the description adds meaningful context beyond the schema: it explains how targets are derived (endpoint host, homepage host, or repository) and maps the proof formats to the method enum values. This enriches an agent's understanding of all three parameters rather than merely restating 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?

The description names a specific action ('Start proving that you operate an indexed agent') on a specific resource, and sharply differentiates itself from the sibling verify_claim by explicitly sequencing this tool before verification. It also specifies the exact output forms (DNS TXT record, /.well-known/ file, or repository file), leaving no ambiguity about what the tool does.

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 description gives explicit workflow guidance: 'Publish the proof, then call verify_claim' names the follow-up tool, and it establishes the when-to-use context of proving ownership to unlock owner features. However, it does not state exclusions or alternatives for other siblings such as search_agents or submit_agent, so it falls 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?

With no annotations, the description carries the full disclosure burden. It usefully lists the returned record contents (declared metadata, derived capabilities, observed status, verification, provenance), but it does not mention failure modes, read-only behavior, or resolution semantics, leaving notable transparency gaps.

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 description is a single well-formed sentence that front-loads the core action and input requirement, then adds a non-redundant list of returned content. It is compact and every clause earns its place, though the enumeration is slightly lengthy.

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 one-parameter read operation with no output schema, the description covers essential input semantics and the categories of returned data. It lacks explicit error/not-found behavior and sibling differentiation, but it is otherwise complete enough for straightforward invocation.

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 schema provides no description for the lone parameter idOrHandle (0% coverage). The description compensates by clarifying that it accepts either a handle or an id, which is essential semantic meaning not present in the schema. It does not specify format details, but for a single simple parameter it is sufficient.

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 clearly states a specific action ('Fetch') and resource ('canonical record for an agent by handle or id') and enumerates the record's content. It conveys an exact lookup tool, but it does not explicitly differentiate itself from sibling tools like resolve_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 description implies this tool should be used when an agent already has a handle or id and needs the canonical record. However, it provides no explicit when-to-use versus alternatives, no exclusionary guidance, and no mention of sibling tools, so the agent must infer selection from context.

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?

With no annotations, the description carries the behavioral burden. 'Counts' implies a read-only operation and 'last crawl' adds freshness context, but it does not explicitly mention side effects, authentication needs, or failure behavior. It adds some value without being fully transparent.

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 description is extremely concise, using a single colon-delimited phrase to list the key statistics. Every word contributes meaning, and the most important term 'Truthful counts' is front-loaded.

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 simple no-parameter statistics tool, the description is reasonably complete: it names the specific data points returned. The absence of an output schema is compensated by these listed categories, though it does not explain whether values are live or cached beyond the 'last crawl' hint.

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 has zero parameters and full schema coverage, so there is no parameter information needed beyond what the schema already provides. The description appropriately focuses on the output categories rather than parameters.

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 clearly identifies the tool as providing counts of indexed records, live endpoints, observations, and last crawl. The title and description align, and the index-specific focus differentiates it from the sibling tools, though it lacks an explicit verb like 'retrieve' or 'return'.

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?

No guidance is given about when to use this tool instead of siblings such as check_status or list_capabilities. The reader must infer that index_stats is for metrics about the index, but the description does not explicitly state exclusions or alternatives.

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?

With no annotations, the description carries the behavioral disclosure burden. It does disclose the return shape ('structured capability slugs') and the purpose, and the verb 'list' strongly implies a read-only operation. It does not mention ordering, exhaustiveness, or availability, but those are minor for a taxonomy listing.

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 result format and follows with the intended use case. There is no filler, repetition, or ambiguous extra detail.

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 zero-parameter listing tool with no output schema, the description adequately explains what is returned and why it would be used. It could be slightly more explicit about pairing with filtering/search sibling tools, but 'for precise filtering' already conveys that relationship.

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 has zero parameters, so the description does not need to document parameter semantics. The description adds useful context about why the returned data exists, which is sufficient at the baseline 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?

The description states a specific verb ('list') and resource ('capability taxonomy'), and clarifies the output format ('domain.capability slugs with aliases'). It is clearly distinguishable from the sibling tools, none of which list capabilities.

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 phrase 'for precise filtering' implicitly tells the agent when to use the tool: when it needs exact capability slugs. However, it does not explicitly state when not to use it or how it relates to sibling tools like search_agents or resolve_agent.

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?

No annotations are present, so the description bears full responsibility for behavioral disclosure. It does reveal that recommendations carry an evidentiary basis ('observed liveness or unverified'), which helps an agent assess output trustworthiness. However, it does not disclose whether the tool performs live network checks, whether it has side effects or authentication needs, or any 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?

The description is two sentences with no waste. The core purpose and return shape are front-loaded, followed by a useful routing note about search_agents. Every clause earns its place.

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 or annotations, the description must compensate by describing the return value and usage context. It gives a high-level return shape and a sibling distinction, but leaves out parameter semantics for three parameters, the detailed structure of the ranked candidates/recommendation, and any failure or edge-case behavior. It is minimally viable but has clear 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 description coverage is only 40%: remoteOnly and requireLive have descriptions, while need, limit, and protocols do not. The description's 'Given a task and constraints' is generic and adds no specific meaning for the undocumented parameters, leaving an agent to guess at the format or effect of need, limit, and protocols.

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 states a specific verb and resource: 'returns ranked candidates and a recommendation' for the 'best available agent for a task'. It also differentiates itself from search_agents by noting this tool is preferred when the result will be called, making its role distinct among siblings.

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 description explicitly says 'Prefer this over search_agents when you intend to call the result,' providing a concrete condition for choosing this tool over the most similar sibling. It does not cover when-not conditions for other siblings like get_agent or claim_agent, but the primary alternative is addressed.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that results are ranked, include observed status and ranking signals, and particularly that result text is untrusted third-party metadata—an important trust consideration not inferable from the schema.

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 description is three concise sentences, each earning its place: what the tool does, what it returns, and a critical security caveat. The most important scoping information is front-loaded, with no wasted words.

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 search tool with five parameters and no output schema, the description covers the essential invocation context: what to search, what results contain, and how to treat result content. It stops short of describing rank ordering details or the semantics of all filters, but nothing critical prevents an agent from calling it 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 60%, and the tool description reinforces the meaning of the query parameter by explaining natural-language capability/task search. However, it adds no detail about limit, status, protocols, or remoteOnly beyond what the schema already provides, leaving those partially or fully undocumented parameters somewhat under-specified.

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 states a specific verb ('Search'), a clear resource ('indexed agents, MCP servers and tools'), and a defining method ('by natural-language capability or task'). This clearly separates it from sibling tools like get_agent or check_status, which target specific entries rather than discovery.

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 description gives clear context for when to use the tool: when you need to find agents or tools by capability or task expressed in natural language. It does not explicitly mention alternatives or exclusions, but the intended scenario is unambiguous and distinct from the sibling tools.

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?

No annotations are present, so the text must carry behavioral context. It discloses that submission only creates an unverified record and that ownership requires a separate claim, which is valuable. The phrase 'Abuse-limited' hints at rate restrictions but is vague and does not specify limits, and no response/error behavior is described.

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 with no filler; the primary action and preferred input are front-loaded. Every clause adds information, and the claim/abuse caveats are placed after the core mechanics.

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?

It covers the core submission flow and the post-submission claim step, but there is no output schema and the description does not say what the tool returns or that one of cardUrl/manifest is required (schema shows 0 required). 'Abuse-limited' is too vague to be actionable, leaving meaningful gaps for a caller.

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 100%, so the baseline is 3; the description adds the preference for cardUrl and the notion of stronger provenance, which is not in the schema. It effectively maps the two optional parameters to a choice, though it doesn't clarify that at least one should be supplied.

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 states a specific verb ('Submit'), the resource ('an agent'), and the two accepted input forms (A2A Agent Card URL or inline manifest). It also distinguishes the tool's outcome from the claim process by noting the record is unverified and ownership must be proven separately, so it won't be confused with claim_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?

It gives concrete selection guidance: prefer cardUrl for strongest provenance and use inline manifest as the fallback. It explicitly warns that ownership proof is not part of this tool ('must be proven separately via a claim'), effectively routing ownership tasks to a sibling. It doesn't list other alternative tools, but the main decision points are covered.

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?

With no annotations, the description carries the full behavioral burden and handles it well: it discloses that the record is marked as owned, that an API key is returned only the first time and shown once, and that contradicting an existing verified owner routes the proof to review instead of transferring ownership. These are exactly the side effects an agent needs to anticipate.

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, no filler, with the core action front-loaded. Each sentence adds a distinct piece of information: what to do, the success outcome and API key caveat, and the conflict edge case.

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 simple two-parameter tool with no output schema, the description covers the primary flow, side effects, the one-time key behavior, and the conflict path. The main gap is the lack of explicit failure semantics or return format, which matters more because no output schema or annotations exist.

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 schema already documents verifySecret as 'returned by claim_agent', and the description only indirectly clarifies claimId via the title's 'claim you started'. With 50% schema description coverage, the description adds some context but does not fully compensate for claimId having no explicit explanation.

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 states a concrete action—'Check the published proof'—and the meaningful result: ownership is marked and an owner-scoped API key is returned. It is clearly distinct from siblings like claim_agent and submit_agent because it is about verifying an already-claimed proof and claiming ownership.

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 description gives clear context for when to call this tool: after starting a claim and after the proof has been published ('Check the published proof now', 'a claim you started'). It does not explicitly name alternatives or exclusion conditions, such as using check_status instead, so it stops 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.