compare_etf_snapshots

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

With no annotations, the description carries full responsibility for behavioral disclosure. It does state one important constraint ('never emit a buy recommendation'), but it fails to mention other traits such as whether the tool makes external calls, requires authentication, handles invalid JSON, or has side effects. This is minimal disclosure.

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 one concise sentence that front-loads the purpose and includes a useful guardrail. Every word earns its place, with no redundant information.

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 has two JSON inputs and an output schema, but the description is too terse to fully guide an agent. It omits input format expectations, potential errors, and when to prefer this tool over siblings. The description relies heavily on the tool name and schema to convey completeness.

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 0%, and the description does not explain what left_json and right_json should contain or how they map to 'comparable ETF facts'. The parameter names imply two ETF snapshots, but the description adds no additional detail about expected format or structure.

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 uses a specific verb ('Return') and clearly identifies the resource ('comparable ETF facts and warnings'). The tool name 'compare_etf_snapshots' reinforces the comparison function, distinguishing it from siblings like validate_etf_snapshot and audit_backtest_report.

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?

No guidance is given on when to use this tool versus the siblings. The description does not mention scenarios, alternatives, or exclusions. The only extra instruction ('never emit a buy recommendation') is a behavioral constraint, not usage context.

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