get_roi_analysis

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

No annotations are provided, so the description carries the full behavioral burden. 'Get' and 'result' strongly imply a read-only lookup, and the parenthetical discloses the return fields (findings, estimated $ savings, status, timestamps), which is genuinely useful. It says nothing about behavior for an unknown ID (error vs empty), permissions, or whether the analysis data is ever mutated, leaving real gaps for an annotation-free tool.

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 compact sentence, front-loaded with the action and resource, with the return contents injected as a parenthetical rather than a second sentence. Nothing is wasted.

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?

There is no output schema, and the description compensates by naming the returned fields (findings, estimated $ savings, status, timestamps). For a single-record lookup, that is nearly everything an agent needs; only error/missing-ID behavior is absent.

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%, so the description must carry the parameter. It does tell the agent that the ID identifies a specific ROI analysis result, but adds no format, source, or example for the analysis_id value, and the schema gives only a bare string with no title detail.

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 gives a specific verb and resource: 'Get one ROI analysis result by ID', with the parenthetical enumerating the payload contents. 'One ... by ID' implicitly separates it from listing siblings such as list_roi_analyses and get_latest_roi_analyses, though it never names them.

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?

Usage is implied by 'by ID' – a caller who already has an analysis_id fetches that record. There is no explicit statement of when to prefer this over list_roi_analyses or get_latest_roi_analyses, and no prerequisites or failure behavior mentioned.

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