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

The description adds context beyond annotations: it is PROJECT-SCOPED, returns the project identity, patches in place (modifies existing layer), and includes a specific behavior (Pass motion={} to clear keyframes). Annotations indicate idempotentHint=true and destructiveHint=false, which align with the modification semantics. No contradiction found.

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 description is two sentences, front-loaded with the project-scoped caveat. It is concise and to the point, with no fluff. It efficiently conveys the core purpose and a key behavioral detail.

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 tool with 18 parameters and a nested motion object, the description is too sparse. It doesn't explain the motion structure, the meaning of many parameters, or the return value beyond a vague hint. No output schema exists, so the description should provide more guidance on expected results and parameter usage. The tool is complex, and the description leaves significant gaps.

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 only 17% (very low), and the description only mentions a few parameter groups (kind, geometry, palette, progress, motion) without detailing individual fields. It does not explain many parameters like rounding, stroke_width, opacity, etc. The motion parameter is touched upon via the keyframe-clearing note, but the nested structure is not elaborated. The description fails to compensate for the schema's lack of coverage.

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?

The description clearly states the verb 'Patch' and the resource 'an existing vector graphic by id', listing the specific aspects (kind, program window, geometry, palette, progress value, general motion) that can be modified. It explicitly distinguishes itself from stacking a duplicate, which differentiates it from add_vector_graphic. This is specific and 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 description implies the use case: modify an existing vector graphic rather than add a new one. It explicitly notes 'This modifies the existing layer instead of stacking a duplicate,' which contrasts with the add sibling. However, it doesn't explicitly name add_vector_graphic or state when not to use it, but the context is clear enough.

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