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

With no annotations, the description carries the behavioral burden. It adds meaningful context beyond the schema: this is intentionally cheap, acts as a sync gate, and its `all` value indicates whether changes occurred. It does not discuss auth or rate limits, but the read-only and lightweight nature is strongly implied.

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 short sentences with no filler. The core purpose is front-loaded, and the second sentence earns its place by explaining the tool's strategic role in syncing.

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

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

For a zero-parameter tool with an output schema available, the description is complete enough. It tells the agent what the tool provides, why it should be called, and how to interpret the key signal (`all`) to decide whether further fetching is needed.

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 no parameter ambiguity. Baseline for zero-parameter tools is 4, and the description's mention of `all` refers to the response payload rather than input, which is appropriate.

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

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

The description clearly identifies the resource and output: timestamps of the user's most recent list changes. It is not a tautology and is easily distinguished from sibling tools like get_library or get_ratings, though it uses a noun phrase rather than an explicit verb like '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 explicitly frames the tool as 'the cheapest call in the API' and 'the gate for every sync,' telling the agent exactly when to invoke it. It also gives a concrete when-not condition: if `all` has not moved, nothing needs fetching.

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 full burden and it delivers: it discloses the deletion-never-in-delta limitation, the skipped counter semantics, and the obligation to surface non-zero skipped to the user. It also defines the read-only nature by its opening verb.

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 front-loaded: purpose first, then each parameter, then caveats. Every sentence adds operational value; no filler or repetition.

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

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

For a read tool with a present output schema, the description covers the non-obvious behavior (deltas, deletions, skipped holes) that the schema cannot convey, and gives enough parameter detail to make the correct call without external lookup.

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% and there are no enums, yet the description fully documents all three parameters: valid values for type, valid statuses, omission behavior, and the exact date_from contract ('ISO timestamp from get_activities, passed back byte-for-byte').

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

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

Opens with 'Read the watch history and watchlists,' a specific verb plus resource that immediately distinguishes this from sibling tools like get_activities (activity log) and get_library_ids (ID diffing). The rest of the description reinforces the scope with filtering dimensions.

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

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

Explicitly explains the delta mode ('With it you get only what changed since; without it, the full library') and gives a when-not condition: 'Deletions never appear in a delta... call get_library_ids and diff instead.' This is actionable 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?

With no annotations, the description carries the full burden of behavioral disclosure. It goes beyond the schema by revealing that absent IDs are equivalent to removal and that Simkl wipes stored ratings on removal, which is valuable behavioral context. It does not mention auth or rate limits, but those are less critical for this simple read-style 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 two crisp sentences with no fluff. The core purpose is front-loaded, and the deletion-reconciliation context is provided in a compact supporting sentence.

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 and has an output schema, so the description covers the main behavioral context and interpretation rules well. The only real gap is the unexplained 'type' parameter, which prevents a fully self-sufficient definition.

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 single optional 'type' parameter has no schema description (0% coverage) and the description never mentions it. The agent is left without guidance on what values it accepts or how it affects the returned IDs, so the description does not compensate for the schema 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 states a specific verb-resource pair: returns every Simkl ID in the library, and explicitly narrows scope with 'and nothing else.' This clearly distinguishes it from the sibling get_library tool, which presumably returns fuller library objects.

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 concrete use case—'the cheap half of deletion reconciliation'—and explains how to interpret missing IDs. It does not explicitly mention when not to use it or name an alternative, but the context is strong enough for an agent to select it appropriately.

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 it returns self-ratings and explains the rating scale meaning, which is useful. However, it does not mention pagination, ordering, authentication requirements, or side effects (though likely none). It does provide insight into how the output should be interpreted, which adds behavioral context. Overall, adequate but not comprehensive for a getter with no annotation coverage.

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

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

Three concise sentences: purpose, parameter usage, and rating interpretation. The purpose is front-loaded, and each sentence adds distinct value without redundancy. No wasted words or filler. Efficient and well-structured.

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

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

Given an output schema exists, the description need not detail return format. It covers both parameters, their allowed values, and optionality, and adds interpretive guidance. It is sufficient for an agent to call the tool correctly. Minor omission: exact string casing for type values (e.g., 'movies' vs 'movie'), but likely implied. Overall, complete enough.

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

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

