inspect_image

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the useful behavioral note that output includes build history (layers, sizes, commands), which is real added context. However, it says nothing about error behavior for missing images, performance on large images, or output format. A 3 reflects modest added value beyond 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?

Front-loads the read semantics and purpose in one bracketed phrase, then lists args compactly. The 'Args:' section is a bit redundant with the schema, but it's short and earns its place by clarifying the opaque 'target'. No wasted filler.

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 2-param read tool with no output schema and only readOnlyHint, the description is adequate but not complete: it doesn't explain what a 'target' actually is in this system, nor how to interpret the returned layer/history data. An agent can call it, but may mis-set 'target' without config context. An output schema is absent, so the description could do more to set expectations for return shape.

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 carries the parameter-explanation burden. It does add meaning for both params: 'image_id' is 'Image id or name:tag', and 'target' is 'Target name from config; omit for the default'. This is genuinely helpful, but the target explanation is thin (what config? what is a target?) and 'name:tag' format could be clearer. Baseline for 2 params is 4, but the shallow target note pulls it to 3.

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?

Clear verb 'inspect' and resource 'image', and the parenthetical '(layers, sizes, commands)' sharpens what is returned beyond a generic inspect. It distinguishes itself from siblings like list_images or image_disk_usage by specifying deep, layered detail. It does not explicitly name a competing sibling, so it falls short of a 5.

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 '[READ]' tag and parenthetical hint imply this is the tool for deep image introspection, and the 'target' arg note ('omit for the default') gives a small usability cue. But there is no explicit when-to-use vs image_disk_usage or dangling_images, nor any prerequisite (e.g., image must exist locally). Usage is inferable, not stated.

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