cantrip_history

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds some context: it describes the audit trail as 'append-only' (implying read-only, historical data) and mentions filesystem constraints for the 'project' parameter. However, it lacks details on permissions, rate limits, error handling, or the return format (especially critical since there's no output schema). For a query tool with no annotations, this leaves significant behavioral gaps.

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 highly concise and well-structured: two sentences that efficiently convey the tool's purpose and key parameter usage. Every word earns its place, with no redundancy or fluff. It's front-loaded with the core functionality, making it easy to scan and understand quickly.

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's complexity (a query with 5 parameters, no annotations, and no output schema), the description is incomplete. It adequately explains what the tool does and gives some parameter context, but fails to describe the return format or behavioral constraints (e.g., pagination, error cases). For a query tool without output schema, the description should ideally hint at the response structure to be fully helpful.

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 schema already documents all 5 parameters thoroughly. The description adds minimal value beyond the schema: it clarifies the 'project' parameter's purpose ('overrides .cantrip.json') and contextual use case ('cloud-hosted or multi-project contexts'), but doesn't provide additional semantics for other parameters. This meets the baseline for high schema 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 tool's purpose: 'Query the append-only audit trail of all actions taken on the project.' It specifies the verb ('query') and resource ('audit trail'), and mentions the 'append-only' nature, which adds useful context. However, it doesn't explicitly differentiate this audit trail query from sibling tools like cantrip_meter_history or cantrip_snapshot, which might also involve historical data retrieval.

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 some usage guidance: it explains when to use the 'project' parameter ('useful in cloud-hosted or multi-project contexts') and hints at a default behavior ('.cantrip.json'). However, it doesn't offer explicit when-to-use vs. when-not-to-use advice, nor does it mention alternatives among the many sibling tools (e.g., cantrip_meter_history for meter-specific history). The guidance is implied rather than comprehensive.

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