search_tasks

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

No annotations provided, so description carries full burden. It states 'Read-only', matching behavior (case-insensitive substring), field defaults and possible values (description, project, tags, any UDA name), and returns tasks as JSON. No contradictions.

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?

Description is about 6 sentences, starting with purpose, then behavior, then details. No fluff. Well-structured and 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 2-param search tool with no annotations and output schema, description covers param semantics, behavior, and usage guidance. Missing minor details like pagination or empty result behavior, but overall adequate.

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 description adds essential meaning. It explains 'query' is the search string, 'field' defaults to 'description' and lists valid values (project, tags, UDA names), and notes field must exist in schema or be built-in.

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 clearly states it searches tasks by matching a query against a specific field. It specifies the verb 'search' and the resource 'tasks', and explains matching is case-insensitive substring. It distinguishes from list_tasks by mentioning filter syntax vs free-text search.

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?

Explicitly states when to use this tool: for free-text search when filter syntax is insufficient or when searching across a UDA field. It advises using list_tasks for structured queries and explains field defaults and valid values.

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