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

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description adds meaningful behavioral details beyond annotations: the 500-result cap and the fact that legacy PROJECT/TASK search paths may return null extra fields. It omits the multi-workspace account_id requirement, but overall adds solid context.

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?

The description is front-loaded with the core purpose, then efficiently covers keyword scope, type behavior, and the API cap in three sentences. Every sentence contributes actionable information with no repetition or filler.

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 read-only search tool with full schema coverage and explicit annotations, the description is nearly complete: it covers endpoint, keyword field scope, type modes, null-field caveats, and the result cap. It could mention the account_id multi-workspace requirement or filter semantics, but those are documented in the schema, so the remaining gap is minor.

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 100%, so the baseline is 3. The description adds real meaning beyond the schema by specifying which fields keyword searches across (project/task/customer/custom-field/list/subtask) and by explaining the functional difference between type=ALL and legacy type values, including the potential for null response fields. It does not add semantics for filter or account_id, but the added keyword and type context is valuable.

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 states a specific verb and resource: 'Searches projects and tasks using GET /search/advanced.' It also clarifies that keyword performs free-text search across multiple entity fields, which helps distinguish it from simple list siblings like list_tasks or list_projects. However, it does not explicitly name or contrast with those sibling tools, keeping it just short of 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 description gives useful guidance on the type parameter, explaining when ALL versus PROJECT/TASK should be used and what trade-offs apply. It does not, however, say when to use advanced_search instead of list_tasks, list_projects, or other search-like siblings, nor does it state exclusions or prerequisites beyond what is implied.

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