create_shows_by_id_refresh_justwatch

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

The annotations already cover the safety profile (non-read-only, idempotent, non-destructive), so the description does not need to repeat those. It adds the scope 'JustWatch links' but does not disclose whether refresh replaces existing data, fetches from an external source, has rate limits, or has other side effects.

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?

The description is compact and front-loads the purpose, then provides the endpoint and argument guidance. The endpoint line is slightly redundant with the tool name but still useful for clarity and does not waste much space.

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?

The description is minimally adequate for a two-parameter mutation tool, especially since an output schema exists. However, it leaves gaps around when a refresh is appropriate, what side effects occur, and how the body should be shaped beyond the GET/schema pointer. More context would help an agent invoke it confidently.

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?

With 0% schema description coverage, the description compensates meaningfully by explaining id as 'id/slug' and giving an actionable strategy for body: read the matching GET or /schema endpoint. While body fields are not enumerated, the guidance tells the agent how to discover them, which is valuable for an open-world body object.

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 states a specific verb ('Refresh') and a precise resource scope ('show JustWatch links'), which clearly distinguishes it from siblings like create_shows_by_id_refresh and create_movies_by_id_refresh_justwatch. The included POST endpoint reinforces the exact action without ambiguity.

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?

The description gives no guidance on when to use this tool versus related alternatives such as create_shows_by_id_refresh or create_shows_by_id_report. It only instructs the agent to read the matching GET or /schema endpoint, which addresses body construction, not tool selection.

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