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

Beyond annotations (read-only, idempotent), the description discloses key behaviors: returns markdown with page markers, preserves PDF download link, truncation for large texts, and OCR pending warnings for scanned documents. This adds significant transparency about the tool's runtime behavior.

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 concise, with the main purpose stated up front, followed by important usage notes. It is well-structured and free of fluff, conveying all necessary information in a few 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?

Given the minimal schema (no parameter descriptions, no output schema) and the annotations (read-only, idempotent), the description covers all essential aspects: what it returns, how to identify the resource, pagination handling, and special cases like OCR. It is complete for effective use.

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 description explains the meaning of the required parameters (cnpj, ano, sequencial) as a reference from pncp_buscar, and clarifies the optional page-range parameters (de_pagina/ate_pagina) for pagination. Since the schema has no descriptions, this provides essential semantic context that the raw schema lacks.

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's purpose: returns the full text of an edital in markdown format, distinguishing it from sibling tools like pncp_buscar or pncp_detalhe. It specifies the action (read/summarize) and the resource (full document).

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 explicit usage context: the identifiers (cnpj+ano+sequencial) come from pncp_buscar, and it explains when to use pagination (de_pagina/ate_pagina) for large documents, plus the OCR warning for scanned files. This clearly guides when to invoke this tool vs alternatives.

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