crop_document

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false). It discloses that no upload occurs and the original is not overwritten, that PDFs reuse existing page rendering with no extra scaling/rotation and output page-1 PNG, that identical source bytes/region are reused while changed copies are rejected, that deleting the parent document removes this descendant, and that crops are not auto-recognized or PI-redacted.

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-loads the core action and its most important constraint (no upload, no overwrite), then layers in sequencing, reuse, and lifecycle facts. Dense but nearly every sentence adds distinct, decision-relevant information; a little consolidation would help, but nothing is padding.

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?

An output schema exists, so return values need not be described, and the annotations already cover the safety/idempotency profile. Within that context the description supplies the crop-vs-OCR coordinate constraint, the read_evidence/parse_document follow-up path, nesting/parent-tracing rules, and delete-cascade behavior — everything an agent needs to invoke and sequence this tool correctly.

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?

With 0% schema description coverage, the description must carry the load, and it does add key semantics: region must be a normalized region of the original page rather than raw OCR coordinates, and coordinates of the result belong to the crop (parent tracking via the crop field, traced layer by layer when nested). It still does not spell out the exact box ordering/coordinate range, so it stops short of fully defining the Region object.

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 specific verb and resource: locally crops a specified region of a page and returns an independent document_id plus parent page/hash/pixel bounds. It also distinguishes itself from siblings by explicitly clarifying it does not upload or overwrite the original, and by naming read_evidence and parse_document for the follow-up steps.

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?

Gives explicit sequencing (view the original page first, then pass a normalized region of the original page) and an explicit prohibition (cannot pass OCR coordinates of unknown orientation). It also routes follow-up work: use read_evidence to view the crop, and parse_document only if recognition is genuinely needed, noting this adds a new upload rather than being a free retry.

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