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

Annotations declare idempotency and non-destructiveness, but the description adds the crucial behavioral detail the annotations only imply: the archive keeps one entry per film and returns the existing entry rather than creating a duplicate. It also discloses what enrichment fetches from TMDB, which no structured field conveys.

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 purpose, enrichment, and the dedup warning before the Args block, so the most important agent-facing facts come first. Slightly redundant in repeating lookup_tmdb twice, but every sentence is functional and earns its place.

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

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

An output schema exists so return values needn't be explained, and the description still notes that an existing entry comes back instead. For a 10-param mutation tool with 0% schema coverage, the definition leaves nothing an agent needs 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 0%, so the description carries the full burden and does so thoroughly for all 10 params: rating scale rules (1-10, 0 unrated, never convert from IMDb, double out of 5), date format with timezone and source, the leave-content-empty rule, status values, and the tmdb_id-vs-imdb_url fallback group.

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 ('Add a film to the archive') plus the enrichment source (TMDB), which immediately distinguishes it from siblings like update_film and write_review. An agent can tell what this creates 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?

Explicitly routes the agent: use lookup_tmdb to find the id, prefer tmdb_id over imdb_url, and use update_film or write_review instead when the film already exists. It even flags that allow_duplicate is 'almost never right', giving clear when-not 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety and repeat-call profile is covered. The description adds one genuinely useful behavioral fact beyond that: drafts are included in results. It says nothing about auth, missing-film behavior (null vs error), or rate limits.

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, zero waste: capability first, usage rationale second, parameter format third. The Args block restates nothing that isn't useful, and the most decision-relevant information (what it is, when to use it) is front-loaded.

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

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

An output schema exists, so return-value documentation is not required, and the single required parameter plus its format is explained. What remains thin is the identity boundary against get_film and search_films, which the agent must infer from the 'before adding it' framing.

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 carry all parameter meaning, and it does: it specifies the accepted format as an IMDb id ('tt0816692') or a full IMDb URL. That is the key ambiguity an agent would otherwise guess wrong on, though it does not say whether the two forms are normalized identically or if the URL may include query strings.

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 ('Find a film by its IMDb id') plus a scope qualifier ('including drafts') that no sibling exposes. It implicitly separates itself from title-based lookup like search_films by arguing the ID route is more reliable, but no sibling is named outright, so sibling differentiation is contextual rather than explicit.

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

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

Gives a clear when-to-use context: the pre-add deduplication check before create_film, with the rationale (titles repeat across remakes and translations). There is no explicit when-not guidance (e.g., use search_films or list_films when you only have a title), so it stops short of full routing 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?

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful context beyond those annotations by clarifying that the tool reports the connected site and write capability, which tells the agent what kind of answer to expect.

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 entire description is one efficient sentence with a front-loaded verb and 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 zero-parameter, read-only diagnostic tool with rich annotations and an output schema, the description is fully sufficient. An agent can call this tool correctly without additional guidance.

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 there is nothing for the description to clarify. Baseline for zero-parameter tools is 4, and the description correctly avoids inventing unnecessary parameter guidance.

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, 'Report', and names the exact resource: the target site and whether writing is possible. It is unambiguous and easily distinguished from sibling tools, none of which are status/diagnostic checks.

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

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

The description provides clear context for when this tool is relevant: when an agent needs to know where the connection points and whether writes are allowed. It does not explicitly name alternatives, but no sibling tool competes with this status-check function.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds useful behavioral context by promising a complete record including review, rating, and credits, which helps the agent know it will receive full detail rather than a summary.

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, front-loaded with the core purpose, and has a clearly separated argument line. Every sentence contributes meaningful guidance without repetition or filler.

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

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

With a single parameter, clear provenance for the id, and an output schema present, the description covers everything needed to correctly invoke this tool. No return-value explanation is required beyond the promise of full film 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?

