Search test runs

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

The annotations provide readOnlyHint: true, but the description adds no behavioral information beyond that. It does not disclose pagination or return format, sorting, or how filters combine. The description essentially restates the schema's filter fields, offering no new insight into the tool's runtime behavior.

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?

One terse fragment condenses the tool's purpose and filters into a single line. No wasted words, front-loads the resource ('TestRun') and action ('filter').

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?

The tool is a simple list/filter operation with full schema descriptions and a read-only annotation, but lacks an output schema. The description does not mention that it returns a list of runs, how many, or the default behavior when no filters are applied. However, the name and schema infer the basics. It is adequate but not complete for an agent to fully understand the tool's behavior without further inference.

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?

All 6 parameters have descriptions in the schema, achieving 100% coverage. The description merely lists the filter fields (summary, plan, build, product, still open) without adding extra semantic detail. It omits the 'limit' parameter entirely. Therefore, the description adds no value beyond the schema, but the schema is complete, so a baseline of 3 is warranted.

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 'TestRun.filter by summary, plan, build, product, and whether still open,' which clearly identifies the tool as a search/filter operation on TestRun entities. It lists specific filter dimensions, distinguishing it from sibling tools like kiwi_create_run or kiwi_list_executions. The title 'Search test runs' reinforces this.

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 provides no explicit guidance on when to use this tool versus alternatives such as kiwi_run_status or kiwi_list_executions. The filter criteria imply usage for searching/filtering runs, but no exclusions or alternative recommendations are given. Context is only implied by the name and title.

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