explain_documentOne catalogue entry: what the document is for, the named clients observed asking this host for it with dates and the status they took, what a 404 costs, and the spec URL. No argument lists all 22. Example: name='owners.json' names the bot that asks for it twice.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Document name or path, e.g. owners.json. Omit for the catalogue. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it returns specific fields, notes the cost of a 404, and mentions observed clients. This gives the agent a clear picture of what the operation entails without contradicting 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 three sentences, tightly packed with facts but without fluff. It front-loads the core purpose and enumerates the return contents. It's concise and readable, though the flow could be slightly clearer (the semicolon-separated list is dense). Overall well-structured and efficient.
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 read-only tool with one optional parameter, the description provides a comprehensive summary of the response contents (purpose, clients, dates, status, 404 cost, spec URL) and an example. It doesn't explain error handling beyond the 404 cost, but for a read-only lookup that's acceptable. The output schema is absent, so the description carries the burden of explaining returns, which it does well.
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 single optional parameter 'name' with its purpose and the 'omit for catalogue' behavior. The description adds an example and the count of entries (22), but these are minor enrichments. With 100% schema coverage, baseline 3 is appropriate; the description doesn't substantially change how the parameter is understood.
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 (explain) and resource (a document catalogue entry), and enumerates exactly what is returned: the document's purpose, clients with dates/status, 404 cost, and spec URL. It clearly distinguishes this from the sibling validation and sitemap tools, which have different purposes.
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 usage: provide a document name to get its catalogue entry, or omit to list all 22. It gives a concrete example and rules for the no-argument case. It doesn't explicitly contrast with siblings, but the distinct purpose is enough to route an agent. It lacks explicit 'when not to use' statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool has a distinct purpose: live host probing, catalogue explanation, llms.txt generation, agent card validation, and llms.txt validation. Even check_discovery_documents and explain_document are clearly separated as 'probe a host' versus 'look up a catalogue entry.'
Most tools follow a clear verb_noun pattern like check_discovery_documents, explain_document, and validate_agent_card. However, llms_txt_from_sitemap breaks the pattern by being a noun phrase with no verb, making it slightly inconsistent.
Five tools is well-scoped for a specialized agent discovery auditing server. Each tool earns its place and there is no obvious redundancy or bloat.
The set covers the core workflows: auditing hosts, explaining documents, and validating two key formats. Minor gaps exist, such as no generator for agent cards or validators for the other 20 probed document types, but agents can still accomplish the main purpose.