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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description does add genuinely non-obvious context about the backend storing KaneAI runs as type "Manual" and instructing use of run_type instead of type, which is valuable. It stops short of covering pagination behavior for the list mode.

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 dense sentences with no filler. The primary routing rule is front-loaded, and the caveat about run_type is placed last where it matters most for interpretation.

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 no output schema, the description shoulders the return-value burden and does describe the detail payload (instance counts by status, pass rate). Pagination semantics for the list branch (page/limit) are left to the schema, a minor gap.

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 100%, so the baseline is 3. The description goes beyond the schema by clarifying the run_id-vs-project_id dependency and by warning that run_type, not the backend's type field, is the reliable discriminator — real added meaning.

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?

States a specific verb and resource and distinguishes the two operating modes: run_id yields a single run's detail plus result summary, while project_id lists runs with filters. An agent knows exactly what it will get without opening the schema.

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 routes usage: pass run_id for one run, otherwise pass project_id to list. The alternative branch and the selecting condition are both stated, so no inference is required.

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