The schema only defines id as an integer with no description, so the description carries the full burden. It explains that the id is a film id and, crucially, tells the agent where to obtain it (from search_films or list_films), which is essential context the schema lacks.

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 'one film in full' and enumerates the contents: review, rating, credits, and every field. This distinguishes it from sibling search/list tools and makes the resource and action immediately clear.

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 argument documentation explicitly tells the agent that the film id comes from search_films or list_films, which implies the intended workflow: search or list first, then fetch full details by id. It does not explicitly state when not to use this tool, but the sequencing guidance is strong.

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

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true), so the description's burden is lower. It adds useful context by enumerating which aggregate figures are returned, but doesn't describe behavior beyond that. No contradiction with annotations.

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

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

Two tight sentences with zero filler. The first sentence front-loads purpose and scope, the second adds usage guidance. Every word earns its place.

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

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

For a zero-parameter aggregate tool, the description is complete. The output schema covers return values, annotations cover safety and idempotency, and the description covers scope and usage. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool has zero parameters, which sets a baseline of 4. The description adds value beyond the empty schema by explaining what the returned figures actually measure (totals, average rating, rating spread, films per year), giving the agent expectations about the output shape.

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 ('Get archive-wide figures') and enumerates the concrete outputs (totals, average rating, rating spread, films per year). The 'archive-wide' scope clearly distinguishes it from per-film siblings like get_film, list_films, and search_films.

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 second sentence gives explicit when-to-use guidance: 'Use this for questions about the collection rather than one film.' This is a clear usage directive with an implied exclusion of per-film tools, though it doesn't name the alternative sibling 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered by structured data. The description adds no behavioral context beyond that - it says nothing about pagination behavior, filter combination rules, or default handling, and an output schema exists to cover returns.

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 one-line summary is front-loaded and the arg list is terse with no filler. It is long only because 13 parameters genuinely need documenting, though indentation of the Args block is slightly wasteful.

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

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

With an output schema present, return values need not be explained, and the 13 parameters are fully described. The remaining gap is the absence of routing guidance against the four sibling find/search/get tools, which matters given this is a heavily filtered listing endpoint.

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 carries the full burden and does so thoroughly: it documents every one of the 13 parameters, including enum-like values for orderby/order/status, the 1-10 rating bounds, the Finnish-language genre convention, and the per_page cap of 100. This is exactly the compensation needed for an undocumented schema.

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

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

States a specific verb and resource ('List films') plus the scope modifier 'filtered and ordered', which is immediately actionable. It does not, however, differentiate itself from the sibling 'search_films' or 'find_film', leaving the agent to guess which listing/finding tool to pick.

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 at all: nothing explains when to call list_films versus search_films, find_film, or get_film, nor whether filters combine with AND semantics. The agent must infer usage entirely from the parameter list.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds genuine value by disclosing that an application password is required and explaining the queue's origin, which goes beyond the structured annotations.

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

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

Three short, focused sentences. The purpose is front-loaded, the queue origin explains behavior, and the password requirement is essential operational information. No wasted words.

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

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

For a zero-parameter, read-only list tool with an output schema, the description is complete. It covers what is listed, why it exists, and the authentication requirement. 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?

The tool has zero parameters and schema coverage is 100%, so the description has no parameter semantics to add. Per the baseline for zero-parameter tools, a 4 is appropriate.

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

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

The description uses a specific verb ('List') and a specific resource ('draft films waiting for a review'), clearly distinguishing this queue-viewing tool from siblings like list_films or search_films. The additional context about the Trakt importer further anchors what this tool returns.

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

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

The description provides clear context about when this tool is relevant: it lists films queued by the Trakt importer after Rolle watches something. It does not explicitly name alternatives or exclusions, but the context strongly implies when to use it, so it earns a 4 rather than 3.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds the constraint that terms are 'used in the archive' and that search narrows to names 'containing this,' but it does not disclose sorting, pagination, or exact matching 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?

The description is compact and well-structured: one opening sentence establishes the tool's purpose, followed by a terse, useful Args list. Every line adds meaning 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?

