CineSenseAI

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

Annotations already establish read-only and non-destructive behavior, but the description adds useful context: subscriber-only season access, ambiguous-name candidate lists, and the shape of returned detail such as age reason, mood, main irritant, and score. It does not cover auth requirements or rate limits beyond the subscriber note.

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

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

The description is a single dense sentence that front-loads the core lookup behavior and key return cases. The domain term 'door' is slightly opaque, but otherwise there is little wasted text.

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

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

An output schema exists and annotations cover safety, while the description still explains result shape, ambiguous-name handling, and subscriber gating. It is adequate for a simple lookup tool, though parameter-specific behavior such as language and year filtering is not elaborated.

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

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

Schema coverage is 75%, with query, type, and year documented in the schema. The description restates that query can be a name or id but adds little about lang, year, or type beyond what the schema already says, so baseline 3 is appropriate.

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

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

States a specific verb and resource: find one film or series by name or id, plus what is returned and how ambiguous names behave. It does not explicitly contrast with the sibling search_titles tool, so it is clear but not fully differentiated.

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

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

Usage is implied: use this for a single known title by name/id, and an ambiguous name returns a short candidate list. It does not explicitly say when to use search_titles instead or when not to use 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds that this returns a scoped, aggregated snapshot ('latest', 'last taste analysis'), which is useful behavioral context. It says nothing about auth requirements, how large the payload is, or whether 'latest' is bounded — minor gaps given annotation coverage and an output 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?

One compact sentence that front-loads the possessive scope ('Your account:') and then lists the payload. Nothing is wasted. It is a noun-phrase fragment rather than a sentence with a verb, which is acceptable but slightly less clear than a full statement.

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

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

For a read-only aggregate tool with an output schema, the description need not explain return values, and the annotation set covers the safety profile. However, the undocumented `lang` parameter and the missing distinction from run_taste_analysis leave real gaps for an agent deciding how to call 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% and the single `lang` parameter (a 17-value enum) is never mentioned in the description. An agent cannot tell from the text whether `lang` localizes labels, filters content, or is required for reasonable output. The enum values are self-evident as language codes, but the description fails to compensate for the coverage 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 verb+resource combination ('get my taste') is backed by an explicit enumeration of what is returned: ratings, irritants, personal tags, profiles, and the last taste analysis. That enumeration distinguishes it in practice from siblings like list_profiles, rate_title and run_taste_analysis. It stops short of naming which sibling to use instead, so it is clear but not fully differentiated.

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

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

There is no statement of when to call this versus alternatives, which matters here because run_taste_analysis sits right next to it and this tool only returns the *last* analysis. It also doesn't say whether this is the right entry point for a first-time agent or a summary/dashboard read. Usage can only be inferred from the returned-data 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=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds little beyond that — 'curated selections' hints at static, non-personalized catalog data and 'where it has one' warns that descriptions may be absent, which is mildly useful, but nothing on caching or freshness.

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 tightly packed sentence with zero filler, and the key differentiator (slug feeding profile_titles) is placed early. The fragmentary, verb-less construction is the only structural weakness.

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 the field-by-field enumeration is redundant, while the one genuine unknown — the semantics of the lang enum and its default — is left entirely unaddressed. For a localization-aware catalog tool this leaves a real gap before 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?

There is one parameter, 'lang', with a 17-value enum and 0% schema description coverage, and the description never mentions language at all. An agent cannot tell from the definition that lang localizes profile titles/descriptions or what the default is when omitted.

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

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

Names the specific resource (ready-made taste profiles / curated selections) and enumerates what each entry carries, and points at the sibling that consumes it ('its slug for profile_titles'). It lacks an explicit verb ('List'), reading as a noun phrase, but the intent 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?

The reference to profile_titles implies the discover-then-fetch flow, so usage is inferable. However it never says when to reach for this tool versus get_my_taste or run_taste_analysis, and states no exclusions or preconditions.

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 establish that this is a read-only, non-destructive, closed-world operation. The description adds that the profile is 'ready-made' and that each title comes with 'its door,' but it does not clarify what a door is or mention pagination, language behavior, or the analyzed_only default beyond what the schema states.

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 short sentence with no filler and is front-loaded around the core resource. Its compactness is effective, though the unexplained 'door' jargon slightly reduces how well the sentence lands.

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 read-only list tool with an output schema, annotations, and high schema description coverage, the description provides enough context to locate the tool in the workflow by naming the slug source. It still leaves 'door' undefined in the description, but the schema's analyzed_only field supplies enough supporting 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 80%, so the schema already documents most parameters, and a baseline of 3 is appropriate. The description adds a small amount of meaning by tying slug to list_profiles and hinting at the 'door' concept related to analyzed_only, but it does not explain lang, page, or limit semantics beyond the schema.

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

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

