get_opinion_figure_image

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns one viewable image per call and that this keeps responses manageable, but it does not specify the image format (e.g., base64, URL, binary), error behavior for invalid indices, or any size/encoding constraints. This is adequate but not detailed.

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 tight sentences with no wasted words. It front-loads the core behavior, then provides the necessary prerequisite step and rationale for one-image-per-call.

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?

For a simple two-parameter retrieval tool with a clear prerequisite workflow, the description gives an agent enough to call it correctly. The main gap is the lack of an output schema or explicit statement of how the image content is returned, but the provided workflow guidance largely compensates.

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?

The input schema already documents citation and fig_index with 100% coverage, so the baseline is 3. The description adds value by clarifying that fig_index selects 'a specific figure' and by directing the agent to use get_opinion_figures first to determine valid indices and choose based on captions/kinds.

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 opens with a specific verb and resource: 'Return one figure's image from an opinion, as viewable image content.' This clearly distinguishes it from siblings like get_opinion_figures (which lists figures) and get_opinion_text (which returns text).

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 explicitly tells the agent to call get_opinion_figures(citation) first to see how many figures exist and their captions/kinds, then call this tool for a specific figure. It also explains the one-image-per-call policy, making the intended workflow unambiguous.

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