Read Media

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

Annotations only declare readOnlyHint/destructiveHint, but the description adds substantial context: thumbnail renders JPEG (PNG when transparent) at 1568px, EXIF/metadata are stripped, the original is served per MIME type, and it requires GRAMPS_MEDIA_RESOURCES_ENABLED=true with size and private-record safeguards. This greatly exceeds what the annotations convey.

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-loaded with the core purpose, then mode behavior, then prerequisites and sibling routing. The paragraph is dense and cohesive, but a few clauses (rendering-fallback detail) push length; each still earns its place, so only slightly less than ideal.

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?

With no output schema, the description carries the return-value burden and does so: it specifies MCP image content, the JPEG/PNG choice, the blob resource content for audio/original modes, and the required environment flag. An agent has everything needed to invoke it correctly.

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 100%, so baseline is 3; the description nonetheless adds meaning beyond the schema by noting images are never upscaled and that the default resolves handwriting and small print. It reinforces mode semantics, though it doesn't add much beyond the already-detailed schema for 'size' and 'handle'.

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?

States a specific verb and resource: 'Download a media file's bytes so you can see it,' then immediately clarifies the two operational modes (thumbnail vs file). It explicitly distinguishes itself from siblings by naming get_object (for the record) and update_media (for edits), so an agent can route correctly without opening schemas.

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?

Gives explicit when-to-use ('Prefer it for reading photos and document scans'), when-not ('Use mode file only when the original is needed'), and alternatives ('For the media record itself... use get_object; to change it use update_media'). Nothing is left to inference.

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