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

There are no annotations, so the description bears the behavioral disclosure burden. It does exposed a key failure mode (no name on TVDBv2) and a workaround, but it does not describe side effects of the add operation, e.g., whether series are immediately searched, what happens on partial failure, or any permissions or storage effects beyond the root_dir parameter.

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

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

The description is two sentences, front-loaded with the primary action, then followed by a specific, actionable caveat. There is no filler or repetition of schema data.

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 11 parameters, no annotations, and no output schema, more context is needed. The caveat is valuable, but the definition omits important context such as the purpose of the various booleans/defaults, how to obtain a valid anime_id, and what a successful add returns or triggers in the Medusa system.

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 0%, so the description must compensate for parameter meaning. It indirectly explains that anime_id is connected to the AniDB-to-TVDB mapping and that TVDB ids are found separately, but it says nothing meaningful about root_dir, status, scene, release groups, or other params. This adds a slim hint but does not compensate for 11 undocumented 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?

The first sentence clearly states the action ('Add an anime series'), the target system (Medusa), and the API endpoint. The note further differentiates it from the sibling add_series tool by explaining when to use the direct-series path instead.

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 an explicit fallback workflow: use search_tvdb, then add_series, when the AniDB-to-TVDB mapping fails. It does not point to other alternatives like bulk_add_anime or resolve_and_add_anime, so it stops short of full 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 are provided, so the description carries the full burden. It discloses that this type of addition uses the standard series endpoint, bypasses anime resolution, and applies global quality defaults when omitted—providing operational context beyond simply saying 'add' by ID. It could go further by describing side effects or success behavior, but it still gives a better-than-simple behavioral view.

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 dense but purposeful: purpose, fallback context, workflow, and the necessary quality-values list. Every sentence earns its place, and the quality enumeration is genuinely needed since the schema lacks enum definitions. It could be marginally streamlined, but nothing is padding or tautology.

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 10 parameters, no output schema, and zero annotations, the description is not complete enough by itself. It provides strong high-level type context and workflow, but it omits the meaning of essential parameters such as anime defaults, scene flags, paused/status semantics, language usage, and root/show directory fields. An agent might infer some of this from names, but for a complicated mutation operation it should not be relied on.

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 has 0% description coverage, so the description must compensate. It does help by enumerating all valid quality values and stating the default handling when qualities are omitted. However, most other parameters—such as root_dir, show_dir, scene, paused, status, language, and the anime boolean—are left unexplained or only inferable from their names. That is a significant gap for a 10-parameter tool.

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 the exact action, resource, and target: 'Add a series to Medusa directly by TVDB ID via POST /api/v2/series.'. It also distinguishes itself from the sibling add_anime by explicitly presenting this as fallback for TVDB-mapping failures. The verb is specific and the resource is clear, so an agent can confidently select intent.

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

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

The description explicitly states when to use this tool instead of add_anime: 'Use this as a fallback when add_anime fails due to AniDB-to-TVDB mapping issues.' It gives a next-step workflow: 'First find the correct TVDB ID with search_tvdb, then add it here.' It even explains why it applies in that case: 'This bypasses anime resolution entirely.' This leaves no ambiguity about the intended route.

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 entire behavioral burden. It does disclose three behaviors: results are 'compact' (format), it checks 'Medusa presence' (side-effect-free lookup), and 'Does not add anime' (readiness confirmation). But the default score thresholding (min_score=88, score_gap=8) is entirely hidden, so an agent cannot foretell that a no-arg call returns only high-scored results.

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 zero scaffolding: the first delivers verb+resource+key parameters and the second is a focused exclusion with no lexical fat. Every token earns 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 7-parameter tool with 0% schema coverage the description is too thin. Although an output_schema exists and sprites the need to describe return values, the unexpected default scoring (min_score=88, score_gap=8) changes the meaning of a no-arg call and is not disclosed anywhere. The 'does not add' line is good but does not close the gap around how many results come back and under what criteria.

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 0%, the intended over-write is required. The description explains title and mal-ud (both named in text), and implies source myanimel; the other five parameters (limit, source, min_score, score_gap and the max fields) remain completely unexplained. With this low coverage and no schema narratives, the description compensation be heavier to compensate, and it doesn't.

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?

