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

Annotations already declare readOnly=false, idempotent=true, destructive=false, so the safety profile is covered. The description adds real value beyond that by disclosing the lock-gated rejection behavior, which is not expressible in the annotation set. It stops short of describing the failure response or whether both fields can be sent together.

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 short sentences, zero filler, with the primary operation stated first and the lock constraint last. Nothing repeats the title or the annotations.

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 three-parameter mutation with no output schema, the description covers the identifier source and the main operational blocker. The remaining gap is what happens when only subgoal_id is passed with neither `done` nor `text`, which an agent could plausibly attempt.

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 only 33% (just subgoal_id documented), so the description must compensate more than it does. It does implicitly map the two undocumented fields — "tick ... done" explains the `done` boolean and "rename" explains `text` — but it omits that at least one of them must actually be supplied and never mentions the 500-character cap on `text`.

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 concrete verb+resource pair — toggle a subgoal's done state or rename it — which is clearly narrower than update_goal and distinct from delete_subgoal. It never names a sibling explicitly, so the differentiation is implicit through scope rather than routing guidance.

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?

"Ticking is refused while the goal is locked" is an explicit when-not condition, and "Subgoal ids come with each goal" tells the agent where the prerequisite identifier originates. There is no guidance on when to prefer this over update_goal or delete_subgoal, but the precondition coverage is genuinely useful.

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