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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description goes well beyond that by disclosing two refusal conditions (already-linked pair, foreign workspace), that failures write nothing, and that is_primary=true demotes the task's other live links. The promotion-demotion side effect is exactly the kind of consequence an agent cannot infer from annotations or schema.

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 purpose, then when-to-use, then the required/optional split, then edge cases — a sensible order with no wasted preamble. It loses a point for restating 'REQUIRED: task_id, project_id' and for a Returns sentence that duplicates the existing output schema.

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 write tool with 7 parameters, three refusal paths, and a side effect on other rows, the description covers the failure modes, the idempotent retry story (via schema), and the return shape. The only gap is that it never mentions the multi-workspace/token plumbing that makes workspace_id and conversation_id consequential, though the schema handles those adequately.

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%, so the baseline is 3, but the description earns a bump by adding semantics the schema only partly carries: 'Omitting is_primary never promotes a link, and the tool never infers primary status from the order projects are named in' closes a real ambiguity about implicit behavior. It says nothing about workspace_id, conversation_id, or idempotency_key, but those are fully documented in the schema, so no compensation is owed.

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 with scope baked in: 'Link a task of the current workspace to a project of the same workspace.' That single clause distinguishes it from well_create_task (creates tasks) and well_delete_task_project (unlinks), and the same-workspace constraint is a real disambiguator rather than filler.

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 explicit triggering conditions ('when the user says a task belongs to a project, or asks to move a task under a project'), tells the agent to resolve ids first via the task list and well_list_projects, and names well_delete_task_project as the inverse. It also pre-empts the most likely wrong call by spelling out the remove-then-relink recipe for promoting an existing link to primary.

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