Schema descriptions are completely absent (0% coverage), so the description must compensate. It clearly explains the 'type' parameter values (movies, shows, anime) and the 'rating' parameter range (1-10) and optionality (omit for all). It adds semantic meaning to rating values as positive/negative signals, going beyond simple type definitions. This is strong parameter documentation.

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

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

The description clearly states the tool retrieves titles the user has rated, specifying the resource and scope. It does not explicitly differentiate from sibling tools like get_library or lookup_watched, but the resource is distinct enough that an agent can infer its purpose. The note about ratings as positive/negative seeds adds context but does not aid sibling differentiation.

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

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

The description explains parameter usage (type and rating) but lacks explicit when-to-use vs alternatives. It does not say 'use this when you need the user's ratings for recommendations' or exclude other tools. The rating semantics provide interpretive guidance, not tool-selection guidance. The usage is implied from the purpose, not explicitly 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?

With no annotations, the description carries the full burden. It explains the mutable nature of the type field and the users_recommendations field, but does not explicitly state that it is a read-only operation, nor does it cover error cases or authentication requirements. The output schema covers return structure, so that is acceptable.

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, using three sentences with no fluff. It front-loads the purpose, then clarifies the type field and mentions the recommendations field. The structure is logical and easy to scan.

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

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

For a simple get tool with two parameters and an output schema, the description covers the essential aspects: the return scope and the type semantics. However, it omits any mention of prerequisites like authentication or how the simkl_id should be obtained, which could leave an agent uncertain about the full calling context.

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 thoroughly explains the type parameter (movie, tv, anime, and its changeable nature), but gives no additional detail about simkl_id beyond its name. The ID is self-explanatory, but the description does not clarify how to obtain it or its format.

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 returns a 'full detail record for one title' including viewer-based neighbors. It distinguishes itself from sibling tools by focusing on a single title's complete record, and the type field clarification adds specificity.

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 guidance on the type parameter, advising to follow Simkl's classification rather than assume. However, it does not explicitly mention when to use this tool versus alternatives like search or resolve_id, nor does it state any prerequisites such as needing a simkl_id from another endpoint.

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 usefully notes that the token is not revealed, and 'whether' implies a read-only status check, but it does not explicitly state that no token data is returned or that no side effects occur.

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 clear sentence with no filler. The most important facts—status check and token non-revelation—are both present and 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?

For a zero-parameter status check with an output schema, the description is largely sufficient. It lacks explicit usage context, but nothing about inputs or return values is missing given the output schema exists.

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

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

The tool has zero parameters, so parameter semantics are not a concern. The description correctly communicates that no inputs are needed and does not need to compensate for 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 description states the tool reports whether the server has a usable Simkl token, which is a specific status check resource. It is distinguishable from sibling tools that mutate or query library data, though it uses a copular 'whether' construction rather than an explicit verb.

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

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

The intended use is implied: call this to check authentication status before using Simkl-backed tools. There is no explicit guidance on when to use it instead of logout or other auth-related operations, and no exclusion criteria.

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

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

With no annotations, the description carries the full burden and does it well: it states the local side effect clearly and explicitly discloses the non-revocation limitation. This is exactly the kind of non-obvious behavioral context an agent needs.

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

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

Two short sentences with no filler. The main purpose is front-loaded, and the important caveat about remote revocation follows immediately.

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 local logout action with an output schema and simple behavior, the description covers everything necessary: what happens locally, what does not happen remotely, and where to go for the stronger action.

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

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

There are zero parameters and the schema fully covers this. The description adds nothing about parameters, but none is needed; baseline for zero-parameter tools applies.

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

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

States a specific verb and resource: deleting the stored Simkl token from this machine. This clearly distinguishes the tool from generic 'logout' and from sibling tools like remove_from_history or login_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?

Explicitly explains that this does not revoke the app on Simkl's side and directs users to simkl.com/settings/apps for that action. This provides a clear exclusion and an alternative, though it does not discuss in-tool alternatives.

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

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

