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

Discloses internal calls (/series/lookup then POST /series) and the return type (SeriesResource). Reveals that server-side default for search_for_missing_episodes is true, which may cause immediate indexer hits. Adds significant context beyond annotations.

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?

Compact yet comprehensive paragraph. Every sentence contributes: purpose, internal workflow, return, and a crucial behavioral note. No verbosity.

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?

Covers prerequisites, internal process, return type, and a key default behavior pitfall. Despite no output schema, the description provides enough context for correct usage.

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?

All 7 parameters are described in the schema (100% coverage). The description adds workflow context: tvdb_id from lookup, quality_profile_id from list, root_folder_path from list. Also explains the behavioral implication of search_for_missing_episodes default.

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?

Clearly states the action (Add a new series), the resource (series), and the identifier (TVDB id). Distinguishes from sibling tools like sonarr_edit_series by specifying 'add' versus 'edit'.

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 prescribes a workflow: look up series first, then get quality profile and root folder. Also notes a behavioral nuance about search_for_missing_episodes default, guiding when to override.

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

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

Annotations already declare readOnlyHint=true, so the agent knows it's safe. The description adds the date window constraint and that it returns episodes, but does not elaborate on other behavioral aspects like pagination or limits. For a simple read tool, this is adequate but not exceptional.

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 two sentences long, immediately states the action and resource, and provides sibling differentiation. Every sentence adds value with no redundancy.

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?

Given the tool's simplicity (two parameters, no output schema), the description covers essential information: what it does, when to use it, and how it differs from related tools. No major gaps remain.

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?

The input schema already describes both parameters as ISO dates with 100% coverage. The description only mentions 'ISO date window' without adding further detail. Thus, no additional value beyond 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?