Starts with a specific verb and resource – 'Return compact anime details and Medusa presence by title or MAL ID' – so an agent knows at once what it does and how it finds results. The closing ' Does not add anime' explicitly separates it write-related siblings like add_anime, resolve_and_add_anime, and bulk_add_anime. This distinguishes it from siblings without requiring 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 'Does not add animes' sentence is a useful negative scope marker – it tells the agent this is not for creation tasks. However, it never says when to prefer this over sibling lookups (search_tvdb, seasonal_anime, resolve_anime_title, diagnose_release_groups) and names no alternatives explicitly. Usage context 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does usefully state that items with 'filterDecision=skip' are skipped and that 'execute must be true for writes,' implying writes do not happen otherwise. However, it does not disclose behavior for non-skip decisions, partial failures, side effects on disk, or what response the agent should expect. This is minimally transparent but far from complete.

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

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

The description is two sentences with zero filler and front-loads the most critical operational distinction: dry-run vs. actual write, and the execute gate. Every word earns its place in terms of conciseness.

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

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

Given the tool's complexity -- 13 parameters, hidden 'items' schema, nested release-group logic, no annotations -- the description is too thin to fully support an agent invocation. It handles the most important write-or-not gate, but omits context for options like max_items, delays, fallback release groups, and expected outcom. Without adding detailed parameter explanations, the tool is under-specified.

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 0%, so the description must compensate for a large parameter set. It only clarifies 'execute' and the role of 'filterDecision=skip' within items. Most members params -- such as 'root_dir', 'max_items', 'pause_seconds', 'allowed_decisions', and release-group settings -- receive no description. Given 13 params and an opaque 'items' array, this is insufficient.

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 clear verb and resource: 'dry-run or add multiple anime items.' This distinguishes the tool from the singular add_anime sibling and clarifies that it is a batch operation. The dry-run/write distinction further sharpens the tool's purpose.

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

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

The description clearly states when to use this tool: for adding multiple anime items, optionally in dry-run mode. It also sets the key condition 'execute must be true for writes,' giving explicit operational advice. It does not explicitly name alternatives, but the plural intent and sibling 'add_anime' make the usage context reasonably 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?

No annotations are provided, so the description carries the full behavioral burden. It clearly discloses that creating the alias changes how Medusa handles future searches, and adds the important scope limitation that only local, user-managed exceptions can be created. This goes beyond a bare 'create' statement and gives the agent a solid mental model of effects.

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

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

The description is compact: a short lead sentence stating the operation and a two-sentence expansion explaining purpose and scope. It is front-loaded with the most important information and contains no irrelevant enfluff or abstruse.

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 creation tool with an output schema and 100% parameter coverage, the rest of description addresses what the operation does, why it is needed, and its local scope. The only missing detail is duplication behavior (what happens if the same alias again), but that's not essential for calling the tool successfully.

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 appropriate. The description does not define the individual parameters but does contextualize 'name' as an 'alternative release title', which is a minor clarification over the schema text (which says 'The alternative title to add as a scene exception'). No additional parameter-level information is provided.

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 opens with the specific verb-resource pair 'Create a local scene exception (alias) for a series' and then explains the operational purpose: enabling Medusa to recognize alternative release titles. It is clearly distinct from siblings like delete_alias and get_aliases, and the local-scope caveat sharpens the definition.

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 the tool: when a series needs a locally-managed alternative title for search matching. However, it does not explicitly contrast with sibling tools such as get_aliases or delete_alias, and the 'Only local' note hints at alternatives without naming 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?

