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

Goes well beyond the readOnlyHint annotation: it explains what is returned inline (images as viewable content), what degrades to metadata plus a time-limited URL, that such a result is success rather than an error, and that URLs are unstable across calls while resourceId is the stable identity. This is exactly the behavioral context an agent needs to avoid misinterpreting results.

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 purpose and then layers the return-behavior rules; every sentence carries information, including the retry warning that prevents a common failure loop. It is dense and somewhat long, but there is no 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?

With no output schema and a read-only tool, the description fully covers what comes back in each case and how to interpret it, plus the stability caveat on the URL. Nothing an agent needs in order to call it and handle the result is missing.

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 the baseline is already high, and the description adds provenance meaning for resourceId ('the id of the task's resource as getBetaTasks returns it') that helps the agent map it to the correct field. It does not add format or constraint detail beyond that, so it sits just above baseline.

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 ('Fetch the media a manager attached to a task') and scopes it to testers following instructions. It names the source tool for the identifier (getBetaTasks) and is clearly distinguishable from siblings like getStepMedia, setTaskMedia, and removeTaskMedia.

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?

Explicitly directs the agent to get the resource id from getBetaTasks (published or unpublished) and describes the two usage branches: share the download URL with the user, or fetch it yourself when asked to read/analyze. It also gives a negative instruction — do not retry when a metadata-plus-URL result comes back.

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