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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful detail that the response carries the validation problems and the revision token that must be forwarded downstream, but says nothing about permissions, staleness of the revision, or response size.

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?

Two compact sentences with zero filler: the first front-loads what the tool returns, the second states the workflow constraint. Nothing is redundant with the title or 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, so the description's enumeration of returned content (script, revision, versions, project, validation problems) is what makes the tool callable with confidence. It does not describe the shape of the validation problems or versions, which is a minor gap for a read-only three-parameter tool.

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 100%, with projeto tied to studio_listar_projetos and episodio accepting number, ref, or slug, so the schema does the explanatory work. The description mentions the revision value but that is a return field, not a parameter, so it adds no parameter meaning beyond the schema.

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?

"Shows one episode" gives a specific verb and resource, and the definition enumerates exactly what comes back: script (roteiro), revision, versions, parent project, and current validation problems. That content list implicitly separates it from siblings such as studio_andamento or studio_mostrar_video, though no sibling is explicitly named as a contrast.

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?

"Read it before editing, and pass its revision to studio_escrever_roteiro" gives clear when-to-use guidance and links the call to the follow-up write tool. There is no explicit when-not case (e.g. listing episodes versus inspecting one), but the pre-edit workflow is unambiguous.

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