There are no annotations, so the description must carry the behavioral disclosure burden. It communicates the destructive 'delete' action but does not mention whether deletion is permanent, whether related scene data is affected, or whether any permission/state requirements exist. This is thin for a mutation tool.

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 sentence, no filler, and immediately actionable. It uses the remaining tokens for the only relevant bit of context: that an alias is a scene exception.

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

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

The tool is simple, has one parameter, and an output schema exists, so no return-value documentation is needed. However, with no annotations and no behavioral context, the description still leaves a destructive action without side-effect or irreversibility caveats. Acceptable but minimal.

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 describes the only parameter (alias_id) at 100% coverage, so the description does not need to add much. It also does not elaborate on how alias_id should be obtained or what constitutes a valid ID; baseline for high schema coverage is appropriate.

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

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

The description states a concrete verb ('Delete') and a specific resource ('alias'), and clarifies that an alias is a scene exception. That makes its purpose unambiguous and distinguishes it from siblings like create_alias and get_aliases without needing more detail.

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 guidance about when to prefer this tool over alternatives or when not to use it. The delete semantics imply the intended use, but the description does not offer any comparison or exclusions beyond the operation itself.

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?

Since there are no annotations, the description carries the behavioral burden. It discloses useful traits: provider cache is checked first, an empty cache triggers manual search and retries, and the result is a structured diagnosis with a recommendation. But it stops short of explicitly confirming whether this tool is fully read-only or whether triggering a search has user-visible side effects like rate limiting or network costs.

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 short, front-loaded with purpose, and includes the algorithmic flow and return type in just three sentences. Every sentence serves a purpose and there is no redundant filler or schema 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 five-parameter diagnostic tool with 100% schema coverage and an output schema, the description gives enough context onbthe flow and result. It still lacks explicit guidance on side effects and failure behavior when retries expire, which would make the context fuller.

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

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

Input schema coverage is 100%, so the baseline is 3. The description does not add parameter-specific semantics beyond the summaries; e.g., it doesn't mention season, episode, or retry controls. The exisfing schema descriptions are sufficient, so no strong penalty is warranted.

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 and resource: 'diagnose release group issues for a series' and explains that it compares config vs available releases. This clearly separates it from siblings like update_release_groups and force_search, which imply modification and search behavior respectively.

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 usage context is implied through the verb 'diagnose' and the comparison of config vs releases, but the description never states when to prefer this over alternatives such as force_search or update_release_groups. It provides no when-not-to-use conditions or explicit 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?

With no annotations provided, the description carries the full behavioral disclosure burden. It reveals that the tool queues a manual search, queries providers, snatches matching releases, and reqs†ŝê³½† waiting for a status change. It could mention whether the operation is asynchronous or what a successful response looks like, but it captures the main side effect.

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, each meaningful: the command, the behavior, and the usage context. There is no filler, and the most important action is stated up front.

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 low-complexity tool with only two parameters and no output schema, the description covers command, provider interaction, side effects, and when to invoke it. It does not elaborate on possible failures or return behavior, which 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?

Schema coverage is 100%, so both parameters already have clear descriptions and examples in the input schema. The description adds no parameter-level meaning beyond what the schema provides, making this a baseline 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?

The description clearly states a specific verb and resource: it forces a manual search for specific episodes and queues an operation that actively queries providers and snatches releases. This strongly distinguishes it from sibling tools like search_tvdb or set_episode_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?

The description gives a clear when-to-use instruction: after setting episode status to "wanted" when you want immediate search and download. It does not explicitly name alternatives or list conditions that should prevent its use, though the guidance is concrete enough 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?

There are no annotations, so the description itself must declare behavioral intent. It clearly states the operation is read-only ('List', 'reads them') and does not claim any mutation or side effect. It doesn't go into error cases or auth, but for a simple list operation with an output schema present, the essential behavior is 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?

The description is three short, focused sentences. It front-loads the core purpose, gives the domain definition in the middle, and closes with the relevant sibling pointer. Every sentence adds value and none repeats schema 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?