The description clearly states the tool's purpose: 'Get upcoming/recent episodes from Sonarr's calendar within an ISO date window.' It also distinguishes itself from sibling tools by noting that movies belong to radarr_calendar and other arr apps have no calendar, preventing misuse.

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 explicitly suggests use cases ('what's airing this week?') and provides boundaries (movies elsewhere, no calendar for others). It does not explicitly list alternatives but gives clear context for when to use this tool.

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

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

The description does not disclose behavioral traits beyond what annotations already provide (readOnlyHint=true). It adds no details about side effects, rate limits, or other behaviors, but the annotations already clarify it is a safe read operation.

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 two sentences, front-loading the core purpose and then providing usage context. Every word serves a purpose with 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?

For a tool with zero parameters and a simple output (free/total bytes), the description covers all necessary context, including return value and suggested companion tool. No output schema exists, but the description implies what to expect.

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?

There are no parameters, so schema coverage is 100%. The description adds no parameter information, but since there are none, the baseline of 4 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?

The description uses a specific verb ('Get') and resource ('per-mount disk space') indicating exactly what the tool does. It also distinguishes itself from siblings by mentioning its use case and pairing with another tool.

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 explicitly states when to use the tool ('for decisions about where to add content') and suggests pairing with sonarr_list_root_folders. However, it does not explicitly state when not to use it, but for a simple read tool this is adequate.

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

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

The description adds valuable behavioral details beyond annotations: the internal GET+PUT process, preservation of unchanged fields, and explicit warning about root_folder_path moving files. Annotations already indicate destructive hint, but description adds specific context.

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 well-structured sentences: purpose, process/guidance, and warning. No filler; every sentence adds value.

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?

Covers essential aspects (process, side effects, parameter usage) for a simple edit tool. No output schema but return values are likely straightforward given the operation. Minor gap: doesn't mention if the full updated resource is returned.

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 baseline is 3. Description adds useful group-level guidance ('pass only fields you want to change') and clarifies tags behavior ('full replacement, not append'), raising it to 4.

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 clearly states 'Edit settings on an existing Sonarr series' with a specific verb and resource, and it distinguishes from sibling tools like sonarr_add_series and sonarr_get_series.

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?

Provides clear context: internally GETs and PUTs, pass only changed fields, and warns about root_folder_path moving files. However, it does not explicitly state when not to use this tool or list alternatives, so a 4 is appropriate.

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

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

Annotations already declare readOnlyHint=true, and the description confirms it's a read operation. It adds behavioral detail about the returned data (status, timestamps). No contradictions.

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 sentences: first states purpose and scope, second details return value. No extraneous text, front-loaded with key info.

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?

For a simple polling tool with one parameter and no output schema, the description fully explains usage and return value, making it complete given the context and sibling tools.

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 has 100% coverage for the single parameter. The description adds meaningful context by stating the id comes from a trigger tool, aiding correct usage beyond the schema's basic description.

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 clearly states the tool polls the status of an async command, specifically mentioning the triggering tools and the returned CommandResource fields. This distinguishes it from sibling tools that trigger commands or perform other actions.

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 explicitly says to poll status of commands queued by specific tools, implying when to use. No explicit when-not-to-use or alternatives, but the purpose is clear given the context.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds value by specifying the kind of data returned (full details including specific fields), which goes beyond the annotations.

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 a single sentence that efficiently conveys purpose and scope, front-loading the core action and key data fields. No unnecessary words.

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?

Given the tool's simplicity (one required param, no output schema), the description fully covers what the tool does and what it returns. Sibling tools like sonarr_list_episodes provide obvious alternatives for listing.

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?

The schema covers the single parameter 'id' with a description 'The Sonarr episode ID'. The description reiterates this with 'by ID' but adds no new 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?

The description clearly states the action 'Get full details for a single Sonarr episode by ID' and lists specific details (air date, overview, file info, monitored state). It distinguishes from siblings like sonarr_list_episodes and sonarr_search_episode.

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 explicitly notes that the tool requires an episode ID, making its use case clear. It does not, however, exclude or contrast with alternatives when the user has multiple episodes or lacks an ID.

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

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

Annotations already declare `readOnlyHint: true`, indicating a safe read operation. The description adds value by listing the response fields (overview, cast, file paths), but does not elaborate on other behavioral traits like error handling or rate limits. This is adequate but not rich.

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 two sentences with no superfluous words. Information is front-loaded with the primary action and content list, followed by a succinct sibling context. Every sentence earns its place.

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?

Given the tool's low complexity (one parameter, no output schema, rich annotations), the description sufficiently covers purpose, usage, and expected output. There are no gaps that hinder an agent's understanding.

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% with a single required parameter 'id' described as 'The Sonarr series ID'. The description does not add additional meaning beyond the schema, so a baseline score of 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?

The description clearly states the verb 'Get' and resource 'full details for a Sonarr series by id', listing the included data (overview, cast, seasons, etc.). It distinguishes itself from sibling tools as a 'drill-down companion' to `sonarr_list_series` and `sonarr_lookup_series`, making its specific role 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?

The description explicitly frames the tool as a 'drill-down companion', conveying that it provides more detail after using list or lookup tools. While it doesn't formally state when not to use, the context is sufficiently clear for correct selection.

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

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

Warns 'HIGH RISK', explains server-side lookup and cache dependency, and override behavior. Annotations indicate mutation (readOnlyHint=false) but description adds valuable runtime context. No contradiction.

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 sentences, no fluff, with critical warning first. Each sentence earns its place.

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?

No output schema, but mutation tool adequately covers failure scenario and recovery. For two-param tool with its risks explained, this is complete enough.

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 covers both parameters (100%), and description adds: release must be verbatim from search, guid+indexerId key, other fields ride along. should_override explained as UI mirror. Adds real value beyond 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?

Clear verb 'grab' and resource 'release', with action 'queues a download'. Distinguishes from sibling sonarr_release_search which searches, not grabs.

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 instructs to pass release verbatim from sonarr_release_search, and advises re-running release_search if grab fails. Mentions when to use should_override. Lacks explicit 'when not to use' but context is clear.

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

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

Annotations already indicate read-only. Description adds that it provides aggregated warnings (summary view), which clarifies the output nature. Could mention what happens with no warnings but adequate for a simple read operation.

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 concise sentences, front-loaded with the tool's purpose, no redundant information.

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?

Given no parameters and no output schema, the description covers purpose, scope, and an alternative. Could specify return format but overall complete for a simple health summary 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?

No parameters exist, so baseline is 4. The description does not need to add parameter info, and schema coverage is irrelevant here.

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 clearly states the tool gets aggregated Sonarr health warnings, provides examples (indexer down, low disk), and distinguishes from a sibling tool (prowlarr_indexer_status) by specifying this is a summary view.

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 explains when to use this tool (for summary view) and when not (for actionable per-indexer detail), and directly names the alternative tool to use for detail.

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

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

Annotations already indicate `readOnlyHint=true` and `openWorldHint=false`. The description adds that results are 'newest first', which is a behavioral detail beyond annotations. No contradictions; description adds some value.

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 sentences, front-loaded with purpose, no wasted words. Every sentence provides essential information about scope and alternatives.

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 simple tool (one optional parameter, no output schema) is adequately described for typical use. Missing details about return format, but given no output schema and common understanding of 'history', it is sufficient.

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% with a single parameter `page_size` fully described. The tool description adds no further meaning to the parameter, so baseline score of 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?

The description clearly states 'Get recent Sonarr history (newest first)', providing a specific verb and resource. It also distinguishes from sibling tools like `sonarr_history_series` and `sonarr_history_mark_failed`, making the tool's scope 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?

Explicitly tells when to use this tool (general history) vs. per-resource scope (`sonarr_history_series`), and when to use `sonarr_history_mark_failed` for wrong-grab events, providing clear context and alternatives.

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

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

Describes the trigger effect (re-search on next interval) and return behavior (confirmation, no body from API). Annotations indicate destructiveness and idempotence; description adds context without contradiction.

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 concise sentences: action, consequence, return value. No repetition or filler. Front-loaded with the primary purpose.

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?

For a single-parameter tool with annotations and no output schema, the description fully explains what it does, when to use it, and what to expect as a result. No gaps.

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 covers the single 'id' parameter with description. The description adds useful context about its source ('from sonarr_history or sonarr_history_series'), but this is supplementary to 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?

Description clearly states the action ('Mark a Sonarr history entry as failed') and the resource type. It distinguishes from sibling tools like sonarr_queue_regrab by specifying the context of wrong cut/quality/release.

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?

Provides a clear use case: 'Useful when an episode imported as the wrong cut/quality/release.' Does not explicitly mention when not to use or alternatives, but the context is strong enough for typical scenarios.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is clear. The description adds value by listing the specific event types (grab/import/upgrade/delete) and the scoping constraint, going beyond annotations. No contradictions.

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 sentences with no extraneous information. The first sentence defines purpose and scope; the second provides usage guidance. Every word earns its place.

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 tool is simple with one parameter and no output schema. The description adequately covers purpose, scope, and when to use. It could mention return format or ordering, but given the low complexity, it is sufficiently complete.

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% with a clear description for `series_id`. The tool description does not add further parameter meaning beyond what the schema provides, resulting in a baseline score of 3.

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 clearly states the action ('Get history scoped to a single series') and specifies the resource ('every grab/import/upgrade/delete event'). It explicitly distinguishes from the sibling `sonarr_history` tool, making the purpose unmistakable.

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 provides explicit guidance: use this tool for series-scoped history, and contrasts it with `sonarr_history` which is server-wide and larger. This helps the agent choose correctly.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds value by explaining the return value (episode IDs) and how they can be used, which goes beyond what annotations provide.

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 two sentences long, front-loads the core purpose, and contains no unnecessary words. Every sentence adds value.

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?

Given the tool's low complexity (single parameter, no output schema, read-only), the description is complete. It explains the action, the scope of results, and how to use the output with other tools.

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?

The schema description coverage is 100%, and the parameter description in the schema already explains 'series_id' as 'The Sonarr series ID'. The tool description does not add additional information about the parameter beyond the schema, so baseline score of 3 applies.

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 clearly states the verb 'list' and the resource 'every episode for a Sonarr series'. It also distinguishes from the sibling tool 'sonarr_get_episode' by noting that it returns episode IDs for further drilling.

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 provides explicit context on when to use this tool: to list all episodes. It also suggests next steps by mentioning that the returned episode IDs can be used with 'sonarr_get_episode', 'sonarr_release_search', or 'sonarr_search_episode'. However, it does not explicitly mention when not to use it or alternative tools for different purposes.

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

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

Annotations already indicate `readOnlyHint: true`. The description adds a minor behavioral detail about the `id` usage but does not contradict annotations or provide significant new behavioral context.

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 concise sentences that are front-loaded. No unnecessary words, every sentence adds value.

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?

Given no parameters, no output schema, and read-only annotations, the description is complete. It explains the purpose and how to use the returned data.

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?

No parameters exist; schema coverage is 100% (vacuously). With zero parameters, baseline is 4. Description does not need to add parameter details.

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?

Description clearly states 'List Sonarr quality profiles' with a specific verb and resource. It also explains the usage of the `id` field when adding a series, adding value beyond just naming the tool.

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 provides implicit guidance by mentioning the `id` is used as `qualityProfileId` for adding series, but does not explicitly differentiate from siblings or state when to use this tool.

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

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

Annotations already declare readOnlyHint=true, so the description correctly confirms a read-only operation. It adds behavioral context by explaining what root folders represent and linking to the add_series workflow, but it does not describe the return format or potential errors.

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 two sentences, front-loaded with the core action, and contains no redundant information. Every word earns its place.

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?

Despite having no output schema, the description does not explain what the output contains (e.g., list of paths, names, or full objects), leaving a gap in completeness. However, the tool is simple and the annotations cover the read-only aspect.

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?

The input schema has no parameters (0 params), so baseline is 4. The description adds no parameter details but correctly implies no inputs are needed.

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 clearly states the tool's verb ('List') and resource ('Sonarr root folders'), with an explanation of their purpose ('where series are stored on disk'). It distinguishes from siblings like sonarr_list_series by specifying the resource type.

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 hints at usage by noting that the returned path is needed for adding a series, but does not explicitly specify when to use this tool vs alternatives, nor does it provide context for exclusion or comparison with sibling list tools.

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

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

Annotations already declare readOnlyHint=true, and the description adds behavioral details beyond that: default slim fields, paging is server-side, and that verbose returns heavier data. No contradictions; description enriches annotation context.

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?

Description is moderately concise, front-loading purpose and then listing fields and notes. Every sentence adds value, though the field list is somewhat long. No wasted words, but could be shortened slightly.

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?

Despite no output schema, the description explains the return fields in detail (listing slim fields and noting what verbose adds). Also covers paging behavior and sibling tools. Highly complete for a paged list 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?

Input schema has 100% coverage, and the description adds context for each parameter: page default 1, page_size default 50 max 200, verbose meaning and side effects. The hint to use smaller page_size with verbose adds value beyond 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?

The description clearly states it lists TV series tracked by Sonarr as a paged result, and distinguishes from 'sonarr_get_series' (full details) and 'sonarr_lookup_series' (find untracked). The verb 'list' plus resource and paging detail make the purpose highly specific.

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?

Provides explicit guidance on when to use this tool (listing series) and when not ('For full details on one series, use sonarr_get_series' and 'To find a series NOT yet tracked, use sonarr_lookup_series'). Also gives tips on page_size versus verbose to avoid MCP cap.

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

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

Annotations already declare readOnlyHint=true, indicating no side effects. The description adds context on how tags are used (scoping, add/edit) but does not elaborate on response size or pagination. No contradiction with annotations.

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 a single, well-structured sentence that starts with the core action and resource, then provides usage context. No unnecessary words.

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?

For a simple list tool with no parameters and no output schema, the description fully captures what the tool does, what it returns (label+id pairs), and why it's useful (tag scoping and setting IDs). The annotations cover safety, making this complete.

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?

The input schema has zero parameters with 100% coverage, so no additional parameter details are needed. The description adds no parameter info, which is appropriate given no parameters exist.

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 clearly states the verb 'List' and the resource 'Sonarr tags (label + id pairs)'. It distinguishes this tool from siblings like sonarr_list_series and sonarr_list_quality_profiles by specifying what is listed and for what purpose.

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 explains when to use this tool: for scoping queries by tag and for setting tag IDs during add/edit operations. It provides a concrete example ('show me everything tagged kids') but does not explicitly exclude cases where it should not be used.

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

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

Annotations already provide readOnlyHint and openWorldHint. The description adds that it performs fuzzy search, returns SeriesResource with tvdbId, and searches TVDB's catalogue, providing helpful behavioral context beyond the annotations.

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 concise sentences with front-loaded purpose. Every sentence adds value without redundancy.

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 fully covers the tool's purpose, scope, output, and relationship to siblings. No output schema needed as the description mentions the return type. Complete for a simple lookup 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 coverage is 100% with the term parameter described as 'Search term'. The description does not add extra meaning to the parameter, so 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?

The description states 'Fuzzy search TVDB for a series to potentially add' with a specific verb and resource, and distinguishes itself from sibling tools like sonarr_list_series and sonarr_get_series by clarifying it searches TVDB's catalogue, not the tracked library.

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 tells when to use (to look up series to add) and when not to (for tracked library, use sonarr_list_series/sonarr_get_series). Also hints at follow-up action with sonarr_add_series.

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

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

The annotation readOnlyHint: true is consistent with the description's 'Get' operation. The description adds value by detailing default pagination and suggesting strategy for large queues, though it omits authentication or rate limit details.

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 sentences: first for purpose, second for paging. No wasted words; information is front-loaded and efficient.

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 covers core functionality and paging but lacks details on the structure of returned queue items. With no output schema, this is adequate for a simple list 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 coverage is 100%, but the description adds meaningful strategic guidance on handling large queues (e.g., bump page_size or step through pages), which goes beyond the schema defaults.

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 uses the clear verb 'Get' and specifies the resource 'current Sonarr download queue', distinguishing it from sibling queue manipulation tools like sonarr_queue_regrab and sonarr_queue_remove.

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 mentions paging behavior and provides strategic advice for large queues, but it does not explicitly state when to use this tool versus related queue tools such as sonarr_queue_regrab or sonarr_queue_remove.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds context that it 'forces a re-grab from the indexer' and 'returns the updated queue entry,' but it does not disclose potential side effects (e.g., duplicate downloads) or network impact. With annotations covering basic safety, the description adds moderate value.

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 sentences (20 words) efficiently convey purpose, usage context, and return value. The first sentence is action-oriented, and no unnecessary information is present.

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?

For a simple tool with one parameter, the description covers purpose, when to use, and return value. No output schema exists, but 'Returns the updated queue entry' is sufficient. The tool is low complexity, so completeness is high.

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% and the parameter description in the schema is clear ('The Sonarr queue item id (from sonarr_queue)'). The tool description adds no additional meaning beyond the schema, so 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?

The description uses the specific verb 're-grab' and clearly identifies the resource 'stuck queue item'. It distinguishes from sibling tools like sonarr_queue (list), sonarr_queue_remove (remove), and sonarr_grab_release (grab release) by focusing on re-grabbing stuck items.

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 provides when-to-use context: 'when a download is hung or the file is corrupt.' However, it does not mention when NOT to use it or compare with alternatives like sonarr_queue_remove, so it lacks explicit exclusions or comparisons.

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

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

Annotations already flag destructiveHint true, but description adds crucial context: server-side default removes from client, but this tool defaults to false. Discloses behavioral traits for each flag beyond annotations.

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?

Single, well-structured paragraph. Each sentence adds value: main action, flag defaults, and explicit warning. Front-loaded with purpose.

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?

For a simple removal tool with no output schema, the description fully covers all flags and their behavioral outcomes. No missing context needed for safe invocation.

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%, but description adds meaning by explaining defaults and their practical implications (e.g., 'flips Sonarr's destructive server-side default of true'). Every parameter's behavior is clarified.

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 'Remove a single item from Sonarr's download queue' with a specific verb and resource. It clearly distinguishes from siblings like sonarr_queue (list) and sonarr_queue_regrab (re-grab).

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?

Provides explicit guidance on when to use this tool and warns about the default behavior of remove_from_client being destructive. Mentions all flags and their defaults, helping decide when to flip them.

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

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

Annotations indicate non-readOnly, non-destructive, idempotent, and open world. The description adds behavioral context: async execution, return of a CommandResource, and polling instructions. No contradictions with annotations.

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 concise sentences, no wasted words. Front-loaded with the purpose and key details. Efficient and easy to scan.

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?

Given the simple tool (1 param, no output schema, annotations present), the description covers purpose, async behavior, and follow-up action. It is fully adequate for an agent to use correctly.

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?

Only one parameter (series_id) with full schema coverage. The description does not add meaning beyond the schema description ('The Sonarr series ID to refresh'). Baseline 3 applies as schema does the work.

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 clearly states what the tool does: 'Trigger Sonarr to re-pull metadata from TVDB for one series' with specific details on what is refreshed (cast, episode list, artwork). It distinguishes from siblings like sonarr_add_series or sonarr_edit_series, as refresh is a unique operation.

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?

Provides explicit usage guidance: 'Async — returns the queued CommandResource. Poll status with sonarr_get_command (use the returned id).' This tells the agent how to handle the async nature and follow up. It could mention when to use alternatives, but the context is clear.

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

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

The description adds value beyond annotations by disclosing that the tool 'hits every enabled indexer in real time — slow and rate-limit-sensitive' and clarifies it does not grab. Annotations readOnlyHint and openWorldHint are consistent and non-contradictory.

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 three sentences, each serving a clear purpose: stating the action, providing usage guidance, and detailing parameter options. No extraneous words.

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?

Given the tool's complexity, the description covers purpose, behavior, usage context, parameter guidance, and future integration with sonarr_grab_release. No output schema exists, but the description implies the return type ('candidate ReleaseResource entries'), which is sufficient.

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%, and the description adds meaning by explaining parameter relationships (e.g., season_number used with series_id, series_id required unless episode_id set). This helps the agent understand optionality and scope.

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 clearly states the tool performs a live indexer search for releases and returns candidate entries without grabbing. It specifies the verb, resource, and return type, and distinguishes from sibling tools like sonarr_grab_release.

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 explicitly says 'call only when the user wants to pick a release manually' and mentions it is slow and rate-limit-sensitive, providing clear when-to-use guidance. It also explains the three scoping options and that at least one is required.

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

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

Adds value beyond annotations by detailing async behavior, returning a CommandResource, and recommending status polling. No contradiction with annotations; idempotentHint and openWorldHint are consistent.

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 efficient sentences with critical information front-loaded: action, async behavior, and follow-up instruction. No unnecessary words.

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?

Given simple one-parameter tool with no output schema, the description adequately covers purpose, async behavior, and result handling. No gaps.

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% with clear description for episode_ids. The description adds no extra meaning beyond what the schema provides, so 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?

The description clearly states the tool triggers a search for episodes, using specific verb 'Trigger' and resource 'episodes'. It distinguishes from siblings like sonarr_search_season or sonarr_search_series by specifying 'one or more specific episodes'.

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 mentions async nature and instructs to poll status using sonarr_get_command. Provides clear post-invocation guidance, though lacks explicit when-not-to-use comparisons with siblings.

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

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

Discloses the async nature of the operation and that the actual search runs in the background. Describes the return value (CommandResource with id and status). Does not contradict annotations (idempotentHint=true is consistent with triggering a potentially idempotent search). No additional side effects or limits are mentioned, but given the simple nature, it's adequate.

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?

Description is two concise sentences with no superfluous words. Front-loaded with the main action, followed by async details and follow-up instructions. Efficient use of 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?

Given the tool's simplicity (no input parameters, no output schema), the description provides all necessary context: what it does, async behavior, return value, and how to monitor progress. It is complete for an agent to select and invoke correctly.

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?

The tool has no parameters, so schema coverage is 100%. The description does not need to add parameter meaning. Baseline for 0 parameters is 4, and the description does not detract.

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 explicitly states the tool triggers a search for all monitored missing episodes. It uses specific verbs ('Trigger Sonarr to search') and resource ('all monitored, missing episodes'), clearly distinguishing it from sibling tools like sonarr_search_episode and sonarr_search_season.

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?

Provides clear guidance on usage: it is an async operation that returns a CommandResource, and instructs to poll status with sonarr_get_command using the returned id. It does not explicitly state when not to use it or mention alternatives, but the context is sufficient.

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

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

The description adds value beyond annotations by revealing the async nature and the returned CommandResource, instructing polling behavior. Annotations already indicate idempotence and non-read-only, but the description fills in the async detail, which is crucial for correct use.

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 two sentences, front-loading the action in the first sentence and providing critical async workflow in the second. Every word contributes value with no redundancy.

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?

Given the tool's simplicity (2 parameters, no nested objects), the description sufficiently covers purpose, behavior, and follow-up steps. The lack of output schema is mitigated by describing the return type and polling mechanism.

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?

The input schema already provides 100% coverage with descriptions for both parameters (series_id and season_number). The description does not add additional semantic context beyond the schema, so it meets the baseline without enhancement.

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 clearly states the tool triggers a search for 'one season of one series', distinguishing it from sibling tools like sonarr_search_episode (single episode) and sonarr_search_series (whole series). The verb 'search' and resource 'season' are specific and 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?

The description explicitly advises to poll status with 'sonarr_get_command' using the returned ID, providing a clear post-invocation workflow. However, it does not explicitly state when not to use this tool or compare it to alternatives like sonarr_search_missing, which limits guidance slightly.

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

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

Discloses async behavior and the need to poll, adding value beyond annotations. Annotations already indicate non-destructive and idempotent, so the description adequately complements them.

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 sentences, no extraneous words. Front-loaded with the core action, then async handling. Efficient and well-structured.

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?

Given the single parameter, clear annotations, and async behavior, the description covers everything needed: what, how, and next steps. No gaps.

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% with a clear parameter description. The tool description does not add extra meaning beyond what the schema provides, meeting the 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?

The description clearly states it triggers a search for all monitored missing episodes of one series. It specifies the action, scope, and condition, distinguishing it from sibling tools like sonarr_search_episode or sonarr_search_season.

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 states the async nature and directs to poll using sonarr_get_command. While it doesn't list when not to use, the guidance is clear and effective for agents.

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

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

Description is consistent with annotations (readOnlyHint=true). Adds context about default monitoring filter and relationship to other tools. No contradictions.

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 sentences, no filler. Front-loaded with core purpose, then relevant details. Efficient and clear.

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?

Given simple tool with full schema coverage and annotations, description is complete. Includes sibling reference and default behavior.

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% with parameter descriptions. Description only restates defaults without additional meaning. Baseline score 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?

Clearly states 'List episodes downloaded below cutoff quality — upgrade candidates.' Verb 'List' and resource 'episodes below cutoff' are specific. Distinguishes from sibling sonarr_search_missing by explaining relationship.

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 says 'Filters to monitored items by default' and suggests using sonarr_search_missing for re-search, which provides clear when-to-use and alternatives.

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

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

Annotations already declare readOnlyHint=true, and the description adds that it filters to monitored items by default. This provides useful behavioral context beyond the annotations, without contradicting them.

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 two sentences long, front-loads the core purpose, and includes a helpful follow-up suggestion. Every sentence earns its place without unnecessary detail.

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?

Given the simple tool (2 parameters, no output schema, read-only), the description adequately covers what the tool does and how to use it. It implies the output (list of episodes) but does not detail the return format, but that is acceptable for such a straightforward 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%, so the schema already documents the two parameters. The description only mentions the default filter behavior but does not add significant new meaning beyond the schema fields.

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 clearly states the tool's purpose: 'List episodes that are wanted but not yet downloaded.' It specifies the resource (episodes) and the action (list), and distinguishes from sibling tools like sonarr_search_missing by indicating the follow-up action.

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 provides clear context: use to identify missing episodes, and mentions the next step with sonarr_search_missing. However, it does not explicitly say when not to use this tool or compare with other listing tools like sonarr_calendar or sonarr_history.

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