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

Annotations indicate readOnlyHint, idempotentHint, and non-destructive nature. The description goes beyond by specifying the character cap (20000), the contentFormat field's semantics, and the excluded data (organization ids, translator ids, deprecated slugs, embeddings, arbitrary metadata). It also reveals the consistent 'not found' result for other organizations, which is critical behavioral nuance not captured in 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 moderately long but each sentence carries distinct information: what is fetched, the cap, the contentFormat, the cross-org behavior, and what is never returned. It is front-loaded with the core purpose and avoids redundancy. No fluff, though it could be slightly tighter by merging the first two sentences.

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 an output schema present, the description need not detail every return field, but it does cover the key aspects (article text cap, contentFormat) and explicitly lists excluded data. It also addresses a likely edge case (documents owned by other organizations). This is sufficient for an agent to correctly invoke the tool and interpret results. Minor gap: the locale default (en) is only in the schema, not the description.

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% – each parameter (slug, locale, documentId) already has a description. The main description references slug and documentId conceptually but adds no new meaning beyond the schema. Since the schema fully documents the parameters, 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 states a precise action (fetch one document) with specific resource (support document owned by the authenticated organization) and distinguishes itself from sibling tools like search_documents or list_documents by emphasizing 'one' document. It also names the returned fields (article text, contentFormat), making the tool's role unambiguous.

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 clearly implies usage for fetching a single document by slug or ID, and mentions the bounded 'not found' result for documents owned by other organizations. While it doesn't explicitly contrast with alternative tools (e.g., list_documents for listing), the single-document focus is evident. The cross-organization note adds useful context for when this tool is appropriate.

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