Agent Discovery Doctor - llms.txt, agent card, mcp.json

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

Annotations already mark the tool as read-only and idempotent, and the description adds useful behavior beyond that: it probes 22 documents, classifies results as served/missing/gated/soft-404, reports who asks for missing documents, and refuses certain host categories. No contradiction with the annotations exists.

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 not concise: it embeds a long JSON-RPC invocation for a sibling tool and then packs the actual behavior into a single run-on clause. The structure makes it harder for an agent to quickly parse which parts describe check_discovery_documents itself versus the recommended first call.

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 does explain what the call returns in terms of document statuses and who asks for missing documents, which is helpful. However, the ambiguous 'FIRST CALL' block and absent guidance on groups and mcp_path leave the agent to infer some usage context from the schema alone.

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 input schema already documents host, groups, and mcp_path. The description only contributes an example host value and does not meaningfully extend parameter understanding. With full schema coverage, a baseline of 3 is 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?

The description identifies a specific probing action over discovery documents (llms.txt, agent card, owners.json, etc.) for a host and distinguishes this from the no-argument sibling by showing host is needed. However, the leading 'FIRST CALL' JSON-RPC payload for a different tool muddies which tool is actually being described, so it is not a perfect 5.

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 explicit sequencing guidance: first call no_arguments_check_this_hosts_own_discovery_documents with the provided JSON-RPC payload. It also states operational limits by noting the tool refuses private, ephemeral, and its own hosts. It does not enumerate alternatives like validate_llms_txt or validate_agent_card, so guidance is partial rather than complete.

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 readOnlyHint, idempotentHint, and destructiveHint, and the description adds substantial behavioral detail: it is free, deterministic, touches no third party, fetches nothing, requires no account or API key, and returns exactly what a real call returns—not a mock. This goes well beyond the structured annotations and gives the agent a precise safety and behavior profile.

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 significantly overlong and repetitive: 'no third party' is stated multiple times, 'canned' appears repeated, and 'shape of an answer' is used more than once. It front-loads a useful exact HTTP body, but most of the paragraph could be halved 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?

For a zero-argument example tool with an output schema, the description is fully complete: it supplies the exact request body, the canned input, the behavior, the safety guarantees, and the nature of the return value. Nothing an agent needs to correctly call and understand the tool 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?

There are zero parameters and the schema has 100% coverage, so the baseline is high. The description further reinforces this by explicitly stating 'Takes no arguments' and showing an 'arguments={}' example, leaving no ambiguity about invocation.

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 and specifically states what the tool does: runs this server's own worked example of validate_llms_txt on a canned four-line llms.txt input and returns the real structuredContent. It also explicitly says it takes no arguments, and it is clearly distinguishable from the sibling tools like validate_llms_txt because it is the example/demo tool rather than a real validation tool.

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 usage context: use it to see the shape of an answer before deciding what to send, and it explains that no URL, account, API key, or consent prompt is required. It does not explicitly name when to use validate_llms_txt instead, but the contrast between this example and a real validation call is clear enough.

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 readOnly/idempotent/non-destructive. The description adds non-annotation details: what the catalogue entry contains, the behavior when no argument is supplied, and the 404 cost consequence. No contradiction with annotations.

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 full JSON-RPC invocation for a sibling tool is bulky and front-loads information that is not about explain_document itself. The useful rule could be expressed in a few words; the example and catalogue explanation are concise but the opening block wastes space.

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 tool with one optional parameter and no output schema, the description covers the prerequisite workflow, conditional behavior, and return contents. It would be complete even without the output schema, though the meaning of '404 cost' is a bit terse.

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% and already documents the optional name parameter. The description adds concrete meaning by showing that name='owners.json' returns that document's bot requester and that omitting the argument lists all 22 entries.

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 title and 'One catalogue entry' make clear the tool returns a per-document explanation (purpose, known clients, 404 cost, spec URL), which distinguishes it from listing/validation siblings. However, the opening JSON-RPC block to a sibling tool muddies the focus, so it stops short of a 5.

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 the workflow: first call no_arguments_check_this_hosts_own_discovery_documents, then explain a specific document by name; omitting the name lists all 22 entries. It never explicitly states when to prefer this tool over its siblings or what conditions rule it out, so guidance is mostly inferred.

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?