The description identifies the resource as the titles of one ready-made profile and specifies that the slug comes from list_profiles, which helps distinguish it from list_profiles itself. It is less clear against siblings like search_titles or find_title, and the term 'door' is unexplained jargon rather than a plain verb-and-resource statement.

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 parenthetical '(slug from list_profiles)' gives one useful workflow prerequisite, implying the agent should call list_profiles first. However, it does not say when to choose profile_titles over alternatives such as search_titles or find_title, nor does it provide exclusions or clearer usage context.

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?

Adds real behavioral context the annotations don't carry: ambiguous names are refused with candidate ids, and the tool accepts either a name or an id. However, annotations declare destructiveHint=true and idempotentHint=true, and the description never warns that an existing rating may be overwritten or that repeat calls are safe — the key mutation semantics are left to the annotations.

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

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

Two tight sentences, front-loaded with the core action before the edge-case behavior and the sibling redirect. The phrase 'and its saved mark' is slightly compressed but 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?

An output schema exists, so return values needn't be described, and the ambiguity-refusal path is covered. The one missing piece is the destructive-overwrite warning for replacing an existing rating, which matters for a mutation tool flagged destructive.

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 86%, so the schema already explains type/year/saved/score/title/rating. The description restates the name-or-id input and the like/dislike/score choice without adding format or precedence detail (e.g. how rating and score interact), so it sits at the baseline.

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 ('Set the user's rating of a title') and enumerates the accepted rating forms (like, dislike, score 1–10) plus the saved mark. It is clearly distinguishable from remove_rating and from lookup siblings like find_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?

Explicitly routes removal to remove_rating and explains what happens when a name is ambiguous (refusal with candidate ids), which tells the agent how to recover. It stops short of stating when to prefer this over search_titles/find_title for disambiguation up front.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description goes further by emphasizing permanence ("The user's own data, gone for good") and disclosing an error behavior not visible in structured fields: ambiguous names are refused with candidate ids. It stops short of stating auth/permission requirements.

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 destructive scope front-loaded and the ambiguity warning last. "The user's own data, gone for good" is stylized but earns its place as a caution rather than padding.

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

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

An output schema exists so return values need no explanation, and the description still covers what is destroyed, the partial-delete option, and the ambiguity failure path. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 80%, so the schema already documents title, type, year, and what. The description only restates that title accepts a name or id and that what=both deletes both artifacts; it adds no enum nuances or format detail beyond the schema. Baseline 3 for a high-coverage 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 ("Deletes the user's rating of a title") plus the scope of the deletion (rating and/or saved mark). It is clearly distinguishable from rate_title by the delete verb, though it never names rate_title or any sibling as the inverse operation.

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

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

Usage is implied rather than stated: the note that a name matching several titles is refused with candidate ids tells the agent it may need year/type or an id, which is useful selection guidance. But there is no explicit when-to-use-vs-alternatives framing, e.g. pointing at rate_title to overwrite instead of removing first.

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 description frames the tool as producing suggested tags and deferring saving to save_taste_tags or update_personal_tag, which implies a non-destructive analysis step. This conflicts with destructiveHint=true in the annotations, so the description contradicts the declared safety profile.

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

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

A single front-loaded sentence with no wasted wording. The parenthetical adds useful next-step routing without bloating the definition.

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

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

An output schema exists, so return values need not be explained, but the definition still omits the meaning of lang and fails to explain the destructive behavior implied by destructiveHint=true. For a destructive-flagged tool, that is a material gap.

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 only parameter is optional lang with an enum, and schema description coverage is 0%. The description never mentions lang or what language selection affects, so it does not compensate for the missing schema documentation.

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

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

States a specific verb and resource: analyse ratings into suggested personal tags. It names save_taste_tags and update_personal_tag as downstream alternatives, which helps distinguish next steps, though it does not clearly differentiate from get_my_taste.

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 subscriber-only context and tells the agent what to do with the suggested tags afterward. It does not explain when to choose this tool over analysis-related siblings such as get_my_taste, nor 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?

Annotations already declare this is a non-read-only, non-destructive, closed-world write. The description adds that it creates new personal tags and is restricted to subscribers, which is useful context. It does not explain duplicate handling, replacement behavior, or what happens if suggestions already exist.

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

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

The description is a single front-loaded sentence with no wasted words. 'Subscribers:' is slightly terse, but the core action and source are immediately clear.

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

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

Output schema and annotations are present, so return values and safety profile need not be described. Still, for a mutation tool, the description is thin on permissions ('Subscribers' only), duplicate/replacement behavior, and how lang affects saved tags.

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 50%, with descriptions for tags, name, and title_ids but none for lang. The description adds meaning by framing 'tags' as suggestions produced by tag_from_titles, but does not explain the optional lang parameter or any constraints beyond the schema.

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

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

The description states a specific action (save suggestions as new personal tags) and names the source sibling tool, tag_from_titles. It is clear what the tool does, though it does not explicitly distinguish itself from siblings like save_taste_tags or update_personal_tag.

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 by 'Subscribers' and by referencing tag_from_titles suggestions, suggesting it should be used after generating suggestions. However, there are no explicit when/when-not rules or comparisons to alternatives such as save_taste_tags.

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=false, destructiveHint=false, and openWorldHint=false, so the write-safety profile is covered. The description adds that each saved tag gets a profile of its own, which is useful non-schema context, but says nothing about how existing tags are handled, whether duplicates are merged, or any limits/permissions beyond 'Subscribers'.

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

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

A single front-loaded sentence with no wasted verbiage. Slightly awkward phrasing ('save suggestions of your taste analysis as new personal tags') but efficiently sized for the tool's complexity.

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

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

An output schema exists, so return values need not be explained. But for a mutating, subscriber-gated tool with a partially undocumented schema, the description leaves open duplicate handling, tag-count limits, and the meaning of 'lang', so it is only minimally complete.

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

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

Schema coverage is 50%: the 'tags' array and its nested fields (name, title_ids) are described in the schema, while 'lang' has no description. The description adds only the framing that these are 'suggestions' from a taste analysis, not clarifying the language parameter or item semantics, so 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 gives a specific verb+resource: saving taste-analysis suggestions as new personal tags, and notes each tag gets its own profile. However, it does not distinguish this tool from close siblings like save_tags_from_titles and tag_from_titles, which sound nearly identical, so an agent cannot route between them from the description alone.

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 'Subscribers:' prefix implies a precondition and 'suggestions of your taste analysis' hints that it follows run_taste_analysis output. But there is no explicit when-to-use/when-not guidance and no mention of when to prefer save_tags_from_titles or tag_from_titles instead.

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

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

Annotations already establish a safe read-only, non-open-world profile, and the description adds real value on top: results carry a 'door' (analysis), a `notes` field explains what was not understood, the `like` anchor is echoed back, and several parameters are gated on subscriber sign-in. It does not discuss pagination depth or result size limits beyond what the schema states.

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?

Four sentences that are front-loaded with the capability and then the operational caveats; every sentence carries information. Some phrasing is idiosyncratic ('each result carries its door'), which slightly costs first-read clarity but is not wasted text.

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 20-parameter tool with nested axis/irritant objects and an output schema, the description covers the non-obvious operational needs: empty-result recovery via `notes`, auth-gated options, and conversational presentation. Combined with 95% schema coverage and an output schema, an agent has what it needs to call this correctly.

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

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

Schema coverage is already 95%, so baseline is 3, but the description adds cross-parameter semantics the schema cannot express: `like` is incompatible with `text`, `exclude`, and `profile`, results are similarity-ordered unless `sort` overrides, and other filters narrow the similar set. That is genuine meaning beyond the field-level docs.

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

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

States a specific verb ('Films and series by ...') plus the full breadth of filterable dimensions (genre, country, years, age rating, score, tags, axes, irritants, similarity to one title). An agent can distinguish this filtered-discovery tool from lookup-style siblings like find_title or profile_titles 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?

Gives concrete operating guidance: read `notes` first, loosen filters after an empty answer, and in voice conversations offer two or three titles with reasons. It also flags that personal options require sign-in. It stops short of explicitly routing away from find_title or profile_titles, so no exclusion rule is stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds only the subscriber precondition and does not disclose that changes are destructive, idempotent, or how omitted irritants behave — that detail lives in the schema, not the description. 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?

A single tight sentence with the audience qualifier front-loaded and no filler. It is efficient, though it is arguably too sparse to be maximally useful.

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 and rich annotations exist, so return values and safety are not the description's burden. Still, for a nested-object, destructive, subscriber-gated mutation, the description leaves gaps: no mention of the destructive nature, no clarification of the undocumented lang parameter.

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 reinforces that levels are per-irritant and define a hiding threshold, which adds meaning over the raw enum of integers. But with schema description coverage at 50%, the 'lang' parameter's purpose is left entirely unexplained in both schema and description, so compensation is only partial.

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 (set) and resource (irritant levels / hidden thresholds per irritant), and 'Subscribers:' scopes who it applies to, which separates it from rating or taste-profile siblings. It stops short of distinguishing itself explicitly from tools like rate_title, but the resource is concrete enough to identify the operation.

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?

'Subscribers:' implies a precondition (subscription required) and the schema note about 0 disabling an irritant and omitted keys remaining unchanged clarifies partial-update usage. However, the description never states when an agent should call this versus related siblings, and no when-not guidance is given.

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 it is a non-readonly, non-destructive, closed-world operation, and the description adds the crucial behavioral point that the non-single mode only suggests tags that must then be saved or merged elsewhere. It does not cover failure modes or persistence details beyond that, but it discloses the main mutation-adjacent behavior 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?

A single tightly packed sentence that is front-loaded with the purpose and then layers the two modes and alternatives. Every clause carries information, though the em-dash-heavy construction is slightly harder to parse than a clean 5 would be.

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

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

An output schema exists, so return values need not be explained, and the description covers both operating modes plus the required follow-up actions. The only notable gap is that lang is undefined, but with full enum documentation in the schema that is a minor omission.

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

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

Schema coverage is 75% and already documents name, single, and titles, so the baseline is high. The description still adds real meaning by explaining the coupling between single=true and the name parameter, which the schema states only superficially. It does not explain the lang enum, so it falls short of 5.

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

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

States a specific verb and resource ('a personal tag from titles') and distinguishes two output modes: one tag when single=true plus a name, otherwise suggested tags. It also names the sibling persistence tools. Slightly dense phrasing ('suggested tags that split them') leaves the exact nature of the non-single output mildly ambiguous, so it's not a clean 5.

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

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

Explicitly tells the agent when to use each mode (single=true with a name for one tag; otherwise it produces suggestions) and names the follow-up alternatives save_tags_from_titles and update_personal_tag. That is a full when/when-not/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?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds the concrete consequence: the old titles are dropped and the tag keeps its name. It also discloses the subscriber requirement, which annotations do not carry. It stops short of saying whether title_ids must belong to the named tag or what quota/validation errors look like.

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

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

Two sentences with no waste. The destructive effect is front-loaded in the parenthetical before the alternative routing, which is the right order for a mutation tool.

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

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

For a destructive mutation with an output schema and full annotation coverage, it covers what is replaced, what is preserved, the audience restriction, and the sibling alternative. Minor gaps remain around the lang parameter and source/title_ids provenance matching, which an agent must infer.

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

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

Schema coverage is 75%, so the schema already documents tag, source, and title_ids. The description only supplies the framing that title_ids are 'the suggestion's' titles; the lang parameter is unexplained in both places and the coupling between the source enum value and where title_ids came from is left to the schema.

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

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

States a specific verb and resource ('replaces the titles of one of your existing personal tags with the titles of a suggestion') and immediately distinguishes it from the tag-creation siblings save_taste_tags and save_tags_from_titles. An agent can tell this apart from both creation tools without opening any schema.

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

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

The 'Subscribers:' prefix signals an access prerequisite, and the closing sentence explicitly routes new-tag creation to save_taste_tags or save_tags_from_titles. There is no explicit statement of when-not to use it beyond that, but the editing-vs-creating split is clear.

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