With no annotations, the description carries the disclosure burden and does well: it states this queries Simkl directly, returns a parallel array with library status and last-watched time, and is independent of the local mirror. It does not cover error cases or authentication, but the key behavioral traits 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 compact and well ordered: purpose, input format, output behavior, then rationale. Every sentence adds useful information, and there is no redundant filler.

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

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

The tool has only one parameter, the description explains its shape and the output in broad terms, and an output schema exists so return details need not be repeated. It is complete enough for selection and invocation, though minor edge-case behavior such as invalid ID keys is not addressed.

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, and it does. It explains that 'items' is a list, shows an exact example with simkl and imdb ID keys, and clarifies that any mix of supported ID keys is accepted. This goes well beyond the minimal array-of-objects 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 opens with 'Ask Simkl directly whether specific titles are already in the library,' a specific verb and resource. It further distinguishes itself by noting this is a server-side check independent of the local mirror, separating it from sibling tools like get_library and get_library_ids.

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

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

The description gives clear usage context: it is the server-side check behind the 'never already seen' guarantee and is independent of the local mirror, catching activity since the last sync. It implies when to prefer this tool over local-mirror lookups, though it does not explicitly name alternatives or say 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?

With no annotations, the description must carry behavioral disclosure. It does reveal the 20-second serialization lock, the placeholder handling for 'long ago', and the anime envelope rule. However, it omits whether the operation is destructive, requires auth, or is reversible, leaving gaps 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?

The description is compact and front-loaded with a clear purpose sentence, then structured details. Each sentence adds value—format, type rules, and batching advice—with no fluff. It's slightly dense but efficient.

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

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

