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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description still adds real value by disclosing the return format (Markdown), the inclusion of a canonical source URL, and the restriction to public pages. It does not describe failure behavior for unknown slugs, which keeps 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?

Two sentences, front-loaded with the action and return artifact, followed by the input shape and examples. No redundant restatement of the title 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?

For a one-parameter read tool with full annotations and no output schema, the description covers what is fetched, in what format, and what the input looks like. The remaining gap is edge behavior on missing or private slugs, which is modest for this complexity.

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 0% for the single 'slug' parameter, so the description must carry the meaning, and it does: it names the argument a public page slug and supplies concrete shape examples ('learn/xml-namespaces-explained', 'about', 'home'). That clarifies path-style formatting and the absence of leading slashes in a way the bare minLength/maxLength schema cannot.

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 gives a specific verb and resource ('Read one public XSDHub page as Markdown') plus the returned artifact (canonical source URL). 'One' versus the search_/list_ siblings hints at single-item retrieval, but it never names search_xsdhub_guides explicitly, so differentiation is left partly implicit.

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 implied rather than stated: the agent can infer this tool applies when it already has a page slug. There is no explicit 'use this instead of search_xsdhub_guides when you already know the slug' routing, and no exclusion for non-public pages.

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