For a simple list tool with a strong annotations profile and an output schema present, the description covers the essential behavior and all parameter semantics. No critical information needed to invoke the 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?

Schema description coverage is 0%, so the description carries full responsibility, and it succeeds: it enumerates the valid taxonomy values, explains search as a substring filter, and defines limit as the number of terms returned. This is exactly the meaning an agent needs beyond the bare schema.

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

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

The description begins with a specific verb and resource: 'List genres, directors, writers or actors used in the archive.' It clearly distinguishes this tool from siblings like list_films and search_films by stating the taxonomy categories it returns.

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

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

The description provides clear context: use this tool to retrieve taxonomy terms from the archive, with optional search narrowing and limit controls. It does not explicitly name alternatives or exclusion conditions, but the intended use is obvious from the stated purpose.

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

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

Annotations already declare readOnly/idempotent/non-destructive behavior, and the description adds valuable operational context: the proxy through the site, the fact that the TMDB key is held server-side, and the application password requirement. No contradictions with annotations.

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

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

Three short sentences plus an Args line carry the entire definition. Purpose is front-loaded, operational notes follow, and no words are 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?

For a one-parameter lookup with an output schema and rich annotations, the description covers the essential invocation context: what to pass, why, and what auth is needed. It does not mention behavior on no results or multiple matches, but those are minor given the output schema.

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

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

Schema description coverage is 0%, so the description must compensate. It does: it explains 'query' means the film title to search for, which is more specific than the schema's bare 'Query' field. For a single parameter this is sufficient.

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 ('Search'), resource ('TMDB'), and targeted outcome ('to get the tmdb_id that create_film enriches from'). It is clear about what the tool does, though it does not explicitly differentiate from the sibling search_films.

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 by tying the lookup to create_film and noting that it goes through the site and needs an application password. It stops short of naming alternative tools or exclusion conditions, but the intended use is easy to infer.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value beyond that by clarifying partial-title matching ('Part of the film's title') and the tool's role as a provider of ids to get_film. No contradiction with annotations 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?

The description is compact and well-structured: a one-line purpose, a usage pointer, a result note, and an Args block. Every sentence earns its place, and no information is buried or repeated from 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 tool is simple, has an output schema, and its annotations cover safety. The description adds the missing context: when to start, what the title parameter accepts, and how the result connects to get_film. Nothing essential is missing 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?

With 0% schema description coverage, the description fully compensates by explaining both parameters: title is a partial title match, and limit controls how many matches to return. This adds real semantic meaning beyond the raw schema types and defaults.

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

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

The description states a specific verb and resource ('Find films by title') and immediately clarifies the intended entry point ('Start here when you know the name'). It differentiates itself from siblings like list_films and get_film by framing the tool as the id-lookup step before get_film.

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

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

It explicitly tells the agent when to use this tool ('Start here when you know the name') and what to do with the result ('Returns the id needed by get_film'). It does not explicitly state when not to use it or name alternatives like list_films, so it stops 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?

Annotations cover readOnly=false, idempotent=true, destructive=false, openWorld=true. Description adds the clearing semantic (rating 0 clears) and the range constraint (1-10), which is meaningful behavioral context beyond the annotations. However it doesn't explain what happens to prior ratings or return behavior, though output schema covers returns.

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 purpose statement followed by parameter bullets. The 'See create_film for the scale' is a useful routing hint. Args-style formatting is acceptable but slightly verbose for two params.

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 an output schema exists, return values needn't be explained. Both params are described, clearing behavior noted, idempotency in annotations. Missing only explicit sibling routing and scale direction.

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 0%, so the description must carry parameter meaning. It documents both params: id as Film id, rating as a 1-10 whole number with 0 semantics. It even cross-references create_film for scale details. Slight gap: doesn't explain whether 1 or 10 is highest.

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: setting a rating for a film. The domain term 'Rolle's own rating' signals user-level rating semantics. Sibling differentiation is weak — it doesn't distinguish from write_review or update_film 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?

No explicit when-to-use versus alternatives like update_film or write_review. The reference to create_film for scale is a helpful cross-link but doesn't explain when to choose this tool.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false. The description adds meaningful behavioral context beyond those flags by stating the film can be restored from WordPress admin, clarifying that this is not a permanent deletion.

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, front-loaded with the action, and contains no filler. The one-line argument note is directly useful and does not repeat the entire 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?

For a one-parameter mutation with an output schema and rich annotations, the description covers the core operation and reversibility. It does not address edge cases like already-trashed films or nonexistent IDs, but the output schema likely covers the response behavior.

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

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

Schema coverage is 0%, so the description must compensate. It provides only 'id: Film id,' which is minimal but does clarify that the parameter refers to the film being trashed. For a single integer parameter, this is adequate though thin.

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 ('Move') and a specific resource ('a film to the trash'), making the operation unambiguous. It is clearly distinct from siblings like create_film, get_film, set_rating, and write_review.

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 conveys when to use the tool: when a film should be moved to the trash. It also adds context that the action is reversible via WordPress admin. It does not explicitly name an alternative, but no sibling tool obviously competes for this operation.

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

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

Annotations declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), and the description adds behavior they cannot convey: list fields are wholesale replacements ('Replace the genres/directors/writers/cast'), tmdb_id overwrites every metadata field plus poster and credits while preserving rating and review text, and publishing a draft keeps its date. This is exactly the overwrite information an agent needs before mutating.

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 opening sentence is front-loaded and the Args block is the minimum needed given zero schema coverage. A few entries are terse ('Film id.', 'New title.') and the repeated 'See create_film' cross-references add slight redundancy, but nothing wasteful.

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

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

