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

Annotations only provide destructiveHint=false and a title. The description adds meaningful behavior beyond that: the original record remains unchanged and simply appears as unlinked on the board, clarifying that this is a relationship removal, not a deletion. It still omits permissions, idempotency, and error behavior.

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?

A single front-loaded sentence that states the action, the resource, the effect, and the resulting state with no filler. Every clause earns its place.

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 four-required-parameter mutation with no output schema and minimal annotations, the description covers the operation's effect well but is incomplete on source_key semantics and on how callers should choose this tool over link_shared_work_case_source. It is adequate but has clear gaps.

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 clarifies source_type by naming the two supported kinds (ToDo or GitHub Issue) and ties case_id/project_id to 'one case' and 'shared project', but leaves source_key completely unexplained, including whether it is a ToDo id or GitHub issue key.

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 states a specific verb (Remove), the exact resource types (shared project ToDo or GitHub Issue), and the scope (from one case), plus the end state on the board. It is clearly distinguishable from the inverse sibling link_shared_work_case_source and from case-level tools like move_shared_work_case.

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 remove verb and stated effect strongly imply when to use it, but it never names the alternative (link_shared_work_case_source) or states any when-not condition. Usage is inferable rather than explicit.

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