Given the simple parameter set (one required slug, one optional filter), a complete output schema, and the explicit read-only and create-alias routing, nothing necessary for an agent to select and invoke this tool 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?

The input schema already describes both parameters with 100% coverage: series is required and season is an optional filter. The description adds context about what scene exceptions are but does not add new details about the series_slug or season formats' that aren't in 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?

The description names a specific verb ('List'), a specific resource ('scene exceptions (aliases)'), and a scope ('for a series'), so the agent knows exactly what the tool returns. It also defines the term and separates reading from writing by naming create_alias.

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

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

The description explicitly says 'This tool reads them' and then directs the agent to use create_alias when adding new ones. This provides a clear decision rule over when to use is tool v. a mutation sibling.

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 fills the burden reasonably. It discloses that the action moves all downloaded episode files, preserves original filenames, enables season folders, and also moves associated subtitled/other files. It does not add notes about irreversibility or downstream effects, but the core behavior is 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?

The description is front-loaded with a one-line command, then branches into a short 'Maybe this' bullets list and the exact API call. It is compact and effectively structured, though the second paragraph partly re-explains the first by saying it enables season folders and moves all downloaded files.

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-parametically tool with an output schema and no annotations, the description gives the operation, the endpointBody, scope, and typical usage conditions. The only meaningful gap is the under-specified series_slug value, but an agent can infer enough to invoke it correctly. This is complete enough to act on autonomously.

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 one required string, series_slug, with a 0% description coverage, so the description must carry the meaning. The endpoint line 'series/{slug}' and the repeated use of 'series' imply that series_slug is the series identifier, but the description never explicitly states the expected format or how the slug is obtained. Partial but not full compensation.

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 starts with a precise verb-plus-resource statement: 'Move episodes into Season XX/ subdirectories without renaming files.' It further specifies that original filenames are prserved and associated files like subitles are moved too, so an agent can clearly picture exactly what the operation does and how it differs from a rename/organizer.

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 includes a explicit 'Use this when' list with three concrete signals: flattened multi-season directories, Plex missing episodes due to multi-season-in-one-folder, and a late second season. It does not state when not to use it or name an alternative sibling, so it stops short of full 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 burden. It discloses that files are moved, credentials are reused from MEDUSA_URL/MEDUSA_API_KEY, and directory is interpreted by Medusa core rather than the Hermes container. This is meaningful trading beyond the input 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?

The description is compact yet complete: purpose, action, use case, credential reuse, and the critical path caveat. The important warning is explicitly flagged with 'IMPORTANT', 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?

All four parameters are documented in schema, return shape is covered by output schema, and the free-text description supplies the missing behavioral and practical context: when to use, the container-path requirement, and the file-moving consequence. 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 baseline is 3. The description adds real value for the key parameter by clarifying that directory must be the container-side path, and it connects the use case to the failed/auto-post-process flow, which maps to process_type.

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

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

Description uses a specific verb-resource pair and explains the actual operation: scan a directory and move matched episodes into show folders. It clearly distinguishes this from the sibling tools, none of which focus on Medusa post-processing.

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 an explicit scenario: clear files stranded in staging after a failed auto-post-process, with a concrete example. It does not enumerate when-not-to-use or name a sibling alternative, so it falls short 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state whether the tool is read-only, whether it modifies persisted state, how it handles large candidate sets, or what 'compacting' actually changes. 'Compact into a packet' hints at transformation but leaves side effects ambiguous.

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 with no filler and the core purpose is front-loaded. However, it is only minimal under-specification rather than genuinely rich concise; it still earns credit for not wasting words.

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

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

Given no annotations, no parameter descriptions, and the existence of several sibling tools, this description is too brief for an agent to understand the contract fully. The output schema may clarify return values, but it does not compensate for missing guidance about inputs, limits, usage flow, or side effects.

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 0%, so the description must compensate, but it does not explain 'items' shape or the meaning of 'max_items'. The phrase 'seasonal candidates' weakly maps to 'items,' but 'max_items' is unmentioned and no parameter semantics are clarified. With two undocumented parameters, this is a significant 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?