For a 12-parameter mutation tool with an output schema present (so return values need not be explained), the description covers partial-update semantics, every parameter, enum values, and the side effects of tmdb_id and status changes. Nothing required to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: all 12 parameters are documented, including the status enum values (publish or draft), the rating domain (whole number 1-10, 0 for not rated), imdb_url format (full URL), and the replace-vs-refresh distinction between list fields and tmdb_id.

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 ('Change anything about an existing film') and immediately scopes it with patch semantics ('Only the fields given change'). It also references create_film as the counterpart tool for field semantics, so an agent can distinguish update from create without opening either schema.

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

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

The patch constraint ('only the fields given change') gives real usage context and the tmdb_id line implies a refresh workflow, but there is no explicit when-to-use/when-not guidance against siblings that also mutate a film (set_rating, write_review, trash_film). Usage is implied rather than routed.

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

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

Description adds real behavioral context beyond annotations: content 'Replaces what is there' (overwrite semantics on an idempotent write) and the authorship constraint that the review text must be the user's, not agent-composed. Annotations already cover safety (readOnly=false, idempotent=true), so this extra guidance is credited. Minor tension between field replacement and destructiveHint=false, but replacement within a record is not the resource-level destruction the hint describes.

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

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

Purpose is front-loaded in the first line, followed by the useful authorship directive and a compact Args list. The docstring formatting is slightly verbose but each line adds information; nothing is wasted.

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

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

For a 5-parameter mutation tool with annotations covering the safety profile and an output schema covering returns, the description is complete enough to call correctly. The only shortfall is that rating/date semantics point to a sibling tool rather than being self-contained.

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

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

With 0% schema description coverage, the description carries the full burden and documents all five parameters: id (film id), content (HTML or plain paragraphs, replaces existing), rating (whole 1-10), date (shown on review), publish (draft->published). It defers exact rating/date formatting to create_film, which is a minor gap but keeps semantics clear.

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 ('Put Rolle's review text on a film'), which cleanly identifies this as writing a review to an existing film record. It doesn't explicitly contrast with update_film or create_film, so the agent must infer the boundary, but the action itself is 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?

Usage is implied through parameter hints ('publish: True moves a draft to published', 'See create_film' for rating/date formats), which tells the agent how to invoke it but not when to choose it over update_film or set_rating. No explicit 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.