Write the masked (anonymized) drawing PDF

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.