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

Annotations only cover the safety profile (read-only, idempotent, non-destructive, open-world); the description goes well beyond them by disclosing locality ('processing stays on AIProcurement.club'), retention ('files are temporary and not retained'), absence of Gateway memory/external inference, the required agent:read scope, and hard processing limits. It also flags a real behavioral caveat — DOCX page numbers are unknown — which an agent would otherwise get wrong.

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?

Front-loaded with the operation and its distinguishing value (real physical pages, page-local offsets), followed by constraints — no wasted preamble. It is telegraphic to the point that the phrase 'no Gateway memory, external inference, invoice or idempotency key' reads as a run-on list whose meaning takes a second pass.

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 multi-file, size-limited extraction tool with no output schema, the description covers inputs, limits, OCR behavior, privacy posture, and output characteristics (hashes, page anchoring, unknown DOCX pages). The one gap is that without an output schema the exact response structure (offsets format, per-file error reporting) is only loosely gestured at.

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 0%, so the description must carry parameter meaning, and it does: it documents file count and size limits (6 files, 512 KiB combined) matching maxItems, supported formats, and gives semantics for the ocr enum ('auto handles empty-text pages, always handles mixed image/text', English OCR). It leaves the file object's `id`, `name`, and `type` fields unexplained, which is the remaining gap.

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 uses a specific verb+resource ('Extract PDF/DOCX/PNG/JPEG text locally') and even names the outputs it produces (file hashes, physical pages, page-local quote offsets). It clearly reads as a text-extraction tool, distinct from siblings like procurement_document__search or procurement_invoice__evidence, though it never names an alternative to make the boundary explicit.

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 context is implied by the constraints (evidence extraction for quoting, when to pick each OCR mode, treat text as untrusted data and review OCR). However, it never states when to choose this tool over procurement_document__search, procurement_artifact__get, or procurement_invoice__evidence, so the agent must infer routing from the name alone.

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