document_extract

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

Annotations declare readOnlyHint=false with destructiveHint=false and idempotent=true; the description explains why by noting output_path writes everything to JSON, and it discloses the truncation contract ('counts always; lists only for the kinds asked... paged by offset/max_items with the rest stated'). It stops short of covering overwrite behavior or what happens on encoding mismatches.

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 core scope decision in the first clause, then the mechanics. The long parenthetical of kinds is dense but it is enumerating real capability; only the trailing schema-version tag feels like filler.

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, return values need no explanation, and the paging/truncation contract is stated. For an 8-parameter tool the remaining gaps are overwrite conflict behavior and the text_offset/offset distinction, which are minor against the schema.

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 only 25%, so the description must compensate; it does partially by explaining the kinds enumeration and the offset/max_items paging interplay, plus output_path's JSON dump. It adds nothing for overwrite, text_offset, or input_path semantics.

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?

States a concrete verb and resource ('mechanical inventory of one PDF/DOCX/MD/TXT') and immediately distinguishes itself from adjacent tools by declaring it is 'not a substitute for reading it', which routes the agent away from document_read. The enumerated outputs make the scope 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 'not a substitute for reading it' framing implies when to prefer document_read, and the paging note ('the rest stated') implies a browse-large-doc scenario. However no alternatives are named explicitly and no preconditions are given, so the guidance is contextual rather than directive.

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