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

Even with readOnlyHint, idempotentHint, and destructiveHint=false annotations, the description goes well beyond them: it states the tool never embeds bytes and never returns base64, only reads metadata, and requires a resource-capable MCP client for bytes. It explicitly discloses that tool-only clients cannot obtain the file, which is valuable behavioral context beyond 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 dense and mostly front-loaded: purpose first, output type second, metadata-only behavior third, and workflow fourth. Almost every sentence earns its place. There's slight redundancy between 'never downloads' and 'can see this result's metadata but cannot obtain the file,' but it's honestly more clarifying than wasteful. A tight 4.

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 to fall back on, the description fully compensates: it states the exact return shape (resource_link) and its type (company-document:// MCP resource), what metadata fields are available (company, category, page count, size, content types), and the prerequisite steps. This is exactly the completeness needed for a 2-param, no-output-schema resolver 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%—both params are documented in the schema. The description adds semantic nuance beyond the schema by asserting the URL must be passed verbatim and must be an exact document-api URL, and by contextualizing mime_type selection as needing to only be set when multiple representations exist. This is valuable on top of 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 opens with a specific verb-resource pair: 'Resolve a filing's document_metadata link to its authoritative source document.' It clearly distinguishes this from siblings like dd_company_filing_history by explaining that this tool converts the discovered metadata URL into a concrete resource_link rather than listing filings or downloading content.

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 workflow guidance is provided: 'Use company_filing_history first to find a filing's document_metadata URL,' with follow-on instructions to fetch the actual PDF via resources/read. The description also warns about client capability constraints, telling tool-only clients exactly what they can and cannot do, which is clear when-to-use and when-not-to-use information.

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