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

Annotations only say readOnly=false and destructive=false; the description goes far beyond by disclosing the two-phase preview/confirm contract, that search starts by default on add, that an option sent to the wrong service is refused rather than dropped, that Lidarr's add-search covers only monitored and released albums, and that monitor:"none" requires monitored:false. These are exactly the failure modes an agent would otherwise hit blind.

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 purpose and the alternative before the parameter detail, and nearly every sentence carries a distinct rule or caveat. The middle is dense and semi-colon chained, so it reads as a wall of detail rather than scannable structure, but there is little true 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 15-parameter mutation tool with five enums, an output schema, and only weak annotations, the description supplies the preview/confirm lifecycle, per-service parameter legality, defaults, and a pointer to arr://docs/add_media for the full field reference. Nothing an agent needs to invoke it correctly is absent.

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 already 100%, so the baseline is 3; the description still adds cross-cutting meaning the schema cannot express — the preview's refusal behavior for ambiguous root_folder/quality_profile, the per-service id provenance via lookup_media, and the service-specific notes on monitor/series_type/minimum_availability. It does not add much on the individual field formats, hence a 4 rather than a 5.

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 plus the exact resource per service ("Adds a film to Radarr, a series to Sonarr, a site to Whisparr or an artist to Lidarr") and immediately names the sibling it is not (request_media). An agent can distinguish it from request_media, update_media and set_monitoring without opening any 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?

Explicit routing: use request_media for a Seerr request that goes through approval. It also gives operational guidance — name a quality profile/root folder when there is more than one because the preview refuses with the list, so "there is no need to check stack_health first", and "Previews first; confirm to add." That is when-to-use, when-not-to-use, and a named alternative.

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 destructiveHint=true and readOnlyHint=false, so the safety class is known; the description adds real substance beyond that: it also removes the item from the download client, it never blocklists, and it only touches items that are both orphaned and import-blocked so in-progress downloads are untouched. It does not mention auth or rate limits, but the destructive scope is well disclosed.

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?

Purpose is front-loaded in the first clause, followed by scope constraints, the blocklist carve-out, the Lidarr exception with the sibling handoff, and the workflow in one closing line. Dense but every sentence carries distinct information; nothing is repeated from the schema or annotations.

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 destructive, multi-service cleanup tool the description covers scope, exclusions, side effects (download client removal, no blocklisting), version-specific behavior, and the safe invocation flow. Return values need no explanation because an output schema exists.

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 75% and the schema already documents confirm, dry_run, and instance in detail, so the baseline would be 3. The description adds meaning the schema cannot: the preview-then-confirm sequencing that gives the confirm token its purpose, and the fact that the token is tied to the previewed arguments.

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 and resource: removes completed downloads stuck in Radarr/Sonarr/Whisparr/Lidarr queues because the parent media no longer exists, naming the exact 'importBlocked' state. It also implicitly differentiates itself from remove_queue_item by scope (bulk orphan cleanup vs. a single row).

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 names the alternative and the condition that selects it: on Lidarr before 2.10.1 nothing is marked importBlocked, so 'remove such a row with remove_queue_item'. It also prescribes the workflow — preview first, then confirm — and notes dry_run is for hypotheticals.

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 destructiveHint=true, so the bar is lower, yet the description still adds real behavioral context: deletion is not undoable, it leaves the series/monitoring/history intact, and skipping the unmonitor step causes Sonarr to re-download the deleted files. It does not cover permission or auth requirements, but for a file-delete tool the irreversible consequence and side-effect chain are well disclosed.

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?

Sentences are dense but front-loaded: the destructive core comes first, then the parameter constraint, then the sibling exclusion, then the prerequisite warning, then the preview flow. Each sentence carries a distinct operative fact, 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 destructive, 7-parameter tool with an output schema already present, the description supplies everything an agent needs to act safely: scope, exclusivity, sibling routing, prerequisite ordering, and the preview/confirm protocol. Return values are correctly left to the output schema.

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 86%, so the schema carries most parameter meaning. The description still reinforces the season/episodes mutual exclusivity and frames `confirm` as the second half of a preview-then-apply loop, which adds workflow meaning beyond the field-level text.

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 and resource ("Deletes the files for one Sonarr season, or for specific episodes, from disk") and explicitly demarcates scope from the sibling delete_media by noting there is no whole-series form here. An agent can distinguish this from delete_media and set_monitoring without opening either 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?

It gives explicit routing rules: use `season` or `episodes`, never both; whole-series deletion belongs to delete_media; unmonitor first with set_monitoring; preview then confirm. When-to-use, when-not-to-use, prerequisite ordering, and the named alternative are all present.

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?

Goes well beyond the destructiveHint annotation: states the action is not undoable, files are gone rather than recycled unless the service itself is configured for a bin, and that Sonarr/Whisparr delete the entire series/site. It also discloses the service-specific quirk that Grimmory always deletes book files, requiring delete_files=true and taking no import exclusion.

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-loads the core action and per-service mapping, then the safety warning, then the alternative tool. Dense but each sentence carries a distinct constraint; the Grimmory caveat and the id-sourcing note could be tightened slightly but neither is 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 destructive multi-backend delete with an output schema already covering returns, the description supplies everything an agent needs: target resource per service, id source, preview/confirm protocol, irreversibility, and the correct sibling for narrower deletion.

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 already 86%, so baseline is 3; the description adds genuine cross-parameter meaning the schema cannot express — that `id` comes from `acquisition.id` on a get_library or get_media_details record, and that Grimmory requires delete_files=true and forbids add_import_exclusion. It stops short of explaining `instance` or the dry_run/confirm token relationship, which remain schema-only.

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 ("Removes") and enumerates the exact resource per backend: film from Radarr, series/site from Sonarr or Whisparr, book from Grimmory. It also names the sibling it must not be confused with (delete_episode_files), so an agent can route correctly without opening a 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?