The description uses a specific verb ('Compact') and a concrete resource ('seasonal candidates') with a clear output destination ('AI review packet'). It distinguishes the tool's job from sibling tools like 'seasonal_candidates' or 'organize_season_folders', though it does not explicitly name 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 gives no guidance on when to use this tool versus alternatives, and it does not state any preconditions or follow-up actions. The only implicit hint is that it operates on 'seasonal candidates,' but that is not enough to route an agent confidently.

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 of behavioral disclosure. It does disclose the critical dry-run behavior and the execute flag that switches to a mutating add. However, it does not explain side effects of adding, how resolution works, or whether filesystem/mal changes occur beyond the parameter names.

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 only one sentence and is front-loaded with the essential action and the dry-run caveat. No filler is present, but it is too terse for a tool with this many parameters and no schema documentation.

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 incomplete for a 14-parameter tool with no schema descriptions. It omits the resolution process, criteria such as min_score and score_gap, release group fallback behavior, and filesystem implications. The presence of an output schema does not compensate for the missing input semantics.

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 0%, and the description adds almost no explanation of the 14 parameters. It only gives meaning to execute ('dry-run unless execute is true'); the rest of the parameters—mal_id, limit, score_gap, root_dir, release groups—remain unexplained.

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

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

The description explicitly states the action: resolve and optionally add one anime, with a dry-run default unless execute is true. This is a specific verb plus resource ('anime') and helps distinguish it from broad tools like bulk_add_anime, though it does not explicitly differentiate from add_anime or resolve_anime_title.

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 dry-run-first workflow: run without execute to preview, then set execute=true to actually add. It gives the central usage condition, but does not provide guidance on when to choose this tool over the sibling add_anime, resolve_anime_title, or bulk_add_anime.

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?

Because no annotations are present, the description must carry the behavioral burden. It at least discloses the core decision behavior and the fact that it resolves to MAL candidates rather than mutating data. However, it does not mention whether it performs an external network call, requires credentials, or is read-only, leaving gaps for a no-annotation tool.

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 with no filler words and the primary purpose is front-loaded. It is compact and readable, though its brevity leaves room for omission of important contextual detail, which is reflected elsewhere.

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 six parameters and no annotations, the description is insufficient on its own for an agent to confidently adapt calls. The output schema exists, but the meaning of threshold and filtering parameters, how the decision is derived, and how this differs from resolve_and_add_anime are missing. It covers the broad job but not enough of the operational details.

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 0%, so the description must compensate by explaining parameters, but it does not. The word 'title' maps to the title parameter, but limit, fields, source, min_score, and score_gap are all unexplained, leaving most of the six parameters ambiguous.

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 ('Resolve'), a specific resource ('anime title'), a target ('MAL candidates'), and a concrete decision output ('match/ambiguous/no_match'). It clearly differs from siblings like resolve_and_add_anime, which implies adding after resolution, and search_tvdb, which targets a different database.

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?

No explicit when-to-use or when-not-to-use guidance is provided. The description does not compare itself to resolve_and_add_anime or any other sibling, so an agent cannot tell from the description alone whether to call this tool or a related one for a given workflow.

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 to cover behavior, the description adds real value by explaining exactly what status information is returned: whether each scheduler thread is alive, enabled, and active. This is sufficient for a simple read-only diagnostic tool, even though it does not mention authentication or 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 three short sentences with no waste. It front-loads the core purpose, expands on the exact information returned, and then states the practical 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?

