Compare financials

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

The annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description does not need to restate safety. It adds behavioral context by noting 'Rows are returned in the order given, with currency per company — no ranking or judgement.' This clarifies output ordering and the lack of derived ranking, which is valuable beyond the annotations. This is a good complement to annotations.

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 two sentences, front-loaded with the core purpose and a clear behavioral note about ordering and currency. Every word adds value; there is no fluff or repetition. This is a model of conciseness.

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 tool's complexity is moderate (4 params, output schema present, annotations cover safety), the description is largely complete. It covers purpose, ordering, and lack of ranking. The only minor gap is the lack of explicit mention of currency handling details (e.g., currency codes) and whether metrics are normalized across companies, which might be inferred from the schema example. But with an output schema present, this is sufficient.

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 75%, covering the key parameters (metrics, tickers, period, frequency) with examples. The description adds the concept of 'side-by-side' and the ordering constraint, but does not elaborate on parameter formats beyond the schema. Since the schema already does heavy lifting, a 4 is appropriate—it adds some value without being redundant.

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 the tool does side-by-side comparison of metrics and ratios for multiple companies in a single call, which is precise and clearly distinguishes it from related tools like get_financials or get_metric_history that handle individual companies or histories. The explicit mention of 'several companies' removes ambiguity about its scope.

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 implies usage for multi-company comparisons, but does not explicitly state when to use this tool versus alternatives like get_financials or get_metric_history. It does mention no ranking or judgement, but lacks clear exclusions or guidance on when to prefer siblings. Given the large sibling list, a brief note on alternatives would help.

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