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

Annotations only declare write/idempotent/non-destructive. The description adds permission requirements (projects:write, whole-workspace access), the idempotency mechanism (a unique requestId reused on retry), a privilege nuance (owner/admin can set workflow without workflows:write), and dedup behavior via source. This is useful context well beyond the structured hints, and it is consistent with idempotentHint=true and destructiveHint=false.

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?

Front-loaded with the core purpose and permission gate, and each subsequent sentence covers a distinct concern (idempotency, context, workflow privilege, import dedup, task routing) with no filler. It is a dense sequence of facts rather than a grouped structure, which keeps it just short of exemplary.

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 nested, 8-parameter mutation with no output schema, the definition covers the critical operational facts an agent needs: auth scope, retry semantics, workflow privilege rules, and import dedup. It does not describe what the call returns (e.g. the created project identifier) or how naming collisions on title behave, which are the remaining unknowns.

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?

With 50% schema coverage, the description meaningfully annotates several parameters the schema leaves thin: requestId (unique, reused on retry), context (goal, constraints, decisions, next actions), workflow (owner/admin only, default statuses when omitted), and source (import dedup). title, dueOn, status, and description still carry no descriptive guidance here, so it compensates for about half the gap rather than all of it.

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?

States a specific verb and resource ('Create a project') plus the scope ('in the authorized workspace'), so the operation is unambiguous. It also draws a boundary against the nearest siblings by noting that tasks go through item_create or items_create, letting an agent separate project creation from task creation without reading either schema.

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?

Gives real usage context: requires projects:write and whole-workspace access, reuse requestId when retrying this exact action, use source when importing to avoid duplicates, and route tasks to item_create/items_create. It lacks an explicit when-not-to-use statement (e.g. when an existing project should be updated instead), but the conditions it does state are actionable.

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