For a no-parameter read-only status tool with an output schema present, the description is complete. It gives the agent enough to select the tool, understand what to expect, and judge when the result has diagnostic value.

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 already fully documents that fact, so there is no parameter meaning for the description to clarify. Baseline 4 is appropriate for a zero-parameter tool.

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 ('Return') and resource ('Medusa scheduler and queue status'), and elaborates on what is shown: thread liveness, enabled state, and active state. It is clear and distinct from sibling tools like postprocess or force_search, though it doesn't explicitly name a sibling alternative.

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 a clear practical use case: 'Useful for diagnosing stuck queues.' This implies when to reach for this tool, though it does not explicitly state when not to use it or name an 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?

Without annotations to lean on, the description carries the burden. It clearly states the operation is a search/read and describes the return value as TVDB IDs. Does not mention rate limits or endpoints, but such details are not necessary for an agent to correctly invoke this tool.

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, front-loaded with the operation, then the exact trigger scenario, and the follow-up action. No filler and every sentence earns its place.

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

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

The description copes for the basic search flow and the follow-along with add_series, and an output schema is present. Gaps from a partially undocumented language parameter and no explicit failure/empty-result behavior, so it is not fully complete without schema inspection.

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 description adds meaning for 'query' by saying 'by name', but the optional 'language' parameter is entirely undocumented and schema description coverage is 0%. The description must compensate at this coverage level but it only does so for one of two 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 (Search) + resource (TVDB) + input (show name) + output (matching TVDB IDs). Clearly differentiates from the sibling add_series and add_anime tools by focusing on lookup only, not adding.

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

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

Explicitly says when to use it: when an anime add fails due to AniDB-to-TVDB mapping issues. It also gives the next step: use add_series with the found ID. No explicit when-not or alternative search tools are mentioned, but the context is clear.

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

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

With no annotations, the description carries the behavioral burden. It does disclose that the tool is paginated, can return only selected fields, and treats season, source, and source_sort case-insensitively. It does not disclose output shape, default behavior, or what affects the sort order.

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

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

Two concise sentences with no filler. The core operation is front-loaded, and the second sentence provides a focused behavioral detail. Every sentence earns its place despite the limited scope.

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 output schema and no annotations, the description is too thin. It lacks guidance on parameter meaning/value formats and default behavior. An agent would likely need additional inspection before it can call this tool correctly in a nontrivial case.

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 0%, so the description needed to compensate for seven parameters. It only partially covers 'fields' and mentions case-insensitivity for three parameters, but it leaves semantics of 'year', 'season', 'source', 'source_sort', 'page', and 'limit' mostly to invention. This is not enough for a tool with zero schema 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?

States a clear verb ('Query') and a specific resource ('paginated seasonal anime page from Medusa'), and mentions pagination and optional field selection. It does not explicitly contrast itself with sibling tools such as seasonal_candidates, so an agent still has to infer some distinction from the resource name.

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?

No guidance is given about when to use this tool versus alternatives like seasonal_candidates, anime_info, or force_search. There are no exclusions or conditions, and the reader must implicitly infer the correct context from the word 'seasonal anime'.

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 carry the full safety and behavioral burden. 'Fetch' suggests a read operation, but 'apply residual preference heuristics' is opaque and could imply state changes, yet no side effects, modifications, or side-effect-free claims are 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?

The description is a single concise sentence that leads with the primary verb and resource. It is not bloated, though the word 'residual' is vague jargon that slightly undermines the clarity of the concise structure.

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 complex tool with 9 unannotated parameters and no guidance, a one-sentence description is incomplete. The meaning of server-filtering, the heuristics, and how they map to the listed parameters is unknown; an agent cannot confidently invoke the tool 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 0% while there are 9 parameters, so the description must compensate but does not. Terms like 'seasonal' and 'preference heuristics' loosely imply year/season and source_sort/min_num_list_users, but no parameter is explicitly mapped or explained.

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?

Uses the specific verb 'Fetch' with a clear resource and scope, indicating that this tool returns a 'candidates' list for a season. However, the phrase 'residual preference heuristics' is vague, and it doesn't explicitly distinguish itself from the sibling 'seasonal_anime'.

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?