Given the minimal schema and lack of annotations, the description covers the essential input format, special cases, and operational constraints. An output schema exists, so return format is covered. It could mention error handling or overwrite behavior, but the core usage is adequately 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 coverage is 0% and the description fully compensates. It explains type values (movie, tv, anime), the items array structure with ids and watched_at, and the 1970-01-01T00:00:01Z placeholder. This adds substantial meaning 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 states a clear action (record watched titles) with a specific resource (user's watch history). It's not a tautology and is distinguishable from siblings like set_status or rate, though it doesn't explicitly contrast them.

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

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

The description provides no guidance on when to use this tool versus alternatives. It only gives operational details (format, batching) and never mentions exclusions or comparisons to sibling tools like set_status or remove_from_history.

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 disclosing side effects. It explicitly states that rating an item not on a list auto-files it, and details the mapping for different content types. The warning to trust the response rather than predict the delta adds useful transparency. However, it does not cover behaviors for already-rated items, permissions, or reversibility.

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, with the primary purpose front-loaded in the first sentence. The subsequent sentences add necessary behavioral context without excessive verbosity. It could be slightly more structured, but it is efficient and readable.

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 (mutation with side effects), the lack of annotations, and zero schema coverage, the description is incomplete. It does not explain parameter semantics, what the output schema will contain, error conditions, or prerequisites like authentication. The warning about the delta hints at a response but does not describe it.

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

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

Schema description coverage is 0%, so the description must explain the parameters, but it does not. It only hints at the rating range ('1-10') and says nothing about the structure of 'items' or the meaning of 'type'. The agent is left without essential information to construct valid arguments.

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

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

The description opens with a specific verb and resource: 'Rate titles 1-10.' It also discloses a key side effect (auto-filing) that distinguishes this from sibling tools like get_ratings (read-only) or set_status (explicit status change). The purpose is unambiguous and differentiated.

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

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

The description explains a behavioral consequence (auto-filing) but provides no explicit guidance on when to use this tool versus alternatives. It does not mention set_status or mark_watched, nor does it state conditions for choosing this tool over them. The 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?

With no annotations provided, the description carries the full burden and does disclose two important side effects: wiping the Simkl rating and re-enabling recommendation inclusion. It does not mention permanence or authorization requirements, but the key destructive consequence is clearly stated.

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 with the primary action stated first and necessary caveats following. Every sentence earns its place and there is no 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?

The description covers the core behavior and important side effects, and an output schema exists so return values need not be explained. However, the required parameters are not documented enough for a fully reliable call, leaving a notable gap in self-sufficiency.

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 only implies that the items are 'titles,' giving a small hint toward the items parameter. It provides no guidance on the required 'type' value or the object shape for each item, and with 0% schema description coverage and no enums, the agent is left to guess.

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: remove titles from watch history. The added side-effect details further clarify what the tool uniquely does, distinguishing it from read-only or status-setting sibling tools.

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 practical context: removing items stops them from being excluded from recommendations, which is usually the point of using this tool. It does not explicitly name alternatives or say when not to use it, but the intended use case is evident.

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

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

With no annotations, the description carries the behavioral-disclosure burden. It adds useful non-obvious behavior by explaining the redirect handling ('Reads the 301's Location header without following it') and the TMDB ambiguity refusal, but it does not mention authentication, rate limits, or other potential side effects, so it is not fully transparent.

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

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

The description is compact and well front-loaded: the one-line purpose comes first, followed by necessary caveats about TMDB IDs and redirect behavior. Each sentence contributes meaning, though 'the cheapest way in' adds only mild informational value.

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

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

Given five optional parameters, no schema descriptions, and no annotations, the description should clarify how to supply mal/imdb/netflix IDs and what happens when multiple IDs are provided. It only covers the TMDB+type scenario, leaving significant input-side gaps; the output schema helps but does not resolve these.

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 only explains `tmdb` and `type`. The `mal`, `imdb`, and `netflix` parameter formats, mutual exclusivity, and selection precedence are not addressed, leaving most parameters underspecified.

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

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

The description clearly states the tool's action and result: 'Turn an external ID into a Simkl ID -- the cheapest way in.' It identifies a specific verb and resource, but it does not explicitly differentiate from sibling tools such as search or get_library_ids.

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

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

The description provides one concrete usage rule: a TMDB ID requires `type` ('movie' or 'show') because a bare TMDB ID is ambiguous and refused. It implies this is the cheapest resolution path, but it does not explicitly say when to prefer this tool over alternatives 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?

With no annotations provided, the description carries full behavioral burden. It discloses key behavioral traits: title collisions are common, results are candidates, and disambiguation by year and type is required. It does not mention limit behavior or rate limits, but the output schema covers return structure and this is a read-only search operation.

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

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

The description is tight and front-loaded: a clear one-line purpose, followed by parameter nuanceable, then a concrete caution about ambiguity. Every sentence earns its place without redundancy.

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

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

The description is complete for a search tool with an output schema. It explains the input semantics, warns about ambiguity, mandates disambiguation, and routes to resolve_id when appropriate. 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?

Schema description coverage is 0%, so the description must compensate. It does add meaning for 'query' ('by title') and for 'type' (enumerates values and explains omission behavior). 'limit' is not explicitly described, but its standard meaning and default of 10 make this a minor 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 opens with a specific verb and resource: 'Search Simkl by title.' It clearly distinguishes this tool from sibling resolve_id by framing search as title-based lookup rather than external-ID lookup.

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 provides explicit usage context: type can be 'movie, tv or anime' or omitted to search everything. It also tells the agent to treat every result as a candidate to disambiguate, never as the final answer, and names resolve_id as the preferred alternative when an external ID is available.

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

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

With no annotations, the description carries the full burden and it delivers two genuinely useful behavioral disclosures: movies do not support watching/hold, and completed silently becomes watching for still-airing shows. This goes well beyond the schema, though it omits details like overwrite behavior, permissions, or return semantics.

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-fragmented into purpose, valid values, and edge cases. Every sentence adds value, and the most important behavioral caveats are clearly highlighted.

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

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

The description covers status values and notable edge behavior, giving an agent useful invocation context despite the opaque schema. It is not fully complete because the type parameter is unexplained and there is no guidance on the shape or required fields of items, so an agent may still guess incorrectly on first call.

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 to the status parameter by listing valid values, which the schema does not provide. But it says nothing about the required type parameter or how items should be structured, leaving significant parameter semantics uncovered at 0% schema coverage.

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 action ('Move titles into a watchlist status') and lists the valid status values, making the resource and operation clear. It does not explicitly contrast itself with siblings like mark_watched, but the 'watchlist status' framing distinguishes it from related tools.

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 makes the intended use context clear: updating a title's watchlist status. However, it does not state when to prefer this tool over siblings such as mark_watched or remove_from_history, nor does it mention any exclusions or prerequisites.

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