extract_kpis

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

No annotations are provided, so the description carries full behavioral burden. It usefully discloses that queries support defaults (step, frame, aggregation, region) and that the output is a 'structured Markdown KPI report.' However, it does not mention side effects, error behavior, read-only guarantees, or performance implications. It adds meaningful context but omits a full behavioral picture.

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 well-organized: a one-sentence purpose, followed by a bulleted breakdown of the query object, a concrete example, and the return type. Every section serves a purpose. It is somewhat long due to the necessary parameter detail, but it is front-loaded and scannable.

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?

Given the complex, nested `queries` parameter and lack of annotations, the description is mostly complete but leaves a critical ambiguity: the schema defines `queries` as a string, while the description calls it a 'JSON array.' It never explicitly states that the parameter must be a JSON-encoded string. It also omits any mention of the `timeout` parameter. The output schema exists, so return values need not be detailed, but these gaps prevent a higher score.

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?

With 0% schema coverage, the description must compensate. It does so extensively for the `queries` parameter, defining each field, optional status, defaults, and providing a JSON example. However, it does not explain `timeout` semantics and only implies that `odb_path` is the file path. The bulk of complexity is covered, justifying a 4.

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: 'Extract KPIs from an ODB file using declarative queries.' This clearly identifies the tool's function. However, it does not explicitly distinguish itself from similar siblings like get_field_output_summary or get_xy_data, so it falls 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 provides detailed query syntax and defaults, but gives no guidance on when to use this tool versus alternatives. Sibling tools like get_field_output_summary, get_history_output, and get_xy_data could overlap, yet no conditions or exclusions are mentioned. The usage is only implied by the KPI-oriented purpose, not explicitly stated.

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