drawing_overlay

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

Annotations only declare readOnlyHint/openWorldHint; the description adds real behavioral context the annotations don't carry: the returned artifact is a PNG path, the sketch must trace the black geometry, and the title-block scale may be wrong so pixel/model alignment must be cross-checked. It does not mention file overwrite behavior for out_png, a minor gap.

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 action and the return value, then the workflow cue and the argument formats. Dense but every clause carries information; the emphasis-heavy phrasing ('BEFORE', 'LOOK', 'WRONG') is slightly informal but not wasteful.

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 10-param tool with no output schema, the description covers the sketch input format, axis mapping, the return artifact, and a caveat about scale detection. The remaining parameters (dpi, page, region, origin, out_png) are documented in the schema, so nothing an agent needs to call it is missing.

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 80% (baseline 3), and the description goes beyond it by explaining the accepted `sketch` forms (catia_sketch_profile object {start, segments}, a single entity, or a list) and the `hv` axis-mapping notation 'h,v', '-h,v', 'v,h'. This compensates for the sketch param whose schema description just says 'see description'.

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 ('Draw a CATIA sketch on top of the PDF drawing') and the return value ('return the PNG path'), which clearly distinguishes it from drawing_render and drawing_extract_geometry. The added constraint 'the coloured sketch must follow the black drawing lines everywhere' sharpens intent but sibling differentiation is left implicit.

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 an explicit workflow condition: 'Do this for every non-trivial profile BEFORE pad/shaft, then LOOK at the image.' That tells the agent when in the pipeline to call it. It does not name a competing tool to use instead, so it stops short of a full when/when-not statement.

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