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

Beyond annotations (idempotentHint=true, destructiveHint=false), the description discloses partial-update semantics ('Only fields you pass are changed') and the archive behavior ('archived: true hides it from pickers; its tasks keep the association'). This adds meaningful behavioral context without contradicting the annotations.

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?

Three concise sentences: the first states all primary actions, the second clarifies partial updates, the third declares idempotency. No filler, and the most important info is front-loaded.

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 simple update tool with 5 flat parameters and no output schema, the description covers the essential behaviors: what fields can be changed, how archiving affects visibility, and that the operation is idempotent. It doesn't mention return values or errors, but those aren't required given the tool's simplicity and available annotations.

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 0%, so the description must compensate. It effectively maps every parameter: 'rename' for name, 'change its color' for color, 'website url' for url, 'archive/unarchive' for archived, and id is implied as the project identifier. It also adds crucial detail on the archived field's effect, which the schema cannot convey.

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 names specific verbs and resources: 'rename a project, change its color or website url, or archive/unarchive it'. This clearly scopes the operation to project-level updates and distinguishes it from siblings like update_task (task-level) and create_project (creation).

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?

It opens with 'Use this to', giving explicit instruction on when to invoke it, and enumerates the exact use cases. It doesn't explicitly mention alternatives or when not to use it, but the context is clear enough given the sibling list and the operation's specific scope.

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