inspect_sketch_full

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

Even though no annotations are provided, the description discloses substantial behavioral detail: it reads dimensions and constraints via API5, includes COM/API5 diagnostic blocks, can include begin-edit fallback data, and explains status code meanings. It also describes the shape of returned geometry, constraint links, and projection classifications, which goes far beyond what annotations would 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 description is front-loaded with a one-sentence summary and then organized into Parameters and Returns sections. Though detailed, every sentence provides necessary operational or return-structure information for a complex inspection tool, with no filler or redundancy.

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 six-parameter tool with no output schema, the description covers all inputs and every part of the return payload, including status codes, entity geometry formats, constraint owner/partner links, and diagnostic content. An agent has enough detail to invoke the tool correctly and interpret its results; only explicit sibling-selection guidance is absent, which is already covered under usage guidelines.

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?

The input schema provides only names, types, and defaults, with 0% description coverage. The tool description fully compensates by explaining each parameter's purpose and effect, including document_id None meaning the active document, the 22 constraint types enumerated, what include_diagnostics adds, and that max_items caps entities per collection.

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 opens with 'Full dump of an existing sketch: entities, dimensions, constraints, status,' which names a specific verb, resource, and scope. 'Full dump' distinguishes this from sibling tools that inspect individual entities or list only one category of sketch data, so the tool's purpose is immediately clear.

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 tool should be used when a complete sketch inspection is needed, but it does not explicitly state when to prefer it over list_sketch_entities, inspect_sketch_entity, list_sketch_dimensions, or list_sketch_constraints. There is clear context about what it does, but no mention of alternatives or exclusion conditions.

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