cantrip_next

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

With no annotations provided, the description carries the full burden and adds valuable behavioral context: opportunities persist across calls, re-running updates rather than replaces them, and UUIDs are stable for follow-up actions. It also hints at filesystem dependencies with the project parameter override. While it doesn't cover rate limits or error handling, it provides meaningful operational insights beyond basic functionality.

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 efficiently structured with four sentences, each adding distinct value: purpose, UUID usage, persistence behavior, and parameter guidance. It is front-loaded with the core function and avoids redundancy, making every sentence earn its place without wasted words.

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 1 parameter with full schema coverage, no output schema, and no annotations, the description does well by covering purpose, behavior, and parameter context. It addresses complexity around opportunity persistence and project overrides. However, it lacks details on output format or error cases, leaving minor gaps for a tool with no structured output documentation.

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 description coverage is 100%, so the baseline is 3. The description adds significant value by explaining the project parameter's purpose: 'overrides .cantrip.json — useful in cloud-hosted or multi-project contexts' and ties it to filesystem constraints. This contextualizes the parameter beyond the schema's technical description, justifying a higher score.

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's purpose: 'List gap-analysis opportunities — things that would move the project closer to ideal state.' It specifies the verb ('List') and resource ('gap-analysis opportunities'), and distinguishes it from siblings by mentioning UUIDs for cantrip_next_prompt/run. However, it doesn't explicitly differentiate from other listing tools like cantrip_history or cantrip_snapshot, preventing a perfect score.

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 provides clear context for usage: 'Review the project snapshot with the user before running opportunities' and explains when to use the project parameter ('useful in cloud-hosted or multi-project contexts'). It also implies alternatives by referencing cantrip_next_prompt/run for acting on opportunities. However, it lacks explicit exclusions or comparisons to other sibling tools like cantrip_snapshot for project review.

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