Explicit when-to-use and when-not: use delete_episode_files to remove one season's files or specific episodes instead. It also prescribes the workflow ("Previews first; confirm to delete"), warns that `service`+`id` are required and never a title, and tells where to source the 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 flag destructiveHint=true, but the description adds the crucial scope of destruction — the request record goes, downloaded files and Radarr/Sonarr entries remain — which the annotations cannot express. It also discloses the two-phase preview-then-confirm workflow, giving the agent the operational shape of the call.

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 short sentences, front-loaded with the destructive scope, then the alternative, then the identifier source, then the confirm flow. No filler, and the most consequential fact (media is not deleted) appears before anything else.

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 destructive single-entity delete with a full-coverage schema and an output schema, the description covers everything an agent needs: what is removed, what survives, where the id comes from, the sibling alternative, and the preview/confirm requirement. No 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?

Schema coverage is 100%, so the field-level meaning of `id`, `confirm`, and `dry_run` is already documented. The description still adds workflow semantics by stating 'Previews first; confirm to delete it,' which tells the agent the ordering relationship between dry_run and confirm rather than leaving them as independent flags.

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 and resource ('Deletes a Seerr request record entirely') and immediately bounds the scope by clarifying it is not the media. That distinction separates it cleanly from siblings like delete_media and respond_to_request without requiring the agent to open either 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?

Explicitly routes the alternative case: 'Use respond_to_request with `decline` to refuse a request while keeping the record,' and tells the agent where the identifier comes from ('Take `id` from get_requests'). Both a when-to-use-this and a when-to-use-something-else condition are present.

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?

Beyond the readOnlyHint annotation it discloses non-obvious behaviour: the ordered check chain, the cross-service fallback for titles no longer in the library, the `certain: false` marker when a step could not be checked, and service-specific extras (Reclaimerr deletion verdicts, Bazarr subtitle notes, Lidarr artist semantics). The explicit statement that it never executes `next_steps` resolves the main ambiguity an agent could have about a read-only tool that emits remediations.

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 question the tool answers, then progressively narrower detail. It is dense and every clause carries information, but the long compound sentence with the parenthesised chain and the field reference at the end is heavy to parse. Slight trimming would improve scanability without losing content.

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 multi-backend diagnosis tool with an output schema, the description covers the check ordering, fallbacks, uncertainty signalling and the key return fields (`remedy`, `next_steps`, `certain`) that drive how the agent should respond. Nothing needed to call it correctly or interpret a 'could not check' result is missing.

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 80%, so the schema already documents `user`, `service`, `instance` and `query` reasonably. The description adds real meaning for `query` (a human-style title rather than a slug) and the `service`+`id` pairing, but says nothing about the `user` parameter or the `allow_other_users` gate, leaving that entirely 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?

Opens with the concrete user question ("Why is this not playable?") and states a specific mechanism: walks the chain from requested through scanned and names the first failing link with a remedy. That is clearly distinguishable from the sibling getters (get_queue, get_history, get_wanted) and from action tools like trigger_search.

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?

Gives explicit invocation shapes: a title via `query`, or `service` plus `id` when an exact item is in hand, and notes the title falls back to Cleanuparr, download-client history and the event log. It also impliedly draws the boundary from action tools by saying it never runs the suggested steps. It stops short of naming a sibling as an alternative or an explicit when-not-to-use case.

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 only declare readOnlyHint=true, and the description reinforces this with 'Nothing is requested or added'. Beyond that it discloses genuinely non-obvious backend routing: Seerr answers when configured (TMDB ratings), otherwise genre/year/min_rating fall back to a local IMDb dataset with different rating semantics, and similar_to has no fallback at all. That rating-source divergence directly changes how min_rating behaves and would be invisible otherwise.

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 core purpose in the first clause, then progressively narrower caveats. Three sentences with no filler. Dense em-dash phrasing makes it slightly harder to scan than a plain sentence structure would, but nothing is wasted.

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 9 optional parameters, an output schema present, and 89% schema coverage, the description covers the pieces structured data cannot: backend selection, rating provenance, and fallback limits. The one real gap is the unexplained overlap between `kind` (movie/series) and `media_type` (movie/tv), which an agent must guess between.

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 89%, so the baseline is 3. The description earns above that by explaining that min_rating means TMDB's rating under Seerr but IMDb's rating on the dataset fallback, which the schema does not say. It also restates similar_to's exclusivity with genre/year/min_rating, which is already in the schema — though it does not clarify the relationship between the seemingly overlapping `kind` and `media_type` parameters.

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 and resource — browse films/series by genre, year and minimum rating, or find similar titles — and draws the sharp line against sibling tools with 'what exists rather than what you have'. An agent can distinguish this from get_library, search_media and lookup_media without opening schemas.

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?

Gives clear context: use it for discovery (unowned catalog content), and use similar_to when you have a known title as an anchor. It also states the condition under which similar_to is unavailable. It stops short of naming a sibling alternative (e.g. lookup_media or search_media) for when the goal is a known title rather than browsing.

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 declare destructiveHint=true, and the description goes well past that: it names what is replaced (all metadata, hand edits included), that there is no undo on Jellyfin, that locked fields are never overwritten, and that the Jellyfin repair holds the request open so it must not be retried. That is exactly the operational context the boolean hint cannot convey.

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?

Dense and front-loaded: purpose first, then the exclusion, then the destructive warning, then edge-case recovery. It is packed close to the limit of readability and ends with a docs pointer, but every sentence carries distinct information and none is 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?

An output schema exists, so return values need not be explained, and the description instead supplies the parts the schema cannot: preview classification of `numbering` versus `title` findings, how films are judged, the no-retry constraint, and the rename-then-rescan fallback. Nothing an agent needs to call this safely and correctly is missing.

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 the baseline is 3, but the description adds resolution logic the schema only partly carries: title goes in `query`, or the id that get_metadata_issues printed, and books are addressed as `grimmory:<book id>` matched by ISBN or title-and-author. It does not elaborate on `user`, `dry_run`, or `confirm` beyond what the schema already documents, so it is not fully additive.

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 and resource ("Repairs films and series whose Jellyfin or Plex metadata does not describe the file on disk") and makes the failure mode concrete with the `Episode 101` shown as S1E1 example. It explicitly separates itself from `trigger_scan` and points at `get_metadata_issues` for id sourcing, so an agent can route correctly without opening another 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?

