search_tasks

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

Annotations already cover read-only, idempotent, non-destructive and open-world, but the description still adds real value: substring vs fuzzy matching semantics, the truncation contract (truncated=true means results are incomplete), and the paging bounds max_tasks/max_lists. What it omits is the default exclusion of completed tasks, which matters for interpreting results.

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, front-loaded with the matching semantics, then scope, then paging. The closing clause about 'ambiguous name-based mutations' is slightly defensive but does usefully signal this is a read-only path, so little is wasted.

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?

An output schema exists, so return values need not be explained, and truncation is covered. But for a 6-parameter search tool with 0% schema coverage, the description leaves the agent guessing about the completed-task default and the relation between limit and max_tasks, which is short of complete.

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 0%, so the description carries the full burden and only partly does so: it explains task_list_id (null = scan multiple lists) and the max_tasks/max_lists paging caps. It says nothing about query, limit, or include_completed, and the include_completed default of false is a genuinely surprising behavior an agent cannot anticipate from the schema alone.

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 first sentence gives a specific verb (search) plus the searched fields (titles and notes) and the matching semantics (case-insensitive substring), which is more precise than the sibling list_tasks. It never names that sibling or get_task explicitly, so the agent must infer the boundary between searching and listing.

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?

'Omit task_list_id to scan multiple lists' gives one concrete usage rule, which is the strongest guidance present. There is no statement of when to prefer this over list_tasks or get_task, and no prerequisite or exclusion guidance beyond that single line.

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