Beyond the readOnly and idempotent annotations, the description adds meaningful behavioral detail: grouping URLs by path into H2 sections, deriving titles from slugs, preserving lastmod, adding TODOs where human judgment is needed, and treating a sitemap index as one entry. This helps the agent set accurate expectations for the output.

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 and informative, but it includes a full JSON-RPC literal for a different tool that is not required to invoke this one. That extraneous block adds clutter and prevents the description from being tightly structured.

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 does a good job explaining what the draft will look like: H2 sections, slug-derived titles, preserved lastmod, TODOs, and sitemap-index handling. It also covers input forms and includes an example, so the main remaining gaps are edge-case error handling and explicit routing among sibling tools.

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%, and all parameters already have descriptive comments and constraints. The description clarifies that xml can be a plain line-separated URL list and provides an example, but this mostly overlaps with the schema rather than adding substantial new parameter semantics.

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 that the tool consumes a sitemap XML or URL list and produces a draft llms.txt with H2 sections, titles, lastmod, and TODOs. It is specific about the verb and output, though it does not explicitly distinguish this tool from sibling validation/discovery tools, and the embedded JSON-RPC to a sibling muddies the focus.

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 provides usable context: the 'first call' workflow, accepted input formats, an edge case for sitemap indexes, and an example. It does not clearly state when to prefer this tool over alternatives like validate_llms_txt or explain_document, nor any exclusions.

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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint false), the description discloses meaningful behavioral traits: no request leaves this edge, nothing is fetched to build the answer, no key/account/OAuth/session is required, and the result is independent of caller input. These are genuinely additive facts an agent could not infer from the schema or annotations alone, and nothing contradicts the annotations.

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 very long single paragraph with heavy redundancy: 'takes no arguments / nothing to fill in / takes nothing / wants nothing' is restated at least five times, and the full JSON-RPC example call appears twice. It is front-loaded with the most critical fact ('TAKES NO ARGUMENTS'), but many sentences repeat rather than earn their place, and the wall-of-text structure hurts readability.

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, read-only tool with rich annotations and an output schema, the description is complete: it names the endpoint, the exact JSON-RPC call shape, the return contents (present/missing verdict, byte size, group, score, askers with date and status), and sibling routing. Nothing an agent needs to invoke 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?

With zero parameters the baseline is 4, and the description adds real semantics on top: 'the input schema is literally empty, `arguments: {}` and no `arguments` key at all both work.' This tells an agent exactly how to construct a valid call and confirms there is nothing to invent.

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: it checks THIS host's own agent-discovery catalogue, reporting per tracked document whether this host serves it, its size and content type, which are missing, and observed askers with dates and statuses. It also distinguishes itself from siblings by name, implicitly contrasting with check_discovery_documents ('the discovery check this server runs on a host you name, run on this host'). Confusing as the tool name is, the description leaves no doubt 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?

