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

With no annotations, the description carries the full behavioral disclosure burden. It transparently states the actions: audits, flags failures/bans, and reports system health warnings. This conveys a read-only monitoring operation and makes side effects (or lack thereof) reasonably clear. No contradiction exists.

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?

A single, well-structured sentence that leads with the action verb 'Audits' and packs all relevant details without redundancy. Every word earns its place; there is 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 no-parameter tool with no output schema, the description fully covers what the tool does and what it reports. An agent has everything needed to invoke and interpret the result. No gaps that would hinder correct usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the schema is empty (100% coverage). The description adds meaning by explaining the tool's purpose, but since there are no parameters to document, the baseline of 4 applies. Nothing more is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Audits'), a specific resource ('Usenet indexers and torrent trackers configured in Prowlarr'), and a precise outcome (flag connection failures/bans, report health warnings). This clearly distinguishes it from siblings like get_cluster_infrastructure_health, which targets a broader infrastructure scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: this tool is for auditing indexer/tracker connectivity in Prowlarr. It does not explicitly name alternatives or when-not conditions, but the context is specific enough that an agent can infer when to use it. Lacks the explicit routing that a 5 would require.

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 no annotations provided, the description must carry the behavioral burden. It conveys a read-only check and names the output (monitoring status and artwork), but it does not describe behavior when the movie is absent, error conditions, or explicitly confirm no side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that states the action, resource, and output with no filler or redundancy. Every phrase earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description should clarify the return contract more fully. It says monitoring status and artwork are returned, but not what the output looks like when the movie is not found or how 'monitoring status' is represented. This is adequate but has clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the parameter is already documented as 'The exact title of the movie to search for.' The description adds context about the Radarr library but does not meaningfully enrich the title parameter beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific action ('Checks if a specific movie exists'), a concrete resource ('Radarr library on the Ubuntu cluster'), and a distinct outcome ('returns its monitoring status with artwork'). This clearly differentiates it from siblings like search_and_select_movies or diagnose_missing_media.

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 intended use is implied: call it when you need to verify a movie's presence and monitoring status. However, the description never explicitly says when to prefer this tool over siblings, nor does it mention alternatives or exclusions.

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 no annotations, the description carries the full burden and does well: it discloses the data source (Sonarr), the return contents (downloaded aired count, missing seasons/episodes, unaired episodes, monitoring status), and a key limitation (doesn't reflect Plex scanning). It stops short of stating read-only nature or any rate/auth behavior, but the query semantics are otherwise clear.

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 it answers, then the returned contents, then the sibling alternative and the boundary. Dense but every clause earns its place with zero 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 2-param query tool with no output schema and no annotations, the description enumerates what the result includes and clarifies the data source and its Plex blind spot. It does not describe the exact response shape, but the content coverage is sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (title, year) are already documented in the schema, including the year's disambiguation role. The description adds no syntax or format detail beyond what the schema provides, which is the baseline 3 case.

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?

It states a specific verb+resource framed as a question it answers ('do I have every episode of <show>?') and names the exact data source (Sonarr's episode list) and returned contents. It explicitly distinguishes itself from the sibling find_series_gaps. An agent can select it correctly 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?

It gives an explicit when-to-use ('for one specific TV show'), names the alternative for the opposite case ('use find_series_gaps to see which shows have gaps'), and adds a boundary exclusion ('does not check what Plex has scanned'). Both the routing rule and the negative scope are stated, not 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?

No annotations are provided, so the description carries the full behavioral burden. It richly describes the informational scope of the response (monitoring, quality, queue, download counts), which signals a read-only status lookup, but it never explicitly states read-only/safe behavior or any auth or rate-limit constraints. Strong on what it reports, thinner on safety profile.

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 identity ('TV counterpart of check_movie_status') before the attribute list, then usage examples, then alternatives. The attribute enumeration is somewhat dense, but each element is informative and no sentence 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 no output schema and no annotations, the description does the heavy lifting by enumerating exactly what the tool returns, so an agent knows what to expect. It does not cover error behavior or output format, leaving minor gaps for a status-query tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with title and year both documented in the schema (including the same-named-show disambiguation rationale). The description adds no syntax or format detail beyond the schema, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (what Sonarr knows about one show) and enumerates the exact data points returned: monitored state, quality profile, location, next episode air date, last download, queue contents, and downloaded count. It positions itself explicitly as the TV counterpart of check_movie_status, making it easy to tell apart from 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 concrete trigger phrases ('is <show> monitored?', 'what quality is <show>?', 'when does <show> come back?') and routes two adjacent questions to explicit alternatives: check_series_completeness for which episodes are missing and diagnose_missing_episodes for why. When-to-use and when-not-to-use are both 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?

With no annotations, the description carries the full burden, and it discloses key behaviors: adding monitored movies, starting download searches, avoiding duplicate additions, and default quality profile/root folder fallbacks. It could go further by describing result reporting format, but the core side effects are transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences cover the main action, duplicate handling, and defaulting logic without waste. The most important purpose is front-loaded, and each sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is largely complete for a mutating workflow tool: it explains what happens, the dependency on a prior search grid, and fallback defaults. It does not describe the output/report format, and with no output schema this is a minor gap, but the essential invocation context is present.

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 meaning beyond the schema by explaining the fallback order for qualityProfile and the default rootFolder behavior. It also ties chosenIndexes to the user's numbered selections from the search grid.

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: 'Adds the user's numbered choices... to Radarr as monitored movies and starts a download search for each.' This clearly distinguishes it from siblings like search_and_select_movies and check_movie_status.

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?

Establishes clear context by referencing 'the last search_and_select_movies grid,' indicating this is a follow-up to that specific sibling tool. It does not explicitly state exclusions or alternatives, but the workflow context 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?

With no annotations provided, the description carries the full burden and does well: it declares 'Read-only: it changes nothing,' names its data sources (Sonarr's history and download queue), and enumerates the diagnostic categories returned. It stops short of mentioning error behavior or lookup ambiguity handling, but the safety profile and result shape are covered.

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?

A single dense paragraph that is front-loaded with purpose before moving to behavior, safety, scoping, and finally the prerequisite. Every clause contributes, though the diagnostic-cause enumeration makes it longer than strictly needed for selection.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema and no annotations, so the description must supply the return semantics and safety profile itself, and it does: it lists the diagnostic verdicts an agent will receive and confirms the call is side-effect free. An agent has everything needed to call it and interpret results correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline would be 3, but the description adds parameter-dependent behavior the schema does not: season/episode act as optional narrowing filters, and omitting them changes the result to a whole-show grouping. The year parameter's disambiguation role is already in the schema, so no extra credit there.

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+resource (explains why aired episodes have no file) and immediately scopes it as the TV counterpart of diagnose_missing_media, which disambiguates it from that sibling. The enumerated causes it reports (never grabbed, grabbed but not imported, failed download, file removed, stuck in queue, unmonitored) make the tool's output unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing: 'Use check_series_completeness first to see which episodes are missing,' plus the invocation choices ('Give season (and episode) to look at just those; without them it groups every missing episode of the show'). The alternative and prerequisite are both named, leaving nothing 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?

No annotations are provided, so the description carries the burden. It discloses that the tool reads multiple sources (metadata, history, download client queues) and produces a diagnosis, which is useful. However, it doesn't disclose whether the tool performs any mutations (e.g., triggering searches, changing statuses), what the output format is, or whether it can take actions beyond diagnosis. The word 'Traces' suggests read-only, but that is not explicit.

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?

One sentence, front-loaded with the action and resources, no filler. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter diagnostic tool, the description is mostly complete. However, with no annotations and no output schema, an agent doesn't know whether the tool is read-only or may trigger actions, nor what the diagnosis result looks like. Given the tool's complexity (tracing through multiple systems), a bit more context about side effects or output would make it fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the only parameter 'title' is described as 'The title of the media to diagnose.' The description adds the context that the title refers to a movie, which is slightly more specific than the schema's 'media.' This is a minor addition; the schema already carries the meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Traces') and names the exact resources it inspects (Radarr metadata, history, active download client queues) and the goal (pinpoint why a movie is missing). This clearly distinguishes it from siblings like check_movie_status or manage_stalled_downloads.

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 a diagnostic use case: when a movie is missing and the cause is unknown. It doesn't explicitly name alternatives or when-not-to-use, but the context of tracing through multiple sources makes the intended scenario clear. A small gap is not stating when to prefer check_movie_status or manage_stalled_downloads instead.

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?

No annotations are provided, so the description carries the disclosure burden. It usefully discloses that exactly one sequential block item is processed, that the job must be active, and that auto-advance already occurs. But it does not mention side effects on job state, error conditions, reversibility, or what happens when no steps remain.

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 first sentence front-loads the action and purpose; the second adds relevant automatic-advancement context. Appropriately sized for a single-parameter tool.

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?

This is a simple one-parameter tool, but with no annotations and no output schema, the description must do more. It explains what and why, but omits return/outcome details and side-effect behavior, leaving the agent with only partial context for a mutating action.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already fully describes jobId as the unique tracking ID of the active job array, so the baseline is 3. The description adds some contextual language around 'active' and 'block item' but does not materially extend the parameter semantics.

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 precise behavior: processes a single sequential block item from an active background batch queue entry, with a clear rationale (prevent API flooding). This is specific enough to distinguish it from sibling read/manage tools like get_background_jobs and update_job_status, even without naming 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?

Usage is implied rather than explicit: the description suggests manual stepping exists to prevent API flooding, and notes that started jobs also auto-advance one item per minute. However, it does not state when not to use this tool or name an alternative explicitly.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses performance ('first call reads every show's files about 15 seconds'), caching ('cached for 5 minutes'), scope limitations (only Sonarr-downloaded content), and read-only nature. It does not specify permission requirements or pagination/return format details, but covers most behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded: it begins with the core purpose and examples, then explains scope, output summary, performance, and read-only status in a logical flow. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given six optional parameters, no output schema, and no annotations, the description is quite complete: it covers purpose, usage, performance, caching, scope limits, and output summary. It could mention permission requirements or exact return format, but the key context for correct invocation is present.

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 adds usage examples for parameters (bestAtMost 720, bestAtLeast 1080, mixedOnly as upgrade candidates) and folder narrowing ('kids', 'anime', 'sports'), which reinforce but do not significantly exceed the schema documentation.

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 ('Finds TV shows by the video quality Sonarr downloaded') and immediately contextualizes with example questions. It distinguishes itself from siblings like search_plex_library by explicitly noting it only sees Sonarr-downloaded content and routing 4K searches elsewhere.

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 when-to-use examples ('which shows do I only have in 720p?'), explains parameter conditions (bestAtMost 720, bestAtLeast 1080, mixedOnly for upgrade candidates), and names a boundary with search_plex_library for 4K. Alternative and exclusion conditions are clear.

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

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

With no annotations, the description carries the full burden and does well: it discloses sort order, which per-show fields come back, and the important operational constraint that the returned rows are exactly what the user sees, so narrowing must happen server-side via filters. It omits any statement about permissions or read-only nature, but the read semantics are unambiguous from the wording.

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 output shape before the query examples and filter rationale. Dense and mostly waste-free, though the interpretation guidance ('Most gaps are in shows that are deliberately not monitored...') is slightly more editorial than needed for tool selection.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by enumerating the columns returned and the ordering. Combined with the filter-selection guidance and the sibling handoff, an agent has enough to invoke and interpret this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is already 100%, so the baseline is 3, but the description adds genuine intent beyond the schema: 'hideEmpty' is framed as dropping shows with nothing downloaded and 'maxMissing' as finding near-complete shows, and it explains why filtering should be done here rather than on the result set. That is meaning the schema alone does not convey.

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 the TV shows in Sonarr that are missing aired episodes') plus ordering ('most missing first') and the per-row payload (downloaded count, monitoring state, searching state). It names the sibling check_series_completeness for the single-show case, so an agent can separate it from adjacent tools 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?

Gives concrete user-intent triggers ('which of my shows have gaps?', 'which shows are only missing a few episodes?') and explicitly routes the 'what is Sonarr still looking for?' case to the monitored='searching' variant, plus points to check_series_completeness for one show. When-to-use and the alternative path are both spelled out.

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 no annotations, the description carries the burden, but it does not disclose behaviors like whether this is read-only (it implies retrieval, so likely safe), how results are ordered, or if there are any side effects. The description is clear about the action (retrieves) but lacks depth on return format or filtering, though the tool has no parameters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the verb and resource, with no wasted words. It is appropriately sized for a simple tool with no parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters and no output schema, the description is nearly complete. It specifies what it retrieves (jobs) and their states, but could mention whether it returns a list or counts, though without an output schema, the description does enough to guide basic usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, and the description covers the full schema (100% coverage with no properties). The description clarifies the scope (server cluster) and job states, adding meaning beyond the empty schema, which justifies a score above the baseline for no params.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves media processing jobs, specifying the job states (active, pending, completed) and the resource (persistent media processing jobs on the server cluster). It distinguishes from siblings like get_plex_activity or get_library_analytics, though it does not explicitly 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?

The description implies when to use this tool—when you need to check on media processing jobs—but does not explicitly contrast with siblings like update_job_status or execute_next_job_step. No exclusions or alternative conditions are stated, but the context is clear enough for most agents.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose that the tool connects over SSH and returns a Markdown table, which is useful. However, it does not mention potential side effects, authentication requirements, latency implications, or what happens if SSH fails. The description is honest but incomplete on behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the core purpose (real-time CPU load and memory allocation), specifies the scope (every configured cluster host), the method (over SSH), and the output format (Markdown table). Every element earns its place with zero waste.

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 zero-parameter tool with no output schema, the description covers the main purpose and output format. However, it lacks context about failure modes, authentication prerequisites, or how this relates to sibling tools like get_cluster_infrastructure_health. An agent might not know when to prefer this over the infrastructure health 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?

The tool has zero parameters, so the schema provides no parameter semantics to cover. The description compensates by explaining what data is fetched and how it is presented. With no parameters, the baseline is 4, and the description adds meaningful context about the tool's behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches real-time CPU load and memory allocation for every configured cluster host over SSH, and specifies the output format as a Markdown table. This is a specific verb+resource combination that distinguishes it from siblings like get_cluster_infrastructure_health, which likely covers broader health metrics.

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 usage context (real-time hardware monitoring for cluster hosts) but does not explicitly state when to use this tool versus alternatives like get_cluster_infrastructure_health. There is no mention of when not to use it or what conditions would make a sibling tool more appropriate.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose that data is real-time, scoped to all configured Ubuntu hosts, and limited to CPU, RAM, and Docker container counts. It does not explicitly state whether the operation is read-only, describe potential side effects, error conditions, or output shape, so some behavioral detail is still missing.

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?

A single well-structured sentence conveys the action, the data collected, and the scope. Every word contributes meaning, and the most important information is front-loaded. No filler or repetition.

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 zero-parameter, read-style monitoring tool, the description is largely complete: it names the exact metrics and host scope. The main gap is the lack of explicit return-format or usage-context details, but the low complexity of this tool means an agent can reasonably infer how to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so per the rubric the baseline is 4. The description appropriately focuses on what data is collected rather than parameter details, since there is no input schema to clarify.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Collects') and a specific resource ('cluster infrastructure health') with concrete metrics: CPU utilization, RAM usage, and active Docker container counts. It is clear and likely distinguishable from get_cluster_hardware_analytics, though it does not explicitly name the sibling or draw the contrast.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: call this when you need real-time resource metrics across the Ubuntu hosts. However, it provides no explicit guidance about when to prefer this tool over related siblings like get_cluster_hardware_analytics or check_indexer_health, and no exclusions or alternative routing.

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?

No annotations exist, so the description carries the full burden. It indicates a read-only operation via 'Queries' and clarifies the data is historical aggregate statistics, but it does not disclose output structure, pagination, or authorization requirements. It is adequate for a simple query tool but leaves behavioral details unspecified.

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?

A single front-loaded sentence with no filler. Every clause contributes specific metrics or scope, making it efficient and easy to parse.

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 zero-parameter analytics query with no output schema, the description gives the main return categories and scope, which is reasonably complete. It could specify the time window or output format, but the low complexity makes the current description sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters and 100% description coverage, and the tool takes no arguments. Per the 0-parameter baseline, this is a 4; there is no parameter semantics for the description to add.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Queries') and names the resource ('historical statistics') with concrete content examples: most watched movies, total user count, and overall watch metrics. It is clear and distinguishes itself from siblings like get_cluster_hardware_analytics by subject matter, though it does not explicitly contrast with any sibling.

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 usage when historical library analytics are needed, but it provides no explicit when-to-use or when-not-to-use guidance and does not mention alternatives such as get_plex_activity or get_cluster_hardware_analytics. The context is understandable, but the guidance is indirect.

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 no annotations, the description carries the full burden and does well: it discloses ordering (most recently active first), a hard cap (at most 50 items across everything), deduplication (movie in HD and 4K is one entry), and the auth/scope of watch state (the connected Plex account). It stops short of stating the read-only nature or error behavior, which 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?

The core purpose and the routing constraint are front-loaded and information-dense, with no filler. It is somewhat long, and the three quoted user-phrasings ('what haven't I finished?', etc.) restate the same routing point, which is mild 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?

For a 4-parameter, no-output-schema query tool this is complete: the description tells the agent what is returned (how far through each entry), how results are ordered, how they are capped, and when to route elsewhere, so nothing needed 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 description coverage is 100%, so the baseline is 3; the description adds value by mapping filters to user intents ('Use title for which episode is next for <show>?') and clarifying what mediaType 'show' returns, beyond the schema's terse enum 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 specific verb and resource ('answers what should I watch next from Plex's On Deck') and precisely defines the resource — partly played movies plus next/partial episode per followed show. It is clearly distinguishable from search_plex_library and other siblings by naming the alternative explicitly.

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 when-to-use mappings ('Use title for which episode is next for <show>?', mediaType 'show' for next episode in each show) and an explicit when-NOT-to-use with the named alternative (search_plex_library with watched 'inProgress') for complete unfinished lists. Nothing is left 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?

With no annotations, the description must disclose behavioral traits. It states the tool 'fetches' data, implying a read operation, but does not explicitly say it is read-only, mention any side effects, rate limits, authentication requirements, or what happens if Tautulli is unavailable. It also doesn't clarify the output structure or that it returns current sessions only. This leaves significant gaps for an agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the primary action and purpose without any redundant filler. Every phrase adds value, and it is appropriately concise for a simple parameterless tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and no output schema, the description is the sole source of context about the return value and limitations. It says it fetches 'analytics' but does not describe the shape of the response (e.g., list of active sessions, per-user details). For an agent to know what to do with the result, more detail on the return would be helpful. Still, the tool is simple enough that the current description is minimally viable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and the schema is empty. Per the rubric, 0 parameters sets a baseline of 4. The description adds no parameter information (since there are none), and no compensation is needed because the schema already fully covers the parameter surface.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Fetches'), names a clear resource ('real-time playback streaming analytics from Plex via Tautulli'), and states the purpose ('to monitor user context and transcoding strain'). This distinguishes it from siblings like get_library_analytics, which focus on broader analytics, and check_movie_status, which checks individual titles.

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 usage by mentioning the monitoring purpose, but it does not explicitly state when to use this tool over alternatives or provide exclusions. No mention of siblings or conditions like 'use this for live streams, use get_library_analytics for historical data'. The purpose gives some context but falls short of clear guidance.

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 no annotations, the description carries the full burden and does substantial work: default 7-day window capped at 60, only monitored shows returned by default with the excluded count reported, seasons premieres/finales/ downloaded state flagged, and the warning that the returned rows are exactly what the user sees. It omits explicit read-only confirmation, pagination behavior, and auth needs, but adds real context beyond any structured field.

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 and the default-mode answer are front-loaded, and each sentence carries operational content rather than filler. It is dense and somewhat long, but nothing reads as 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?

There is no output schema, yet the description explains the return shape (grouped by day, premieres/finales flagged, already-downloaded marked) and the default filter semantics. An agent has enough to answer correctly without probing further.

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: how 'days' interacts with the no-title mode, what 'title' returns when nothing is scheduled, why 'year' disambiguates same-named shows, and the operational reason the monitored filter must reflect the exact filter used. That is genuine value beyond the 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 specific verb and resource ('What TV episodes are coming, from Sonarr's calendar') and cleanly separates two modes: a calendar view by default and a per-show lookup when a title is given. It does not name or contrast with any sibling such as get_on_deck, search_episodes, or check_series_status, so it falls short of full sibling differentiation.

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 use conditions for both modes ('what's on this week?' without a title; 'when does <show> come back?' with one) and prescribes exactly when to use each monitored filter value. It stops short of pointing to alternative tools for adjacent questions, so context is clear but alternatives are unnamed.

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 no annotations, the description carries the full burden and does so well: it discloses that AUDIT changes nothing, that PURGE_STALLED deletes only the passed hashes and never anything else, deletes downloaded files too, and explicitly notes Radarr/Sonarr are not notified. This is the key behavioral context an agent needs before a destructive operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences front-load the read/write split and the safety constraint; only a minor amount of repetition between the action enum description and the top-level description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description supplies exactly the missing behavioral and safety context: read-vs-write modes, deletion scope, file removal, and absence of *arr notifications. Nothing essential for correct invocation 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 schema already documents action, hashes, and minSpeedKbps in detail. The description reinforces that hashes come from AUDIT and are required for PURGE_STALLED, but adds little beyond the schema on the threshold semantics.

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 precise verbs and resources for both modes: lists stalled/slow downloads (AUDIT) and deletes chosen ones with files (PURGE_STALLED). The dual-mode action is made explicit, and the description distinguishes itself from the many sibling tools focused on media status, search, and infrastructure.

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?

Clearly directs that PURGE_STALLED should only be used with hashes from a user-agreed AUDIT, giving a strong precondition. It does not name alternatives or state when not to use the tool, but the audit-then-purge workflow is well spelled out.

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?

No annotations are provided, so the description carries the full behavioral burden. It gestures at safety ('safely', 'controlled batch', 'enforcing storage policies') but never clarifies whether the tool mutates state or only produces a plan, what happens on execution, or what constraints (permissions, reversibility) apply.

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?

It is a single, front-loaded sentence with the verb leading and no filler. It is efficient, though the terseness contributes to the gaps in the other dimensions.

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 no annotations and no output schema, the description must explain what the tool returns and how a 'plan' relates to execution, and it does not. The core ambiguity of whether this only evaluates/schedules or actually performs the upgrade is left unresolved for a tool whose name centers on planning.

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 all three parameters (mediaType, maxBatchSize, targetResolution) are already documented with enums and bounds in the schema. The description adds only the vague phrase 'specified media classes', providing no syntax or format detail 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?

The description names a specific verb and resource ('schedules a controlled batch upgrade for specified media classes'), which is clearer than a bare name restatement. However it does not distinguish the tool from related siblings like find_series_by_quality or diagnose_missing_media, leaving the agent to infer the planning/evaluation angle.

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?

There is no when-to-use guidance, no mention of prerequisites, and no routing to or away from any sibling tool. The phrase 'for specified media classes' implies scope but gives the agent no condition under which this tool should be chosen over others.

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 no annotations, the description carries the full burden and does well: it discloses the exclusions (talk shows, news, self-appearances, uncredited roles) and that Plex ownership marking is conditional on Plex being configured. It omits failure modes, rate limits, and permissions, which keeps it 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?

Front-loaded with purpose, then filtering, then Plex behavior, then usage guidance. Dense but every sentence is load-bearing; only the mediaType sentence runs slightly long.

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 7-parameter tool with no annotations and no output schema, the description covers intent, filtering, ownership semantics, and the key enum choice. Remaining parameter detail (yearFrom, limit, library, show) is handled by the complete schema, so nothing critical 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 adds genuine meaning by prescribing mediaType values per question phrasing ('movie' for films, 'show' for series, omit for general work) and reinforcing consistency on follow-ups.

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 ('Resolves an actor's name to their official TMDb filmography') plus the scope (movies and TV shows) and filtering behavior. No sibling tool covers actor filmography, so the agent can place it precisely.

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 use case ('answer which of an actor's movies or shows the user is missing') and detailed mediaType selection guidance including follow-up behavior. It does not name a when-not condition or a competing alternative, but its function is fairly unique among siblings.

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

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

Annotations are absent, so the description carries the whole burden. It discloses that it waits for completion, verifies a new backup file, reports file metadata, leaves backups inside app folders, and copies nothing. It does not mention failure modes or authorization requirements, but the core behavior is transparent.

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 action is front-loaded, the waiting behavior is clarified, and the non-copying boundary is stated at the end. Every sentence contributes useful 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 no-input, no-output-schema tool, this description is complete: it states target apps, action, synchonization behavior, verification step, return details, and side-effect boundary. No important invocation information appears to be 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?

The tool has zero parameters, so the schema already covers everything. The description adds useful context by defining the scope ('each configured Servarr app'), and no parameter clarification is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('asks... to create'), the resource ('built-in database backup' for each Servarr app), and the observable outcome (waiting, confirming, reporting file name/size/time). This clearly distinguishes it from siblings like manage_stalled_downloads or get_plex_activity.

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?

There is no explicit alternative or 'use instead' guidance, but the context is unmistakable: use when you need each configured Servarr app to create a database backup and verify it. No sibling tool appears to compete for the same operation, so missing exclusions is a minor gap, not a critical one.

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?

No annotations are present, so the description carries the full burden. It discloses a key behavior: rendering a Markdown multi-choice grid for confirmation, which goes beyond a simple search. However, it does not mention potential side effects, user interaction flow, or whether it blocks pending confirmation. This is adequate but not exhaustive.

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?

A single, efficient sentence that front-loads the primary action ('Searches TMDb') and follows with the output behavior. No wasted words; every phrase contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description is complete enough to understand its purpose and behavior. It explains the search and the confirmation grid. It does not detail what happens after confirmation, but this is a minor gap given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides 100% coverage for the only parameter (query), including a description and example. The tool description adds no further semantics about the parameter beyond restating the search action, so it meets the baseline without extra value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: searching TMDb for movies, and the specific output: a Markdown multi-choice grid for confirmation. It distinguishes this tool from siblings like check_movie_status or get_plex_activity by its search-and-select nature.

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 tool is used when you need to search for a movie and let the user confirm a selection, but it does not explicitly contrast it with alternatives or state when not to use it. No explicit exclusions or comparisons are provided.

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?

No annotations are provided, so the description carries the full behavioral burden, and it does so well by disclosing the non-obvious constraint that Plex cannot search episode plots library-wide and that plot search requires naming the show. It also states what each result contains (show, season/episode numbers, air date, watch state). It omits any pagination/truncation guidance beyond limit, keeping it out of the top tier.

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 purpose and its flagship example queries are front-loaded, and the critical plot-search limitation is flagged with 'IMPORTANT' before param guidance. It is dense and slightly long, but nearly every sentence carries actionable content; no major 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?

For a 9-parameter, zero-required tool with no output schema and no annotations, the description covers the essential gaps: the plot-vs-title search constraint, per-parameter usage, the fallback behavior, and the result shape. It is complete enough to invoke correctly, with only minor gaps around result volume/pagination handling.

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 genuine meaning: it maps airedFrom/airedTo to natural queries ('aired in March 2026'), explains episodeType 'premiere'/'finale' semantics including the show dependency for 'finale', and clarifies season+episode pairing for a specific episode. This is more than the schema restates.

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 ('finds') and resource ('individual TV episodes in the user's Plex library') and immediately disambiguates scope with several example natural-language queries. An agent can distinguish this from siblings like search_plex_library, search_and_select_movies, and get_upcoming_episodes 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?

Gives explicit when-to-use conditions (plot search, title search, date-range membership, premieres/finales) and a clear when-not fallback: 'When the user describes an episode by its plot and no show is known, ask which show or say only titles can be searched.' It stops short of naming specific alternative sibling tools, so it lacks the explicit routing of a 5.

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 no annotations, the description carries the full burden and does well: it discloses the default small limit, the pagination flow (offset, 'more matches remain'), that a show in multiple libraries is deduplicated into one result, that some libraries are excluded unless named, and that watch state maps to the connected Plex account. It omits auth/permission requirements and error behavior, so it stops 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?

Front-loaded with purpose and routing, then details; every part is dense with usable information. It is a single long block rather than a scannable structure and repeats several things already in the schema (network/contentRating/minRating examples, sort enum values, decade hint), which costs it the top score.

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 17-parameter tool with no output schema and no annotations, the description is unusually complete: it explains the shape of returned rows (one row per title, season/episode counts), the pagination contract, library inclusion quirks, and how filters combine. Nothing an agent needs to call it correctly appears to be 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 genuine meaning beyond the schema: how mediaType should be chosen from user phrasing, the semantic split of watched values, that notWatchedInYears counts never-watched titles from their add date, that a decade is expressed as yearFrom/yearTo, and that limit 500 should be passed for 'all/every' requests.

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 ('Searches the movies and TV shows actually in the user's Plex library') and scopes it to owned content. It explicitly distinguishes itself from siblings: check_movie_status for Radarr/download status, Sonarr tools for continuing/ended status, and get_on_deck for recent unfinished items.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Extensive when-to-use routing: mediaType mapping for movie/show/any queries, watched vs inProgress vs watched usage, when to use notWatchedInYears, and a direct instruction to express any narrowing as a filter here rather than post-filtering. It also names alternatives for adjacent queries.

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 no annotations, the description carries the full burden and does well: it explains the actual mechanism (the old key is forgotten, the next check accepts whatever key is presented) and flags the security risk and the need for user confirmation. It stops short of stating reversibility, required privileges, or any response behavior.

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: purpose first, then the narrow applicability condition, then the safety caution. No redundancy and nothing that fails to earn 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?

For a one-parameter tool with full schema coverage and no output schema, the description covers purpose, preconditions, and the risk/confirmation requirement. Minor gaps: no statement of what is returned or whether the operation can be undone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the sole 'host' parameter is documented in-schema with format examples ('192.168.1.10 or host:2222'). The description adds no additional parameter meaning, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource ('Forgets the remembered SSH key') plus the downstream effect ('so the next check trusts the key it presents now'), which resolves the ambiguity in the tool name 'trust_new_host_key'. It does not distinguish itself from siblings, but the sibling list is entirely media/cluster-job tooling, so differentiation is largely moot.

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 scopes use to 'a host the user rebuilt or reinstalled' and adds a when-not signal via the impersonation warning ('an unexpected key change can mean another machine is impersonating it'), plus a required workflow step ('Confirm with the user first'). This is textbook usage guidance for an agent.

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?

No annotations are provided, so the description carries the full burden. It indicates the tool mutates job state, but does not disclose potential side effects (e.g., whether CANCEL is irreversibly destructive, or whether PAUSE/RESUME have any queuing effects). It also doesn't mention any permissions or whether actions are reversible. For a mutation tool, this is a moderate gap, but the action enum provides some clarity for the agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that is front-loaded with the purpose. It avoids fluff and is easy to scan, which is ideal for an agent's prompt context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 2-parameter tool with a clear schema, the description is mostly sufficient. However, given no annotations and no output schema, it could benefit from stating the expected response (e.g., success/failure indicators) or any constraints (e.g., actions only on active/pending jobs). The description is adequate but leaves some behavioral context unclear.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers 100% of parameters with descriptions for jobId and action, including an enum for action. The description adds minimal extra meaning beyond the schema—it just restates that these actions operate on operational state. Baseline 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Updates the operational state of an active or pending background batch job.' It specifies a verb (updates), a resource (operational state of a job), and the scope (active or pending). It distinguishes from siblings like get_background_jobs (which likely reads) but does not explicitly differentiate from other update tools like execute_next_job_step or manage_stalled_downloads, though the specific action set (PAUSE/RESUME/CANCEL) is implied.

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 implicitly indicates usage: to change the state of an active or pending job, not for completed jobs. It does not explicitly state when to use this tool versus alternatives like execute_next_job_step (which might advance a job) or manage_stalled_downloads (which might handle stalled jobs). No explicit exclusions or alternative routing is provided, so guidance is adequate but not explicit.

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