Add a project or area

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

With no annotations provided, the description carries the full burden. It discloses a key behavioral trait: 'The scope line is what routing is judged against', and advises how to phrase the scope. It does not, however, mention side effects, reversibility, permissions, or any other behavioral aspects. The routing detail is valuable but the overall disclosure is incomplete for a mutation tool.

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 two concise sentences that front-load the purpose and then deliver actionable guidance. Every sentence earns its place; there is no fluff or redundancy. It is appropriately sized and easy to scan.

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 simplicity (3 required parameters, full schema coverage, no output schema), the description covers the essential aspects: what the tool does, the distinction between project and area, and the critical routing behavior. It does not describe return values or error conditions, but these are less critical without an output schema. The description is nearly complete for the tool's 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 coverage is 100% with each parameter having a description. The description adds meaningful semantics beyond the schema, notably the guidance on scope ('write it as a plain description of what belongs here rather than a title') and the clarification of project vs. area. This enhances the agent's understanding beyond the raw parameter definitions.

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 verb 'Add' and the resource 'project or an area', and explicitly distinguishes between the two ('A project finishes; an area is ongoing'). It explains the purpose ('so captured items have somewhere to go') and even clarifies how the scope parameter is used for routing. This fully clarifies the tool's function without ambiguity.

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 is used after capturing items ('so captured items have somewhere to go') and provides guidance on choosing between project and area. However, it does not explicitly contrast this tool with its siblings (capture, shortlist, mark_done) or state when not to use it. The usage context is implied but not fully explicit.

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