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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered and the bar is lower. The description adds genuine value beyond them by specifying error semantics: a show absent from TVmaze 'is reported as a miss with guidance, not an error,' which tells the agent to expect a structured miss rather than a failure and not to abort a workflow.

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 with zero filler: the action and scope come first, then the when-to-use cue, then the edge-case behavior. Every sentence earns its place and nothing is buried at the end.

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?

An output schema exists, so the return profile need not be described, and the description covers action, scope, usage cue, and miss behavior. The only gap is not naming sibling tools for TVmaze-native or title-based lookups, which would fully close the routing decision.

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% and each source variant documents its own id format and pattern, so the schema carries the parameter burden. The description names the three catalogs but adds no syntax or format detail beyond the schema's const/pattern definitions – 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?

States a specific verb (resolve) plus resource (TV show) and, critically, the scope qualifier 'from its id in another catalog — IMDb, TheTVDB, or TVRage — and return the matching TVmaze profile.' This implicitly separates it from tvmaze_get_show (native TVmaze id) and tvmaze_search_shows (name search), so an agent can route without opening the schema.

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?

'Use this to cross a show id from another source into TVmaze' gives a clear triggering context. It stops short of naming the alternatives it is not (e.g., use tvmaze_get_show when you already hold a TVmaze id, or tvmaze_search_shows when you only have a title), so no explicit exclusion is provided.

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