Gives the when (metadata doesn't match the file), the when-not ("Not trigger_scan, which never replaces a wrong title"), the sequencing ("Previews first; confirm to apply"), and a conditional alternative path (use trigger_scan `action: "rename"` on the Sonarr series plus a rescan when a refresh cannot move episodes). It also covers the book case with the `grimmory:<book id>` form.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description earns credit for what it adds: newest-first ordering, the provenance of the reason field ("usually relayed from the download client"), and the boundary that download clients have no blocklist of their own. It does not discuss volume or when the list can be empty, but the coverage caveat largely substitutes for that.

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 core purpose is front-loaded in the first clause, and each subsequent sentence carries a distinct payload (reason provenance, symptom, id linkage, ordering, service coverage). The embedded quoted user complaint is slightly loose but earns its place by anchoring the diagnostic use case.

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 output schema covers return shape, and the schema fully documents all five optional parameters, so the description is free to spend its words on the things structured data cannot express: the coverage boundary, ordering, and the foreign keys (mediaId, id) needed to chain into get_media_details and remove_blocklist_item. Nothing an agent needs to call this correctly is missing.

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 limit, offset, detail, service and instance are already documented in the schema, including the enum values. The description only reinforces the service enum boundary (four apps, no download clients) and adds no format or syntax guidance beyond the schema, so the baseline 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?

States a specific verb and resource ("Lists what Radarr, Sonarr, Whisparr and Lidarr have blocklisted") and immediately frames the scope as releases those apps will not grab again. The sibling set contains get_releases and get_history, and the description distinguishes itself from both by naming blocklist status and the repeating-failure symptom rather than generic release listing.

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?

Gives a concrete triggering symptom ("it keeps finding the same thing and never downloading it") and points at get_history as the thing that shows the problem without explaining it, plus remove_blocklist_item as the follow-up action. It does not explicitly exclude the sibling get_releases case (looking at releases that were not blocklisted), so the negative space is implied rather than stated.

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 only declare readOnlyHint=true, and the description adds genuinely useful behavior: results are merged across four services and sorted by date, and each item carries a has-file indicator with the specific rule that an album only counts once every track is on disk. That file-completeness nuance is non-obvious and would be hard to infer from the schema. It does not discuss pagination stability beyond what the schema already says.

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 the resource and sources, then the temporal scope and file-status rule. Every clause carries information; nothing is redundant 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 an output schema present, return-shape explanation is unnecessary, and all five parameters are fully documented in the schema. What remains thin is the relationship to overlapping siblings (get_releases, get_wanted) and any hint about how the merged feed orders items sharing a date.

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 baseline is 3. The description's 'date window' framing loosely maps to days_back/days_ahead and the file-presence note hints at output content, but it adds no format, boundary, or interaction guidance beyond what the schema already documents.

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 a concrete resource (films, episodes, albums due in a date window), the four source services it merges, and the sort order, so an agent knows exactly what comes back. It stops short of distinguishing itself from siblings like get_releases or get_wanted, which sound adjacent and could be confused with a date-window release feed.

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?

Usage is implied rather than stated: the phrase 'date window' plus the note that it covers both upcoming and recently aired items suggests when this is the right call. There is no explicit when-to-use, when-not-to-use, or named alternative such as get_releases for a different view of the same data.

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?

readOnlyHint=true is consistent with a history read. Beyond annotations it discloses genuinely useful behaviour: results are merged across many backends into one vocabulary with the upstream word kept in `rawEvent`, failures carry the download client's own message, and deleting a title also destroys its Radarr/Sonarr history. It stops short of describing pagination stability or response shape (offset warns items can move between pages only via the schema).

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 core definition, then escalation to the failure-diagnosis use case and the deletion caveat. Dense but nearly every clause carries new information; the parenthetical service inventory is long but earns its place by signalling coverage breadth.

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 return values need no explanation, and the description covers sources, scoping, and the history-loss caveat. Minor gap: it doesn't state whether merged multi-service results can fail partially or how `detail` levels differ, though the schema covers the latter.

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 the baseline is 3; the description still adds cross-tool meaning by tying `service`+`id` to a single movie/series/artist and by linking the returned `downloadId` to an *arr grab and to trigger_scan's postprocess action. It also points to arr://docs/get_history for the field reference rather than duplicating 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?

States a specific scope: 'What happened to a download after it left the queue (grabbed, imported, failed, deleted), merged across the *arrs, SABnzbd, NZBGet...'. It enumerates the normalised event vocabulary and names the sibling it differs from (get_queue), so an agent can pick it 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?

Explicit when-to-use with the motivating question ('why did last night's download fail') and the exclusion ('get_queue cannot see finished or failed items'). It also gives conditional routing: pass `service` and `id` to scope to one title, and use `source: "webhooks"` when a title was deleted and its *arr history is gone.

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 safety profile is covered, but the description still adds real context: what detail levels expose, that disable reasons are surfaced, and that indexer-supplied failure text is fenced as untrusted data. That last point is a meaningful disclosure an agent would otherwise not know. Pagination hazards are left to the schema rather than restated here.

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 the payload contents before the detail-gating clause and the untrusted-data caveat. The first sentence is dense with em-dashes but each clause carries distinct information. No filler or restatement of the tool name.

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 return values need not be explained, and the read-only annotation covers safety. The description fills in the parts structured fields cannot: what the data means and that indexer-authored strings are untrusted. The only gap is routing guidance relative to the many sibling diagnostic 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 coverage is 100%, so a baseline of 3 would be defensible, but the description genuinely extends the 'detail' parameter: the schema only says 'how much per-item detail', while the description tells the agent that full is what surfaces recently rejected queries and their reasons. limit and offset receive no added meaning beyond their already-complete schema text.

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 (Prowlarr indexers) and enumerates exactly what is reported: enabled/disabled state, disable reasons, per-indexer query and grab counts, and rejected queries at full detail. That is far more specific than the bare name 'get_indexers'. It stops short of 5 because it never distinguishes itself from near-neighbours such as diagnose, stack_health, or manage_indexer.

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?

Usage is only implied: an agent can infer this is the read-only health/monitoring view of indexers. There is no explicit statement of when to call it versus diagnose or stack_health, and no pointer to manage_indexer for actually changing an indexer's state. The one conditional it does give — 'at detail: full' unlocks rejection data — is about parameters, not tool 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?

With readOnlyHint already declaring the safety profile, the description goes well beyond it: it explains what each `presence` value means operationally (arr_only + file = likely broken import; jellyfin_only = unmanaged media; unknown = other half not read), instructs the agent to report `degraded`/`note` reasons instead of mislabelling items unwatched, and warns that an artist's `monitored` is the artist-level flag, not the album flag.

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 purpose and the sibling hand-off before the caveats, and almost every sentence carries non-obvious information. It is dense and backtick-heavy, with a few clauses that restate schema points, but no padding of the kind that would obscure the main routing signal.

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 an 18-parameter read tool with an output schema, the description covers exactly what the schema cannot: cross-service join semantics, degraded-read handling, monitored-flag ambiguity, and the detail/rating-source prerequisites. It also points to arr://docs/get_library for the full field reference, so remaining gaps are addressable.

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 89%, so the baseline is 3, but the description adds real meaning on top: it clarifies that `presence`'s jellyfin naming is fixed regardless of configured server, that `rating_source` defaults to the widest-coverage source and that IMDb series ratings require the dataset, and that `detail: "full"` is a prerequisite for seasons and folder paths. It adds less for the plain filter params, which the schema already documents well.

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 first sentence names the specific resource (a cross-service library union over Radarr/Sonarr/Whisparr/Lidarr/Grimmory plus the media server), the join key (shared external ids) and the entity types covered. It also explicitly contrasts with get_media_details for single-title lookups, so an agent can route without opening either 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?

Explicit division of labour: 'Use it for filtered lists and counts; for one title use get_media_details.' Beyond that it gives task-level guidance for the hard cases — 'has_file: false with monitored: true is what you are still waiting for', and when to ask for `rating_source: "imdb"` or `detail: "full"`.

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 only declare readOnlyHint=true, and the description adds real behavioral context: merged vs. raw sourcing, an `ambiguous: true` plus `candidates` outcome for tied title matches, refusal-with-metadata for titles not in the library, and per-season monitoring consequences downstream. It does not cover pagination or how `limit` interacts with `detail` for large series.

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 a one-line scope statement, then a dense sequence of mode, caveat, and field notes with no filler sentences; the pointer to arr://docs/get_media_details correctly offloads the exhaustive field list. Its length is justified by the number of non-obvious behaviors it must surface.

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 return values need not be enumerated, and the description still highlights the fields an agent would otherwise misread (`seasons`, `monitored`, `audioLanguages`, `cleanup`). Slightly incomplete on result-volume behavior (`limit` default 50, max 500) when `query` matches many items.

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 the baseline is 3; the description earns above that by explaining what `query` actually matches (original and alternate titles, ambiguity handling) and what `detail: "full"` changes structurally, which the schema only labels. `limit` and `instance` are left to their schema text.

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 concrete retrieval verb and resource ("Everything known about one item") and distinguishes its two access modes: merged record via `query`, raw single-service view via `service`+`id`, with `detail: "full"` expanding to episodes/albums. It never names the sibling reader tools (get_library, search_media, lookup_media) directly, though the note that a miss returns metadata "so no other search is needed" implicitly routes away from them.

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?

Gives mode-selection guidance with reasons: `service`+`id` is "for checking a join that looks wrong"; `detail: "full"` when you need per-episode or per-album ids. It adds a concrete pre-condition for a destructive sibling ("check `monitored` before delete_episode_files") and tells the agent which field to trust when resolving dub presence.

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?

Beyond the readOnlyHint annotation it discloses the real cost profile (slow, one call per series), the shape of each result row (numbering vs titleOnly confidence, the three remedy values and when no refresh will help), and the untrusted-data fencing of titles and paths. It also notes the Grimmory-specific low-match-score branch, none of which is recoverable from 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?

Front-loaded with the purpose and the sibling comparison, then behavior, then the pointer to a deeper doc. It is dense with backtick-heavy clauses and the remedy enumeration sentence takes a re-read, but almost every clause carries operational 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?

For a read-only sweep with a full output schema, an agent has everything needed: cost expectations, the pagination caveat, how to consume each row, and how to act on the result. Return-value detail is a bonus rather than a gap since the output schema exists.

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 limit, offset and detail are already fully documented including the offset/sort interaction. The description adds nothing about pagination or detail levels, which is the expected baseline when the schema carries that load.

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 and resource at a defined scope: it sweeps the whole library for series whose metadata does not describe files on disk. It explicitly contrasts itself with the sibling fix_metadata, so an agent can pick between them without opening either 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?

Gives the exact routing rule: this is the discovery step fix_metadata cannot do because that tool needs a title, and a returned row's `service:itemId` is fed to fix_metadata as `id`. That is a full when-this/when-the-other plus the handoff between 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?

Beyond the readOnlyHint annotation, the description discloses the Jellyfin-specific behaviour of pulling plays from the activity log that were never marked played, the `source: "activity_log"` tag, a 30-day default log retention, the allow_other_users authorization requirement for reading another user, and the empty-plus-note behaviour when no server is configured. These are exactly the non-obvious traits an agent needs to interpret results correctly.

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 core purpose, then scope enumeration, then auth and empty-state caveats, then a docs pointer — a sensible information order. It is dense, and the Jellyfin activity-log caveat is repeated in both description and schema, but no sentence is wasted 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?

With a rich 5-parameter schema, 100% description coverage, and an output schema covering return fields, the description fills the remaining gaps: default-user behavior, permission gate, empty-state semantics, and the Jellyfin log caveat. Nothing an agent needs to call it or interpret an empty response is missing.

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 already documents all five parameters, so the baseline is 3; the description nudges above it by framing what each scope semantically means for the user (resumable position, 'your media server's own answer to what to watch next') and by pointing to a field reference for return shapes. The `user` and allow_other_users detail largely restates 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 opening clause states a specific resource and the three things it can return (watching, next, watched), and the note that 'watch state exists only on the media server' distinguishes it from library/metadata siblings like get_library or get_media_details. An agent can tell what this tool answers 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?

Each scope is given an explicit condition for selection (now playing vs next unwatched episode per in-progress series vs recent plays), plus a concrete handling instruction for the empty-result case when no media server is configured. It stops short of naming sibling alternatives such as get_history, leaving the read-history vs playback-history boundary implicit.

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?

readOnlyHint is already supplied, but the description adds substantial behavior beyond it: every `remedy` is advisory and 'never one arr-mcp performs', drift findings are instance-scoped rather than per-profile, and `note` reports the case where nothing was configured to check. The per-profile independence caveat ('a finding on some profiles says nothing about which others score the same format') prevents a real misreading. It does not cover result volume or truncation behavior, but with an output schema present that is a minor gap.

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?

Content is front-loaded with the fault taxonomy, and the caveats are ordered after it, which is the right sequence. The opening sentence runs long by piling six fault types into one clause chain, which slows scanning, but no sentence is 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 read-only diagnostic with a fully documented schema and an output schema, this covers everything an agent needs: what is checked, how findings are scoped, how filtering interacts with drift, that remedies are not executed, and what an empty `note` means. Nothing material is missing.

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 limit, offset, detail, profile, service and instance are all already documented, establishing the baseline of 3. The description adds one genuine piece of meaning the schema lacks: that the `profile` filter does not constrain drift findings. That is useful but narrow.

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?

Opens with a concrete resource and scope: 'Faults in Radarr, Sonarr and Whisparr quality profiles', then enumerates the specific fault classes (unreachable minimum custom format score, edge scores, language coverage gaps, Profilarr drift). An agent knows exactly what class of findings this returns. It stops short of naming the nearest sibling (get_metadata_issues) to draw the boundary, so it is clear on its own but not fully differentiated.

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?

Usage context is implied (diagnostic auditing) and one real filter rule is stated: drift findings are instance-scoped and 'unaffected by the `profile` filter'. But the description never says when to reach for this versus get_metadata_issues or diagnose, nor does it state prerequisites such as needing configured profiles in Profilarr.

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?

Consistent with readOnlyHint: true and adds substantial context the annotations cannot carry: data is merged across eight clients, sizes are bytes and ETAs seconds, release names are fenced as untrusted data, and detail: "full" adds seeding and Cleanuparr strike/dueAt fields. It also discloses the retry-vs-fix-in-service distinction, which is exactly the behavioral nuance an agent needs.

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-loads the resource scope in the first clause and then layers the actionable details; every sentence carries information. It is dense and long-sentenced, and the cleanuparrDue totals note is somewhat niche, but nothing is redundant 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?

An output schema exists, so return-shape explanation is not required, yet the description still pre-explains the notable per-item fields and their units. For a three-optional-parameter read tool spanning multiple backends, an agent has everything needed to call it 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 100%, so the baseline would be 3, but the description adds real meaning to the detail enum by spelling out what appears at "full" (seeding ratio, time seeded, limit, overLimit, Cleanuparr rule, strikes, dueAt). limit and offset are left entirely to the schema, which already documents them well including the pagination-plus-sort caveat.

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?

Opens with a specific resource and scope: everything downloading or stalled, merged across eight named services plus Bookdrop. That is clearly distinguishable from siblings such as get_history, get_wanted and get_releases, which cover different states of the media lifecycle.

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?

Routes the agent to concrete alternatives in context: remove_queue_item for removing a row and trigger_scan with action: "import" plus a downloadId for importBlocked items. It also explains the failure case that cannot be retried (title mismatch/unknown episode), which implicitly tells the agent when not to retry. It stops short of an explicit statement of when to prefer get_queue over get_history or get_wanted.

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 only declare readOnlyHint=true; the description adds the behavior that actually matters: synchronous polling of every indexer, 15s+ typical, 120s timeout, and an explicit no-retry instruction. It further discloses refusal behavior (`season` refused on Radarr, `episode` mutually exclusive with `season`) and a data quirk (`seeders` absent, not zero, on usenet) that no other field carries.

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?

Purpose is front-loaded in the first sentence, followed by differentiation, then the slow/timeout warning and per-service narrowing rules — a sensible order. The prose is dense but nearly every clause carries a distinct, actionable fact; the bolded '**Slow**' aside and the field-reference pointer at the end are slightly crammed rather than cleanly separated.

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 10-parameter, five-service tool, this covers the things an agent would otherwise get wrong: latency and retry policy, service-specific parameter refusals, breadth controls, and the book path via shelfmark. Return shape is partly covered by the existing output schema, so the description is not obligated to explain values, and it still explains what `rejections` means and where `guid` lives.

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 already 90%, so the baseline is 3; the description earns above that by adding cross-parameter meaning the schema lacks — that Lidarr's `id` is the artist so `album` should be passed to avoid thousand-row responses, that `episode` is far faster than `season`, and that `detail: "full"` is what surfaces the `guid`/`indexerId` `grab_release` needs. It does not restate schema text, but it also doesn't touch `limit`, `offset`, or `instance`, leaving a small gap.

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 and resource — runs the same interactive indexer search the *arr UI runs — and scopes the output precisely (every candidate, rejected ones included, with `rejections`). It explicitly contrasts itself with `trigger_search` and names `grab_release` as the consumer of its `guid`/`indexerId`, so an agent can place it in the workflow without opening siblings.

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?

Gives explicit routing rules: use this instead of `trigger_search` when you need to see what was found, keep searches narrow (episode over season on Sonarr, album over artist on Lidarr), and use `service: "shelfmark"` for books. It also includes a when-not rule — 'a long wait is not a hang: do not retry' — which is exactly the kind of exclusion agents otherwise get wrong.

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?

Beyond the readOnlyHint annotation it discloses an authorization prerequisite (allow_other_users), the default-user behavior, and a graceful-degradation trait — issues may fail while requests still succeed. That partial-failure note is genuinely non-obvious behavior an agent needs. It stops short of 5 because pagination stability and ordering are left entirely to the schema.

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, front-loaded with resource and scope before the detail-level caveat. The closing clause about a Seerr that cannot answer for issues is a little convoluted but carries real information, so it 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?

An output schema exists, so return values need no explanation; the description covers the pieces the schema cannot — permission requirements, defaulting, and the issues side-channel. For a five-parameter read tool with full schema coverage and annotations, this is close to 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 description coverage is 100%, so the baseline is 3; the description earns an extra point by explaining what 'full' detail actually adds (issues with newest comments) and by clarifying that issues span all users, not just the requested one. The user/allow_other_users wording duplicates the schema rather than extending 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 (media requests in Seerr) and its scope (one user, states pending/approved/declined), which lets an agent distinguish this read tool from the mutating siblings respond_to_request and delete_request. The verb is only implied by the tool name rather than stated outright, which keeps it just short of a 5.

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 useful context — defaults to the configured user, reading another needs allow_other_users — and signals that no separate issues call is needed when detail is 'full'. It never explicitly states when to prefer this over get_media_details, get_metadata_issues, or the request-mutation siblings, so routing still requires inference.

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?

Beyond readOnlyHint=true, it discloses that results span two media types, that per-item wanted languages are included, that provider state (working/throttled/blocked) is folded into the response, and that release names are externally sourced and fenced as untrusted data. That last point is a meaningful safety-relevant behavior an agent would not otherwise know; only return shape and ordering are left unaddressed.

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 tight sentences with the scope and the diagnostic rationale front-loaded, and the untrusted-data caveat placed last where it belongs. The opening is a verbless noun phrase ('Subtitles Bazarr knows are missing') which reads slightly as a label rather than an action, but nothing is wasted.

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 an output schema present, return-value detail is not required, and the three optional scalars are fully documented in schema. The description supplies the scope and the diagnostic framing an agent needs; only explicit sibling routing is missing, which is a minor gap for a read-only 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 description coverage is 100%, including the limit cap, the detail enum, and the offset/sort pagination caveat, so the schema carries the parameter burden. The description adds no per-parameter meaning (e.g., whether 'detail: full' includes provider diagnostics), so baseline 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?

States a specific resource (subtitles Bazarr knows are missing) with explicit scope: both films and episodes, wanted languages per item, plus provider health. This is clearly distinguishable from siblings like get_wanted (missing media) and trigger_subtitle_search (an action), so an agent can select it without opening a 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?

The description implies the use case by noting provider status is 'usually why something is missing', which points at diagnosis. But it never explicitly says when to call this versus get_wanted, diagnose, or trigger_subtitle_search, and offers no exclusions or prerequisites, leaving the routing decision partly to inference.

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 only declare readOnlyHint=true, and the description adds substantial behavior: Lidarr albums missing any track can appear in both lists, unmonitored gaps are excluded, and `detail: "minimal"` drops titles and air dates. It also points to arr://docs/get_wanted for the field reference, though it does not discuss pagination stability beyond the schema's own note.

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-loads the core purpose and scope definitions, then layers service-specific caveats. Dense but nearly every sentence carries distinct information; the field-reference pointer is a small extra that could be trimmed.

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 an output schema present, return values need not be explained, and the description covers the remaining complexity: scope semantics, per-service row shapes, Lidarr dual-list behavior, and detail levels. Nothing an agent needs to call it correctly is missing.

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 the baseline is 3, but the description adds meaning beyond the schema: it links Lidarr `albumId` to set_monitoring with `level: "album"` and explains the consequence of `detail: "minimal"`. The `service`/`instance`/`limit`/`offset` semantics are left 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?

States a specific resource (Radarr/Sonarr/Lidarr wanted lists) and defines the two scopes precisely: missing = monitored with no file, upgradable = file below quality cutoff. It explicitly distinguishes itself from the sibling get_library by noting it lists missing episodes one by one.

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?

Gives explicit selection criteria for `scope` (the two answer different questions), names the alternative get_library and how it differs, and states exclusions such as unmonitored gaps never appearing and unmonitored artists' albums being left out. An agent can pick this tool and the right scope without inference.

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 only say this is a non-read-only, non-destructive mutation; the description goes much further by disclosing the preview-then-confirm flow, that the confirm token is single-use and bound to the previewed arguments, that previewing is slow because it re-runs the search, and that a magnet bypasses any *arr vetting or import. It also flags that indexer-supplied release names are fenced and must not be treated as instructions, which matters for a tool that echoes external strings.

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?

Dense but front-loaded: the core action and the primary identifier path come first, followed by service-specific caveats, then safety and undo. Every sentence carries operational information, including the fencing warning and the slow-preview cost, 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 12-parameter, multi-service mutation tool with a preview/confirm cycle, the description covers the selection path, scope preservation, service-specific quirks, bypass risks, cost, and reversibility. An output schema and full parameter descriptions already exist, so nothing material is left for it to explain.

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 100% schema description coverage the baseline is 3, but the description adds cross-parameter meaning the schema does not convey alone: that `season`/`episode`/`album` must match what get_releases used so the preview stays in scope, that `magnet` is mutually exclusive with `guid`, and that `id` alone selects the most-downloaded release on Shelfmark. The schema already documents most individual fields thoroughly, so it stops short of a 5.

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?

Opens with a specific verb and resource ("Grabs one release listed by get_releases") and adds a memorable alias for the exact intent ("not that one, the 1080p remux"), which cleanly separates it from the sibling that lists releases. Supported services are enumerated, so an agent knows the scope immediately.

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 routes the agent: pull `guid` and `indexer_id` verbatim from get_releases at detail "full", or use `release_title` exactly as listed, and says the call is refused when no row or multiple rows match. It names the magnet alternative and its consequence, and points to remove_queue_item as the undo path.

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?

Goes beyond the readOnlyHint by spelling out the consequence ('nothing is added, requested or monitored') and by disclosing per-source quirks — Lidarr hits are artists keyed under `ids.mbid`, and id-prefix handling changes coverage. No contradiction with annotations; it reinforces 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?

Front-loaded with the core purpose, then tight clauses on source-specific caveats; nearly every sentence carries operational weight. It is dense with backticked syntax and cross-references, which costs a little readability but not correctness.

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 and all four parameters are documented, so the description only needs to cover multi-source semantics and id handoffs — which it does. Minor gaps remain: nothing about behavior on ambiguous or zero-hit queries, and the relationship to search_media is unstated.

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, but the description adds real meaning to `query` by documenting prefix syntax (`imdb:tt…`), the `kind: book` selector, and how returned ids feed get_releases and add_media. `limit`, `offset`, and `detail` are left entirely 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?

Names a specific operation and resource ('Metadata for something you may not have: title, year, and external ids') and enumerates the backing sources (Radarr, Sonarr, Whisparr, Lidarr, Seerr, Shelfmark). The 'something you may not have' framing separates it from library/detail tools like get_library or get_media_details without needing to name them.

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?

Gives concrete usage conditions: use `kind: book` for Shelfmark results, query `imdb:tt…` to resolve an IMDb id to a TMDB id, and note that a bare `tt…` will miss Seerr. It does not explicitly contrast with search_media or discover_media, so the when-to-use-vs-siblings case is only implied.

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 annotations only say destructiveHint=true for the whole tool, but the description clarifies that only delete is destructive and irreversible while add/edit/disable/enable are 'safe tier' — a genuinely useful refinement of the coarse annotation. It also discloses cross-app effects (disable stops grabs everywhere, delete propagates to synced apps) and that edits are not received by apps at Add and Remove Only. It does not cover rate limits or what the preview payload looks like, keeping it just short of a 5.

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 action list is front-loaded and each sentence carries operative information for a 5-action, 13-parameter tool. The closing pair about previews slightly restates the confirm/dry_run semantics already stated earlier and in the schema, which is the only real 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 five distinct actions, a destructive branch, cross-app sync effects, and a preview/confirm protocol, the description covers prerequisites, side effects, reversibility, and where ids come from. With an output schema present and full parameter documentation, nothing an agent needs to call this correctly is missing.

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 the baseline is 3; the description nonetheless adds meaning by bounding which parameters edit actually honors ('priority, app profile, tags and torrent seed settings, nothing else') and by clarifying the preview/confirm token binding. The seed-related parameters are left to the schema alone, so it is useful but not exhaustive beyond structured data.

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 specific resource (one Prowlarr indexer) and enumerates every verb it supports (add, edit, disable, enable, delete) plus the side effect of syncing to Radarr and Sonarr. It is immediately distinguishable from the read-only sibling get_indexers, which it explicitly points to for ids.

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 per-action guidance rather than a single generic sentence: add only works for public indexers needing no login and refuses private/semi-private ones, edit is limited to priority/profile/tags/seed settings, disable applies in every app regardless of sync level. It also states the required workflow (preview first, then confirm) and where to get the 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 a safe, non-destructive write, and the description reinforces that with the explicit reversibility model: "the undo is this same tool with the other action." It further discloses the preview-then-confirm apply flow and the non-obvious side effect that *arr services keep sending releases into a paused client.

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 multi-action purpose and the scope trap, and every sentence contributes operational information. It is dense rather than wasteful, though the quoted example phrasing and em-dash chain make it longer than strictly necessary.

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?

Output schema exists, so return values need not be explained, and the description covers the decision-critical traps: per-client scope, item vs client-wide limiting, and downstream *arr behavior. Nothing essential is missing for a 7-parameter tool with a preview/confirm flow.

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 86%, so the schema already carries most parameter meaning and 3 is the baseline. The description adds real value on a few points — limit is client-wide and never per item, 0 removes the cap, `service` must name exactly one client — but leaves `instance` and the confirm/dry_run token lifecycle 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?

States a specific verb set (pauses, resumes, throttles) and a precise resource scope (one download client among four named clients), plus the item-level variant gated on `id`. It is unmistakable against siblings like `get_queue`, `remove_queue_item` and `retry_download`.

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?

Maps a concrete user intent ("stop downloading for an hour") to the exact invocation, and distinguishes throttling from stopping with the `action: "limit"` path and 0-to-uncap rule. It also states the exclusion that matters most — it does NOT stop Radarr/Sonarr grabbing — and clarifies that pausing "everything" requires one call per client.

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?

Goes well beyond the annotations: it declares the operation safe because "nothing on disk changes," explains that the entry is only a refusal to grab, and documents the reversibility path. It also discloses the preview-then-confirm protocol and that the token is single-use and bound to the previewed arguments. Only gap is that instance/error behavior is left implicit, and the output schema already covers return values.

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?

Purpose is front-loaded in the first clause and every sentence adds operational value. Minor redundancy in repeating the full product list ("Radarr, Sonarr, Whisparr or Lidarr") twice, which could be compressed to a single mention.

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 5-parameter, non-destructive mutation with an output schema and annotations already present, this description covers the prerequisite lookup, the effect, safety, reversibility, and the confirm flow. Nothing an agent needs before calling it correctly is absent.

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 80%, so the baseline is 3, but the description adds real meaning: it tells the agent where `service` and `id` come from (a get_blocklist row), which is not in the schema. The preview/confirm sentence also clarifies the intended order of `dry_run` and `confirm` beyond their individual field descriptions.

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?

Opens with a specific verb and resource ("Removes one entry from ... blocklist") plus the downstream effect ("so that release can be grabbed again"). It is clearly differentiated from the read-side sibling get_blocklist, which is named as the source of the arguments.

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 frames the trigger scenario ("this never downloads and I do not know why" once get_blocklist has said why) and states the prerequisite sequencing (call get_blocklist first, copy `service` and `id` from a row). It also names an alternative re-blocklist route via remove_queue_item's `blocklist` flag, so the agent knows both directions of the operation.

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?

Goes well beyond the destructiveHint annotation: it discloses per-service side effects (blocklisting only on Radarr/Sonarr/Whisparr/Lidarr, NZBGet parking kept data in history, Shelfmark cancelling queued/running books, Grimmory deleting the file from disk and refusing `remove_from_client: false`). The preview/confirm two-step and its refusal cases are exactly the kind of behavioral context an agent needs before a destructive call.

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?

Purpose and scope are front-loaded, then service-specific caveats follow in a compact sequence. It is a dense block rather than a list, but nearly every clause carries distinct information; only the long service enumeration is somewhat list-like 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 annotations covering the destructive profile and an output schema covering returns, the description fills the remaining gaps: prerequisites (get_queue), the confirm-token flow, and service-specific exceptions. A little is left implicit, such as what happens to partial data on Transmission/qBittorrent beyond the `remove_from_client` default, but nothing blocking.

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 86%, so the baseline is 3, but the description adds real meaning on top: the scoping of `blocklist` to four services and the Grimmory override where `remove_from_client: false` is rejected. It does not explain `instance` selection or `dry_run` nuances beyond what the schema already says.

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 and resource ('Removes one item from a download queue') and immediately narrows scope to the stuck/wrong-release/stalled download case, which separates it from siblings like clean_queue and delete_media. The enumeration of ten supported services makes the tool's domain 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?

Gives clear operational guidance: take `service` and `id` from get_queue, preview first, then confirm to apply. It does not explicitly name an alternative for bulk cleanup (clean_queue) or explain when to prefer delete_media, so routing between siblings is only partly covered.

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 only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond them, disclosing the approval queue, quota accounting, the permission gate for other users, and the preview-then-confirm mutation pattern. This is strong added context on top of thin annotations, but it stops short of describing what the resulting request object or failure modes look like.

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?

Dense but front-loaded: identity and the add_media contrast come first, then id semantics, then the preview/confirm step. It is one long paragraph with heavy parentheticals, which costs a little scannability but almost every clause carries 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?

For a mutating, quota-affecting tool with a preview/confirm flow, it covers the alternative, the permission prerequisite, id provenance, season defaults, and user attribution; return values are covered by the output schema, so nothing an agent needs to call it correctly is missing.

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 already 100%, yet the description adds real meaning: media_id must be a TMDB id, an IMDb tt… id must be resolved via lookup as imdb:tt…, Seerr resolves TVDB itself, and seasons defaults to all seasons and is refused on a movie. Only the confirm/dry_run semantics are left entirely 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?

States a specific verb and resource ("Asks Seerr for a film or series") and immediately frames the scope as an end-user web-UI request that enters an approval queue. It explicitly contrasts itself with the nearest sibling, add_media, so an agent can route between them without opening either 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?

Gives an explicit selection rule ("This is the tool for 'request X'") plus a when-not rule naming add_media and its differing behavior (writes to Radarr/Sonarr, skips approval and quota, needs that service's write permission). It also names the prerequisite services.seerr.allow_other_users for non-default users.

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?

Goes well beyond the readOnlyHint=false / destructiveHint=false annotations by disclosing the downstream consequence: approval hands the item to Radarr or Sonarr, triggering a search and download that consumes disk space and bandwidth. It also clarifies that the decision itself is reversible, and documents the preview/confirm token flow, which is exactly the behavioral context an agent needs before mutating state.

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 short sentences, front-loaded with the action, then the cost consequence, then the workflow. No filler and nothing buried.

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 return values need no explanation, and the cost/reversibility/preview details cover the main risks of a mutating tool. The one gap is what a decline actually does to the underlying request versus delete_request, which the agent must infer from siblings.

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 the baseline is 3. The description adds provenance for `id` (from get_requests) and frames the preview-then-confirm sequencing that ties `confirm` and `dry_run` together, giving marginal meaning beyond the field-level docs.

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 pair and resource: approves or declines a pending Seerr request. This is clearly separable from siblings like delete_request (permanent removal) and get_requests (listing), so an agent can pick it without opening another 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?

Gives explicit workflow guidance: take `id` from get_requests, preview first, then confirm to apply. It does not explicitly contrast with delete_request or explain when declining is preferable to deleting, but the routing instruction is unambiguous.

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?

Beyond the annotations, it discloses per-service behavior (a password-paused SABnzbd job is unlocked, an NZBGet job with missing articles is refetched, an unpack failure is re-post-processed) and that the password is never echoed back. It also warns that the preview checks whether Radarr or Sonarr already grabbed a replacement, avoiding duplicate copies.

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 core action and the preview-then-confirm model are front-loaded and each sentence carries operational content. It is dense and slightly overlong in the per-service behavior list, but nothing is truly redundant.

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 6-parameter mutation with an output schema and preview token flow, the description covers dispatch logic, credential sourcing, prerequisites, and the fallback path. Nothing an agent needs to invoke it correctly is missing.

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 already 83%, so the baseline is a 3; the description goes further by explaining the origin and sensitivity of password and the provenance of id. It says less about instance (multi-instance disambiguation) and nothing that extends the dry_run semantics already in 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 first sentence names a specific verb (retries) and a precisely scoped resource (one failed download on SABnzbd or NZBGet, or a failed/cancelled book on Shelfmark), then enumerates which failure modes it handles per client. An agent can distinguish this from siblings like get_history, get_queue, and trigger_scan without opening any 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?

It states where to source the id (the get_history or get_queue row), when to supply password, when to prefer a scan, and the preview-then-confirm workflow. It also names the concrete alternative path -- trigger_scan with action: "import" -- for the case where no *arr imports the result.

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 is consistent with that. It adds genuinely non-obvious context beyond the annotations: that indexer results carry attacker-controllable release names and come wrapped in an explicit untrusted-data boundary, which is a safety-relevant behavioral trait an agent should know before trusting returned strings.

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 filler; the scope statement comes first and the security caveat second. Every clause carries information the agent needs.

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 a full input schema, an output schema, and readOnlyHint already present, the description only needs to supply scope and the trust caveat, and it does both. The remaining gap is sibling routing advice against lookup_media and discover_media, which the description leaves unaddressed.

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 query, limit, offset, detail, and source are all documented in the schema, including the untrusted-data note on source. The description adds no parameter-level detail beyond what is already structured, so the baseline 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?

States a specific verb (search) and names three concrete scopes: existing library, metadata for titles not owned, and indexer offerings. That scope statement implicitly separates it from get_library and discover_media, but no sibling is named explicitly, so differentiation still requires the agent to infer from the source enum.

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 three-scope framing implies when each mode applies and the schema's source enum spells out library/discover/indexers. However, there is no explicit guidance on when to pick search_media over lookup_media, discover_media, or get_library, and no exclusions or prerequisites are stated in the description itself.

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