restore_milestone

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true), so the description only needs to add effect detail, and it does: the milestone returns 'with all its properties and associations intact'. It omits permissions/auth needs, what happens on a non-trashed or already-restored id, and is in mild tension with destructiveHint=true given that restoring is a recovery rather than a destruction.

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 and short, with the operative verb and precondition in the first two sentences. The first two sentences are somewhat redundant ('Restore a milestone. Restore a previously deleted milestone...'), which costs a point but the rest is efficient.

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 single-parameter mutation whose annotations already carry the safety profile, the description supplies the precondition (must be in the trash) and the outcome (full recovery of properties and associations). Only edge-case behavior (errors on already-restored ids, permission requirements) is left uncovered, which is minor here.

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 reported at 0%, and there is a single nested parameter (path.milestoneId). The description only says 'using its unique identifier', which restates the schema's own 'The milestone identifier.' label without adding format, type, or source detail (e.g. where the id comes from, whether it is the integer project-scoped id).

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 a specific verb (restore) and resource (milestone), and the second sentence narrows the scope to a soft-deleted item taken 'from the trash', which cleanly separates it from delete_milestone, put_milestone and post_milestone. It stops short of explicitly naming any sibling as the alternative, which is the only thing keeping it from a 5.

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 phrase 'previously deleted milestone from the trash' implies the precondition for use, so an agent can infer this applies only to trashed milestones. However, there is no explicit when-to-use guidance, no statement of what to do if the milestone was never deleted, and no pointer to delete_milestone as the inverse operation.

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