get_plan_image

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

With no annotations, the description must disclose behavioral traits but only mentions a dependency on Pillow and the rationale for max_px. It does not state what is returned (e.g., image bytes, base64), whether the operation is read-only, or any potential side effects. Additionally, it claims max_px is 'required' while the schema shows it has a default and is optional, introducing inconsistency with the structured definition.

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 short, two sentences, and front-loads the main caveat about max_px. It earns points for brevity and highlighting a critical operational detail (dependency). However, its brevity comes at the cost of missing essential information about parameters and output, so it is concise but under-specified rather than efficiently complete.

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 no output schema, so the description must explain the return value, but it does not. It fails to state what the inline preview looks like (format, encoding), what handle and guid refer to, or any error conditions. Sibling tools like extract_plan_image and list_plan_images suggest a family of image tools, but without further context the agent cannot accurately construct a call or interpret the result. The false claim about max_px being required further compounds the incompleteness.

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 coverage is 0%, so the description must compensate, but it only touches on max_px (and even that is ambiguous—it says 'required' but doesn't explain its meaning beyond 'originals can be larger'). It provides no explanation for handle or guid, which are the required parameters. The agent cannot infer what these strings represent or how they relate to a plan image, making the parameter semantics nearly absent.

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 'Inline preview of the substrate' in Russian, which conveys the tool's core function of returning a preview image of a plan's base image. It implies a preview rather than full extraction, loosely distinguishing it from sibling extract_plan_image. However, it does not explicitly use the verb 'returns' or clarify the term 'substrate' for non-Russian-speaking agents, so it is clear but not perfectly explicit.

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 no guidance on when to prefer this tool over alternatives like extract_plan_image or get_plan. It only notes that max_px is necessary because originals can be large, which is a parameter usage hint, not a tool selection cue. There is no mention of context, prerequisites, or exclusions, leaving the agent without direction on which tool fits a given scenario.

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