search_comments

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

The annotations declare readOnlyHint=true, and the description is consistent with a read-only search operation. The description adds the project-scoping behavior, but provides no detail on filtering semantics, limits' effects, or what is returned.

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 a single front-loaded sentence with no wasted words. However, it is so brief that it omits useful behavioral details, making it concise but not fully 'appropriately sized' for an agent.

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?

With five parameters, optional filters, no output schema, and sibling tools that overlap in purpose, the description is too sparse. It does not explain search semantics, defaults, return shape, or when to prefer list_task_comments or search_tasks.

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 only 40%, covering the two limit parameters. The required project_gids is understandable from its name, but task_text and comment_text have no description and the tool description does not explain how they are used, whether filters combine, or what matching logic applies.

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 identifies a specific verb ('search'), a resource ('comments'), and a scope ('across selected projects'). This distinguishes it from list_task_comments, which implies per-task listing, though it does not fully explain the search criteria or differentiate it from search_tasks.

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?

There is no explicit guidance on when to use this tool versus its siblings. The phrase 'across selected projects' hints at multi-project search, but no exclusions or alternatives are mentioned, so an agent must infer usage from sibling names alone.

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