No guidance is given on when to use this tool versus alternatives like seasonal_anime or prepare_seasonal_review. The description implies a filtered candidate pipeline, but does not state which scenario should call this tool.

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

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

With no annotations provided, the description carries the burden of explaining side effects. It discloses that the tool mutates episode statuses, triggers Medusa to search episodes, and can converts UNAIRED episodes to WANTED. It does not discuss permissions or reversibility, but the core behavioral side effects are 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?

The principle operation is stated first, followed by problem scenario and the comparison to the alternative endpoint. Each sentence serves a purpose, and the description is compact enough for quickly consuming.

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 three-param mutation tool with an output schema, the description provides the operation, the exact endpoint, when to use it, and the behavioral mechanism. The schema covers the remaining param details, so agents have enough information to select and invoke the tool 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 schema already documents `status`, `episodes`, and `series_slug`. The description adds use-case context around setting episodes to `wanted`, but does not add parameter-level detail beyond what the schema and default `wanted value already provide. Baseline 3 is appropriate.

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

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

The description states a specific verb, resource, and endpoint: 'Set episode statuses for a series via PATCH /api/v2/episodes/{series_slug}. It is not a tautology and conveys the operation clearly. It does not explicitly distinguish itself from the sibling force_search, though the use case and endpoint make the role reasonably unambiguous.

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

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

The description provides a concrete trigger ('Use when TVDB metadata is out of sync... and Medusa is not downloading episodes that should be available'), giving the agent a strong signal for when to select this tool. It also references an alternative ('internal bulk-update endpoint') and explains why this tool is preferable for changing UNAIRED to 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?

No annotations are present, so the description carries the behavioral disclosure burden. It usefully reveals that the operation is a PATCH, meaning only provided fields change and omitted fields remain untouched. This is important safety-relevant behavior 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 compact and well-ordered: purpose first, then the HTTP operation, then the behavioral contract. Every sentence serves a distinct purpose with no redundancy.

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

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

For a flat 5-parameter update tool with an output schema, this is nearly complete. The main missing nuance is whether sending a nullable field explicitly as null clears it or is ignored, since 'only provided fields are changed' suggests null might be significant.

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 parameters already have useful descriptions. The description does not add further parameter-level nuance, such as how null values are interpreted, so the schema is doing 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 opens with a specific verb and resource: 'Update release group configuration for a series'. It also names the exact HTTP endpoint, making it easy to distinguish this from siblings like update_series_quality or diagnose_release_groups.

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 first sentence clearly states when to use the tool: when release group configuration for a series needs to be updated. It gives context but does not explicitly mention alternatives, edge cases, or when not to use it.

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?

There are no annotations, so the description itself must disclose behavior. It does this well by explaining that only provided fields are changed and omitted fields remain untouched. The HTTP PATCH method and accepted quality values add useful behavioral context beyond a simple update statement.

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, front-loaded with the core purpose, and uses the space efficiently. The quality value list is long but necessary because those values are not otherwise represented as enums in the schema.

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 definition provides enough context for an agent to call the tool: endpoint, required and optional parameters, valid values, and partial update behavior. It does not detail auth requirements or return values, but the tool has no output schema and this is likely a simple mutation, so these are not critical 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?

The schema already covers all parameter descriptions, but this is a case where the description adds real value by listing the valid quality strings, since there are no enums in the schema. It also clarifies that provided fields are merged with existing values rather than replacing the whole config.

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

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

The description clearly states it updates allowed and/or preferred qualities for an existing series, identifies the specific PATCH endpoint, and this distinguishes it from sibling tools like update_release_groups. The verb and resource are specific and unambiguous.

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

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

The description clearly frames the usage context: updating quality settings for an existing series via PATCH. It also clarifies partial update behavior, which is essential for correct use. It does not explicitly name alternatives, but the scope is clear enough that an agent can select this tool without much inference.

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