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

With no annotations, the description must carry behavioral disclosures. It only says 'Path discarded,' which is vague—does it mean the URL path is omitted from output, or the 'path' parameter is ignored? It doesn't disclose whether the tool validates, normalizes, returns components, or has side effects.

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 only two short sentences and front-loads the main verb 'Parse.' 'Path discarded' is cryptic and may not earn its place, but the overall size is appropriate for a simple parse tool. Could be clearer with a small rewrite.

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?

Despite 100% schema coverage, the tool has 9 optional parameters and no output schema; the description doesn't state what the parsed output looks like or which parameter(s) to supply. An agent cannot determine whether this is validation, extraction, or normalization, or what to do with the other parameters. This is incomplete for a tool with this complexity.

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 descriptions already cover all 9 parameters, so baseline is 3. The description adds that the URL should be a Figma file URL, narrowing the generic 'HTTPS URL to normalize or cite' schema description. However, it does not explicitly map 'Figma file URL' to the url parameter or explain the role of the other params.

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 the action 'Parse' and the resource 'Figma file URL', making the core purpose clear. It does not explicitly differentiate from sibling shape tools, but the resource type is specific enough. 'Path discarded' creates minor ambiguity but does not obscure the main purpose.

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 this is for Figma file URLs, which is useful for selecting among siblings like github-repo-shape or domain-shape. It does not explicitly state when not to use it or name alternatives. No conditions, prerequisites, or exclusions are provided.

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