suggest_spec

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

With no annotations, the description fully carries the burden. It details the introspection primitives, return format (JSON with spec and note), default tolerance bands, and what is not captured. This provides comprehensive behavioral insight for an AI agent.

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 a single paragraph that packs substantial information without being verbose. It front-loads the main purpose, but the density of details could benefit from slight structuring (e.g., bullet points) for easier parsing.

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?

Given the tool has one simple parameter and an output schema exists, the description covers the core functionality, return structure, and limitations. It lacks explicit details on the output schema fields but is otherwise complete for an AI agent to understand usage.

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 single parameter object_name has no description in the schema (0% coverage). The description compensates fully by explaining it comes from show() and defaults to the current shape, adding essential context beyond the schema's type and default value.

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 tool drafts a starter design-intent spec from a shape, using the verb 'Draft' and the resource 'design-intent spec'. It distinguishes from the sibling tool verify_spec by explicitly mentioning it avoids authoring from scratch, and lists the primitives used, making its scope precise.

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 explains the tool is for editing detected values before passing to verify_spec, providing clear use context. It also notes what is not captured and suggests manual addition, but does not explicitly mention when not to use or compare to other siblings besides verify_spec.

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