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

Goes well beyond the annotations: quota (1 free analysis/day/IP), retention (files deleted within 24h, nothing else stored), latency (10–120 s), timeout behaviour with status "processing" plus resumable drawing_id, and session-level caching. The idempotentHint=false annotation is not contradicted — caching an identical PDF in-session is distinct from idempotent mutation semantics.

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 purpose and return shape, then quotas and retention last. Dense but nearly every clause carries information; the only mild redundancy is restating the wait/timeout behaviour in both the timing sentence and the upload sentence.

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, the description compensates by enumerating returned fields (detection id, category, value, page, box, confidence, title-block flag, masked flag, page sizes). Inputs, cost, and retention are covered; only error/failure handling is left unstated.

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%, so the baseline is 3, but the description adds relationships the schema states only locally: that drawing_id resumes an earlier call that returned "processing" without a new upload, that timeout_seconds caps the wait before returning "processing", and that up to 4 pages count as a single drawing.

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?

Opens with a specific verb and resource: 'Upload a technical-drawing PDF to Imnoo's drawing analysis and return the sensitive data it finds', then enumerates exactly what is detected. It separates itself from siblings by stating that memory-cached re-analysis avoids a new upload and that masking runs locally, making it distinguishable from load_analysis and mask_drawing.

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 real operating context: 1 free analysis per day per IP, identical PDFs served from session memory without re-upload, and the drawing_id resume path. It falls short of explicitly naming when to prefer `load_analysis` or `mask_drawing` over this call, leaving that routing to be inferred.

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

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

Annotations only declare readOnlyHint/openWorldHint=false; the description adds real value beyond them by disclosing that this performs no upload, consumes no daily credit, and has the side effect of registering the drawing so review_masking and mask_drawing can consume it. That registration side effect, not visible in annotations, is exactly the kind of context an agent needs before calling.

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?

Three tight sentences, front-loaded with the action and result, then constraints, then the parameter hint. The parenthetical about the Imnoo FileStore document and the pdf_path clause both earn their space as disambiguation.

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 and thin annotations, the description carries most of the burden and does so well: it covers the source of the JSON, offline behavior, the registration side effect, and the prerequisite for downstream tools. The return value/registered-id behavior is only lightly implied rather than stated.

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%, so the baseline is 3, but the description goes further by explaining why pdf_path matters across tools ('masking needs the original PDF, and custom terms search its text') rather than merely restating 'needed to write the masked PDF'. It adds little about drawing_id beyond the schema's stated default.

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+resource ('Open a drawing analysis JSON saved earlier') and immediately names the downstream siblings it feeds (review_masking, mask_drawing) plus the producer (analyze_drawing with save_analysis_to). An agent can distinguish this from analyze_drawing without opening either schema.

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?

Clear about context: use this when the analysis JSON already exists, and it is 'fully offline — no upload, no daily credit', implicitly routing the agent away from re-running analyze_drawing. It also gives a concrete calling rule ('Pass pdf_path as well: masking needs the original PDF'). It stops short of an explicit when-not-to-use statement.

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

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

Far exceeds the annotations: it discloses that pages are rasterized at 288 dpi so covered content is destroyed (tamper-proof single-layer PDF), that metadata (author, title, producer, XMP) is stripped, that share_link uploads only the MASKED copy with explicit expiries, and that the source is never modified. It also gives the default output location and naming. This is rich, non-obvious behavioral context the structured fields do not carry.

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 primary action and every sentence carries distinct information, but it is a single dense block with several embedded clauses. It is appropriately sized for a complex masking tool, though light structuring (grouping the secure/rasterize, share, and output concerns) would improve scanability.

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 nested-schema tool with no output schema, the description covers the important externals: what the output is, where it lands, how naming works, what share_link returns (an expiring public link), and that the original is untouched. An agent has what it needs to invoke correctly without opening 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 coverage is already 100%, so the baseline is 3, but the description adds meaning beyond the field docs: 288 dpi rasterization, the masking-reuse rule, share_link link lifetimes, and default output naming/location. It ties drawing_id back to its producers (analyze_drawing/load_analysis), which helps the agent source the value correctly.

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 up front — 'Mask the drawing and write the anonymized PDF' — and immediately scopes it with what gets covered (detections, terms, rectangles) and how (blank/replacement/logo boxes). An agent can tell this is the write/output stage of the pipeline, distinct from analyze_drawing (analysis) and review_masking (review).

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?

Explains the two entry paths clearly: drawing_id from analyze_drawing/load_analysis, or pdf_path for a one-shot run that analyses first. It also covers the reuse case (omitting masking for a previously masked drawing, including an identical PDF under another path) and states the source PDF is never modified. It never explicitly routes against review_masking as an alternative, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, but the description adds substantial context: nothing is written, the run is deterministic and offline, and it enumerates exactly what the preview surfaces (masked vs visible detections, term matches, rectangles, stamp, pages, anonymity score with warnings, output file name, visible_text_after_masking). This is far beyond what the annotations convey.

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 purpose and the dry-run distinction are front-loaded, and the long enumerated sentence earns its length because there is no output schema. Slightly dense, with the output list packed into one very long sentence, but no 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 no output schema, the description must explain the return payload, and it does so thoroughly (detections masked/visible, term matches, anonymity score, visible_text_after_masking, etc.). Combined with a fully documented input schema and readOnly annotations, an agent has everything needed to call it 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?

Schema description coverage is 100%, so the schema already documents every parameter (mode, terms, rectangles, etc.), and the description largely restates 'mode "replace"' rather than adding syntax or format meaning. Baseline 3 applies when the schema does the heavy lifting.

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 action (compose the masks for an analysed drawing exactly as mask_drawing will, without writing anything), which is a dry-run/preview of the sibling mask_drawing. An agent can distinguish it from analyze_drawing, load_analysis and mask_drawing without opening any schema.

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 a concrete use case (find leftovers like a customer name in notes or a person the analysis missed, then add them as terms or rectangles) and implicit contrast with mask_drawing via 'without writing anything' and 'iterate freely'. It stops short of an explicit 'use this before mask_drawing, not instead of it' routing statement, so not a full 5.

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