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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), but the description adds substantial non-obvious behavior: completed_at is only written by certain paths (day close, this MCP, reminders, ClickUp sync) and is skipped when a task is marked done from the app, so ordering falls back to updated_at. That is exactly the kind of data-reliability context annotations cannot convey.

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 well-organized: what it is, what it answers, alternatives, then a bolded caveat. The caveat paragraph is dense but every clause carries real information. Slightly long, but nothing reads as padding.

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?

No output schema exists, so the description does some of that work by explaining ordering and the completed_at fallback. Combined with the annotations and the 80%-covered schema, an agent has enough to call it correctly; return shape and pagination remain unstated but are minor for a filtered list.

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 80% with descriptions on limit, status, workspace_id and milestones_only, so the schema does most of the work. The description reinforces the status meaning (completed/cancelled) and the ordering logic but adds no syntax or format detail beyond what the schema provides. Baseline 3 is appropriate.

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+resource with scope: closed (completed and cancelled) tasks ordered most-recent-first. It explicitly distinguishes itself from get_tasks (open ones) and generate_report (written report). It does not, however, differentiate from the very close sibling get_completed_tasks, leaving one ambiguity.

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?

Provides explicit usage context ('answers what did I do this week'), names two alternatives (get_tasks, generate_report), and even states a when-not ('not useful for counting how many I closed on Tuesday without clarifying'). It omits any mention of the near-identical get_completed_tasks sibling, which is a real routing gap.

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