Check (and convert) media for Instagram

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

With readOnlyHint=false already flagging that a write can occur, the description adds genuine context: the write only happens when convert=true, what the output container/codec will be, and that a path is returned. The "Needs ffmpeg" prerequisite is a real environmental dependency worth disclosing. It doesn't say where the copy is written, whether it overwrites, or cleanup expectations.

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?

Three tight sentences, front-loaded with the inspection purpose, then the mutation mode, then the redundancy note and dependency. No filler and nothing repeated from the schema.

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 covers both return shapes at a high level: a list of rejections in inspect mode and a file path in convert mode. The ffmpeg requirement and the note about automatic handling in publishing tools round it out. Minor gap: the structure of the rejection list and the destination of the converted copy are unstated.

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 75%, so kind, file_path and convert are already documented in the schema. The description adds the output target format for convert (JPEG / H.264+AAC MP4) and that reframing uses fit, but the fit enum values keep/crop/blur are never explained in either place. Baseline 3 is appropriate.

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?

Specific verb+resource with explicit scope: "Inspect an image or video and list what Instagram would reject for a placement (format, codec, aspect ratio, length, size)". It also names the second mode (convert=true writes a fixed copy) and distinguishes itself from the publish_* siblings by noting they do this automatically.

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?

"Publishing tools do this automatically" tells the agent this is a pre-flight check, not a mandatory step, which is real routing guidance against publish_photo/publish_reel. It also implies the convert=false vs convert=true decision (inspect vs fix). It stops short of explicit when-not-to-use or when to prefer convert over letting the publisher handle it.

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