Wellknown

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

With no annotations provided, the description carries the full burden and does a strong job: it discloses all four probing paths, validation against JSON Schema, registry queries, and MCP directory checks, plus the return format (scored report). It omits details like whether the tool is read-only or any rate limits, but all actions are inherently read-oriented, making the behavior clear.

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 dense sentence that efficiently lists all major actions, but its length and run-on structure could be improved by splitting into two sentences. Every phrase contributes valuable information, so it is not wasteful, but front-loading is slightly less crisp than ideal.

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?

The description covers the tool's full scope: all advertisement paths, validation, registry lookup, and MCP directory checks, plus the output as a scored report with remediation steps. Given the tool's complexity and absent output schema, this is reasonably complete, though it could mention any operational constraints like network timeout or required permissions.

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% with descriptive parameter definitions (e.g., domain example, competitors limit). The description adds no additional parameter-specific detail beyond the schema, so it reaches the baseline for full coverage.

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 uses a specific verb 'Check' with a clear resource ('domain's agent discoverability') and enumerates the four advertisement paths it probes, which thoroughly distinguishes it from siblings like generate_catalog and validate_catalog.

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 establishes a clear context for use ('Check whether AI agents can find and trust a domain') and lists the audit activities. However, it does not explicitly name alternative tools or stipulate when to use this over validate_catalog or search_registry, but the specific scope and output report make the intended usage evident.

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 full responsibility for behavioral disclosure. It explicitly states that derivation handles three known shapes, that un-derivable fields are omitted and returned as a to-do list, and that capabilities are never fabricated. This is exceptional transparency.

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, front-loaded with purpose and followed by essential constraints. There is zero waste; every word contributes to understanding the tool's behavior.

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 tells the agent what to expect (a catalog and an optional to-do list) and explains the derivation logic. It lacks details on error handling or the exact structure of the catalog, but for a single-parameter tool this is largely 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 schema already fully documents the single 'domain' parameter. The description adds context by indicating that the domain may serve .well-known/mcp.json and that the tool will derive from it, providing meaningful behavioral context beyond the schema's generic description.

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's function with a specific verb ('Produce') and resource ('ARD catalog'), and distinguishes it from siblings by mentioning derivation from .well-known/mcp.json. It is unambiguous and directly aligned with the tool name.

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 when to use the tool (when generating a catalog for a domain) and notes that it handles .well-known/mcp.json if present. However, it does not explicitly contrast with sibling tools like validate_catalog or audit_domain, so guidance is clear but not fully explicit on 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 provided, the description carries the full burden and does so admirably. It discloses the record contents (endpoint, description, publisher, conformance grade, trust level), the behavior for inline artifacts (returned verbatim under `artifact`), gated entries (access block explains provisioning), and authentication effects (whether Wellknown ID holds the grant). This is rich, non-obvious behavioral context.

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 sentences, each densely informative without redundancy. It front-loads the core action, then provides usage guidance, then details edge cases (inline artifact, gated entry, authentication). Every clause adds value; there is no filler or repetition.

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 lookup tool with no output schema and no annotations, the description covers the main response fields, special cases (inline vs gated), authentication behavior, and even the telemetry side-effect of `from_query`. It gives the agent everything needed to invoke and interpret results 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?

The schema already covers both parameters with 100% coverage, so baseline is 3. The description adds value by explaining the identifier format ('urn:air: identifier') and the purpose of `from_query` (letting the registry learn useful results, with a privacy note). This goes beyond the schema's basic descriptions, warranting a 4.

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 opens with a clear, specific verb+resource: 'Fetch the full record for a urn:air: identifier returned by search_registry'. It also distinguishes from siblings by focusing on resolving a single known identifier rather than searching or catalog generation, making it unique among the sibling tools.

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 states when to use: 'Call this before invoking a capability you found, to confirm it is what you want.' This provides a clear directive that separates it from search_registry (which finds candidates) and other siblings. It also notes that granted identifiers resolve here, adding an additional use case without ambiguity.

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?

Despite having no annotations, the description fully discloses the behavioral profile: it operates as a read-only search, returns ranked results with an identifier, endpoint URL, and provenance (whether found on the publisher's own domain or federated). It also transparently states scope including the caller's own granted tools, providing separation from other tools.

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 longer than a single sentence but well-structured: it opens with the most crucial directive ('Search FIRST'), then explains the scope, then the result envelope. Although it is not as compact as possible, every sentence serves a purpose—answering 'when', 'what', and 'what results'—so the length is justified.

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?

The tool is a search with no output schema and no annotations, so the description must carry the full context. It successfully explains what it searches, the scope (Wellknown plus and granted tools), the return fields (identifier, endpoint URL, provenance), and guidance on when to use it. An agent could call this correctly with no additional documentation.

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% (all three parameters are described in the schema). The description adds context about the per-parameter behavior, but the key details (limit semantics, query freeform, published_only filter) are already present in the schema. Thus the description offers no additional semantic meaning beyond the schema, which places it at the baseline.

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 opens with a clear, imperative instruction ('Search FIRST') and defines a specific resource (the registry of agent capabilities) and a precise action ('finds capabilities, MCP servers, and APIs') that differentiates it from a web search. It also lists the exact result structure, so an agent understands exactly what the tool produces.

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 to use this tool *before* a web search and specifies the exact conditions ('whenever a task needs an external tool... you do not already have wired up'). It also names the alternative ('web search') and gives a clear fallback rule ('only when this returns nothing that fits'), leaving no ambiguity about when to choose it over 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 provided, the description carries the full burden and does well: it discloses the ten rules, the schema validation, and the return format (grade + findings with JSON paths). It doesn't cover failure modes or side effects, but for a validator this is sufficient context.

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 dense but front-loaded with the core purpose. The list of rules in one sentence is long yet each item is meaningful. It could be slightly more scannable, but no content 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?

Given no output schema, the description explicitly states return values (grade and findings with JSON paths). It covers the tool's complexity by listing all ten rules and provides domain context, making it complete for an agent to select and invoke the 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 coverage is 100%, so the schema already fully documents both parameters. The description adds no extra parameter-level meaning beyond what's in the schema, giving the baseline score of 3.

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 validates an ARD catalog document for conformance, enumerates specific rules, and mentions the return of a grade and findings. This distinguishes it from siblings like generate_catalog (creates) and audit_domain (domain-focused).

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 its use for conformance checking and gives context on why certain rules matter (e.g., registries rank on representativeQueries). However, it does not explicitly name alternatives or state when not to use it, 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.