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

Annotations only declare readOnlyHint=true; the description goes further by stating the call is free, warning that detail=full returns a large envelope, and annotating nullability (voice_job_id/plan_job_id are null when no job runs, plan_warnings is optional). It does not cover failure modes such as an unknown or deleted project_id, so it is strong but not complete.

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 cost and the resource in the first sentence, then cleanly split into Args and Returns sections. The inline return-type dump is dense and long, but with no output schema it is carrying necessary information rather than padding.

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 definition supplies the full response shape including optional and nullable fields, plus the default and tradeoff for the one enum parameter. An agent has everything needed to call this correctly and interpret the result.

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 only 50% — detail has an enum but no schema description — and the description compensates by defining the default ('summary') and the cost/size tradeoff of 'full' (the editor's whole envelope, large). It also restates the provenance of project_id, which duplicates the schema text rather than adding to it.

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 names the resource (a single project) and enumerates its contents — scenes with line/timing/visual, settings, price quote, and the revision used for edits — so an agent can tell it apart from studio_list_projects. It never states the verb explicitly, relying on the tool name, but the scope 'one project' is unambiguous.

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?

It gives practical routing context: project_id comes from studio_list_projects, and a returned revision is what you need for edits, which tells the agent this is a read-before-write step. The detail parameter's guidance ('summary (default) | full (the editor's whole envelope, large)') helps pick the mode, but there is no explicit when-not or named alternative for fetching multiple projects.

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