Explicit routing is provided: 'Every other tool on this server wants a file pasted in; this one wants nothing,' and each sibling is listed with the one question it answers (e.g., /mcp/triage maps to no_arguments_triage_this_hosts_own_crawler_log, /mcp/netcheck to the crawler IP ranges tool). The condition for choosing this tool is also stated — the subject is a file this host already publishes, so the answer does not depend on the caller.

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 readOnlyHint and idempotentHint, and the description adds meaningful behavior: checking nine required fields, validating skill fields, warning on capabilities declared true, and giving a concrete example where json='{"name":"a"}' returns the eight missing fields. This goes well beyond what annotations provide.

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 core description is tight and informative, but the embedded full JSON-RPC first-call invocation is verbose and could be misread as saying validate_agent_card itself needs no arguments, contradicting the required json parameter. This structural confusion reduces clarity.

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, read-only validation tool with no output schema, the description covers input expectations, validation criteria, warning behavior, and an example return. An agent has enough information to call it correctly and interpret the result.

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 describes the json parameter as 'The agent card JSON itself, not a URL', and the description reinforces this with 'pasted' and an example. With 100% schema coverage, the baseline is 3; the example and emphasis on pasted JSON lift it to 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 states a specific action: validates a pasted /.well-known/agent-card.json against the nine fields A2A requires, plus each skill's id/name/description/tags. This clearly distinguishes it from sibling validators like validate_llms_txt and check_discovery_documents.

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 'FIRST CALL, needs nothing' instruction with the JSON-RPC payload guides the agent to first call the no-argument sibling no_arguments_check_this_hosts_own_discovery_documents. The word 'pasted' also clarifies that this tool takes inline JSON rather than a URL. It does not explicitly name alternatives or state when not to use it, so it falls just 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. The description adds meaningful behavioral detail: it produces 'Errors and warnings with line numbers and fixes, plus the parsed links,' and explicitly states 'nothing fetched.' No contradiction with annotations.

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 packs useful information, and the key behavior is front-loaded, but the embedded JSON-RPC literal for a different tool is noisy and distracts from the definition of validate_llms_txt. It could be trimmed to improve readability without losing meaning.

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-only, idempotent validator with no output schema, the description covers input constraints, validation rules, output components, side-effect-free behavior, and provides an illustrative example. Nothing essential 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?

The input schema already fully describes the text parameter at 100% coverage, including 'The llms.txt content itself, not a URL.' The description reinforces this by noting 'pasted' input and 'Text in, nothing fetched,' adding practical nuance beyond 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 states a specific verb and resource: "Checks pasted llms.txt against the format: one H1, a blockquote summary, H2 sections of `- [name](url): notes`." This clearly distinguishes it from siblings like validate_agent_card, and the validation rules are concrete.

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 opening 'FIRST CALL, needs nothing' plus the JSON-RPC example for no_arguments_check_this_hosts_own_discovery_documents explicitly guides the agent to call that tool first. Saying 'Text in, nothing fetched' also clarifies the intended input style, indirectly distinguishing this from fetching/sitemap tools. It does not explicitly name alternative siblings, but the context is sufficient.

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?

Beyond the annotations, it adds deterministic, no third-party contact, no fetching (data comes from request headers or already-published files), and exactly which facts are returned. It also explicitly says it takes no arguments and is safe to call, consistent with readOnly/idempotent/destructive hints. No contradiction with annotations.

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, rambling paragraph with a full JSON-RPC example, URL, sibling paths, and a duplicate example; the core behavior appears only after a long preamble. Many details could be trimmed or moved to a shorter 'returns' sentence.

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-argument, read-only tool with an output schema, the description is more than sufficient: it explains the output semantics, determinism, no side effects, and no third-party dependencies. Extraneous transport-level detail and a confusing sibling count slightly undermine readability, but nothing essential about invoking the tool 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?

There are zero parameters and the schema already documents this via empty properties/required. The description reinforces it ('Takes no arguments') and gives an empty-arguments example, which is all that is needed at this level.

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 caller identity data (user-agent, address, classification, prior-visit flag) and the host's observed discovery-document requests with dates/statuses. It also distinguishes it from siblings by noting only this server answers the discovery-log part. However, the purpose is buried under a JSON-RPC/URL preamble and a long list of sibling paths.

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 communicates use context: callable with no args, safe/deterministic, no third-party calls, and suitable for learning what the server knows about the caller. It contrasts with siblings but doesn't give concrete when-to-use/when-not-to-use criteria per sibling beyond 'one other question each about you.' No explicit exclusions or decision rule.

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