Achriom

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the recommended lookup workflow but says nothing about what happens on duplicate titles or what a successful add 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?

Three short sentences, the core action first and the classification warning front-loaded at the end. Every sentence carries information, though the all-caps emphasis is slightly louder than needed for content already in the schema.

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

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

With annotations covering idempotency and mutation semantics and a fully described 7-parameter schema, the description supplies the workflow and typing conventions an agent needs. Duplicate-handling behavior is the one gap, partially mitigated by idempotentHint.

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

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

Schema coverage is 100%, so all seven parameters are already documented in the schema, including the anime/show enum note the description repeats. The only added value is tying external_id to the lookup_item workflow, which is marginal against a fully described 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 ('Add a new item to the library') that an agent can act on immediately. It is implicitly distinguishable from bulk_add_items and add_to_list, but never names those siblings to sharpen the boundary.

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 when-to advice: call lookup_item first to obtain external_id, and apply the anime-vs-show classification rule. It stops short of stating when to prefer bulk_add_items or add_to_list over this single-add 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 readOnly=false, idempotent=true, destructive=false, so the safety profile is carried structurally. The description adds genuinely new behavior: the implicit list creation side effect and the library-membership prerequisite. It doesn't say what the ambiguous-title response looks like, though the schema parameter text does.

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, front-loaded with the primary action, followed by the auto-create behavior and the prerequisite. Nothing redundant and no filler.

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

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

For a 5-parameter mutation tool with full schema coverage and no output schema, the description covers the primary action, the side effect, and the precondition — everything needed to invoke it correctly without opening sibling tools.

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

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

Schema coverage is 100% and the parameter descriptions are already rich (exact-title preference, item_id override, case-insensitive list_name). The description's only added hint is 'by title', so it neither regresses nor meaningfully extends the schema — baseline 3.

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 ('Add a library item to a list') and immediately adds the two scope facts an agent needs: the list is auto-created and the item must already exist. This distinguishes it cleanly from add_item and create_list in the sibling set.

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 to the sibling: 'use add_item first if not' handles the precondition, and 'Creates the list if it does not exist' tells the agent not to call create_list first. Both the when-to-use and the when-to-use-something-else cases are covered.

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

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

Annotations already declare mutation safety and idempotency, but the description adds critical behavioral context beyond them: fuzzy title resolution can silently choose wrong versions, bad matches are expensive to undo, duplicate items are skipped, and results include honest per-item counts.

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 and usage rules, then layers in disambiguation risks, return shape, and follow-up status handling. Despite being dense, every sentence provides actionable guidance for correct invocation.

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?

Complete for a bulk mutation tool with no output schema: it explains the return object shape, the default status behavior, error modes, and the follow-up tool for status changes. Annotations plus schema cover the rest.

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

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

Schema description coverage is 100%, so the baseline is 3. The description meaningfully strengthens parameter guidance by saying to always pass year and external_id whenever known, explaining why those fields prevent silent misresolution—an important layer beyond the schema's optional phrasing.

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, and scope: add up to 250 items to the library in one call. It explicitly distinguishes itself from the add_item sibling by warning against looping.

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 clear when-to-use guidance (lists of more than 3 items), an explicit alternative to avoid (never loop add_item), and a prerequisite workflow for ambiguous titles (resolve via lookup_item). It also routes status changes to bulk_update_status.

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 behavior beyond the annotations: ambiguous titles are skipped and reported rather than guessed, and there is a hard 250-entry ceiling. It does not state what a repeat call does (idempotentHint=false implies duplicates), nor how many entries succeed when some fail, which matters for a non-idempotent mutation.

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

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

Three tight sentences: what it does first, then entry shape and formats, then the safety behavior and intended use. No restatement of the title and no filler.

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

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

For a one-parameter bulk mutation with no output schema, the description covers entry composition, date formats, item limit, partial-failure handling for ambiguous titles, and the intended scenario. An agent can construct a correct payload and predict failure modes from this alone.

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 load and does it well: it enumerates media_type, title-or-item_id, and the optional event_type, event_date, rating, and notes, plus the accepted date formats (YYYY-MM-DD, YYYY-MM, YYYY). It omits any guidance on when to prefer item_id over title and on the rating scale.

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 ('Log finish or re-watch/re-read/re-listen events') and immediately scopes it as bulk ('for many items in one call (max 250)'), which separates it cleanly from the single-item sibling log_event. The set of valid event kinds is spelled out, so an agent knows exactly what lands in the library.

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?

'Use for imports that carry finish dates' gives a concrete triggering scenario, and the 250-item cap signals when to split work. It stops short of explicitly naming log_event as the single-item alternative or saying what to do for the non-bulk case, leaving that inference to the agent.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that: the 250-item ceiling, partial-success semantics (matched/unmatched counts), and the instruction to tell the user what each batch touches. It stops short of stating that the status change is destructive/overwrites the prior value, which would have earned a 5.

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

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

The hard constraint is front-loaded and each sentence does work — the "no parameter will make one appear" line defensively blocks a known agent hallucination. It is slightly redundant, repeating the 250 cap already in the schema and restating the titles semantics, but nothing is wasted overall.

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 bulk mutation with no output schema, the description covers scope limits, partial-failure handling, and the required follow-up path. Combined with annotations that declare destructiveness and idempotency, an agent has everything needed to call it correctly and safely.

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

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

Schema description coverage is 100% and all three parameters are documented there, including exact/case-insensitive titles and the 250 max. The description largely restates that ("exact titles, case-insensitive, max 250 per call"), adding only the hint that `status` values must come from what update_status lists — which is also in the schema. Baseline 3 is appropriate.

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

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

The description names a specific verb and resource ("Update status for a specific list of items") plus the exact mechanism (`titles`, case-insensitive, max 250). It also explicitly carves out what it is not — unlike update_status, it cannot do library-wide changes — so an agent can distinguish it from siblings without opening a schema.

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

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

It gives an explicit when-not ("no way to update a whole library in one call") and a concrete alternative workflow: fetch titles first via get_by_status, then apply in explicit batches. It also routes the residual case — unmatched titles — to individual update_status calls, which is exactly the routing an agent needs.

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 the outcome state (item becomes unrated rather than deleted), which is genuinely new information beyond the annotations. It stops short of mentioning error behavior for already-unrated items, but given idempotentHint that gap is minor.

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, zero filler, with the purpose front-loaded and the sibling relationship appended as a routing hint. Nothing could be trimmed without losing meaning.

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

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

For a simple one-target mutation with full schema coverage and rich annotations, the description supplies purpose, outcome, and sibling routing. Only edge-case behavior (target missing, already unrated) is absent, which is a minor gap rather than a blocker.

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

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

Schema description coverage is 100%, with media_type enumerated and item_id explicitly preferred over title. The description adds no parameter-level guidance beyond what the schema already states, so baseline 3 applies.

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

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

States a specific verb and resource ('Remove the user rating from one library item') plus the resulting state ('leaving it unrated'). It also explicitly contrasts with the update_rating sibling, so an agent can distinguish the two without consulting 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 undo for update_rating' gives a concrete selection rule: use this when the user wants to unrate rather than set a new value. It does not spell out exclusions (e.g., item not found, or whether an unrated item errors), but the intended usage is clear.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context — that lists are private and can hold mixed media types — but says nothing about duplicate-name behavior, what is returned (e.g. a new list id), or visibility to other users.

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, front-loaded with the action, followed by just enough context to understand the object being created. No filler, though the example list names are marginally decorative.

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 two-parameter creation tool with full schema coverage and clear annotations, the definition covers what is created and its nature. The only real gap is return behavior (whether a list id comes back for subsequent add_to_list calls), which the agent would need to chain correctly.

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

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

Schema coverage is 100% and both parameters are documented in the schema itself, so baseline is 3. The description confirms a name is required ('named list') but adds nothing about the optional description field or any constraints on either.

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 ('Create a named list') and explains what a list is — a private, cross-media curated collection. This distinguishes it conceptually from sibling mutation tools like add_to_list or update_list, though it never names them directly.

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 only implied: the agent can infer this is the tool that must run before add_to_list or add_item, but the description never says so, nor does it contrast with update_list or delete_list. No exclusions or prerequisites are 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 already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral information the annotations cannot express: the no-selector case deletes nothing and instead returns the events with their ids for a follow-up call. It does not discuss permissions or partial-failure behavior, so not a 5.

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

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

Three short sentences, front-loaded with the verb and resource, then the sibling relationship, then the edge case. Every sentence carries distinct information; nothing is repeated from the schema or annotations.

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 six-parameter mutation with no output schema, the definition covers the identity of the operation, its inverse, and the most likely failure-to-act scenario along with what the agent gets back. The remaining details live in a fully described schema and explicit destructive annotations.

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 100% schema coverage the baseline is 3, but the description adds meaning the schema cannot: it establishes that event_date, event_id, and all are mutually exclusive selectors and explains the fallback when none is supplied. The item targeting (title vs item_id) is left entirely 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 (delete) and a specific resource (a logged finish/re-watch/re-read event on one item), which clearly separates it from delete_item and delete_review among the siblings. It also names log_event as its inverse, so the agent immediately knows the paired write 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?

The third sentence explicitly describes the ambiguous case (no event_date, event_id, or all with multiple events) and the resulting behavior, which tells the agent how to disambiguate. It stops short of naming sibling alternatives by name for the underlying item deletion or telling the agent which selector to prefer in normal cases, so it is clear context rather than a full when/when-not map.

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. The description adds nothing beyond that – it doesn't say whether dependent data (lists, ratings, progress) is cleaned up, whether deletion is reversible, or whether confirmation is expected.

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 no filler, front-loading the verb and target. It is efficient, though the brevity comes at the cost of the guidance noted elsewhere.

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

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

For a simple 3-parameter tool with full schema coverage and complete safety annotations, the minimum is met. What's missing is the blast radius of a destructive operation – side effects on lists, reviews, or watch progress – which an agent should know before calling 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 100%, and the schema itself explains the title-vs-item_id precedence and the ambiguous-partial-match behavior. The description contributes nothing on parameters, which is the baseline-3 case when the schema does the heavy lifting.

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

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

States a specific verb (delete) and resource (an item in the library), which is unambiguous on its own. It doesn't distinguish itself from close siblings like remove_from_list, delete_list, or delete_review, so the agent must infer that 'item' means a library entry.

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 guidance on when to use this versus remove_from_list, delete_list, or delete_review, and no prerequisites or cautions are mentioned. The target of deletion is inferable only from the word 'library.'

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 safety profile is covered; the description adds the genuinely useful blast-radius detail that list membership survives the deletion. It doesn't state whether the list deletion itself is recoverable, which is the remaining behavioral question for a destructive tool.

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

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

Three short sentences, front-loaded with the action and immediately followed by the consequence and the usage trigger. No filler.

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

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

For a one-parameter destructive tool with full schema coverage and annotations carrying the safety flags, the description supplies the one thing structured fields can't: what happens to list contents. Only the reversibility of the list deletion itself is left unaddressed.

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

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

Schema coverage is 100% and the single parameter already documents case-insensitive matching. The description adds nothing about the parameter beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ("Delete one of the user's lists") and implicitly separates itself from item-level siblings by noting the contents stay in the library. It never names remove_from_list or delete_item explicitly, so the sibling differentiation is inferred rather than stated.

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?

"Only when the user asks to delete the list itself" is an explicit precondition, and "Everything on it stays in the library" signals the when-not case (don't use this to clear items). It stops short of naming the alternative tool to use for removing contents.

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; the description adds non-obvious side effects beyond that, namely removal from the public page and preservation of the underlying rating and notes. It does not say what happens on a second delete or whether the review is recoverable.

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, zero filler, with the destructive effect stated first and the preservation guarantee second.

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 3-parameter destructive tool with full schema coverage and no output schema, the description covers the key concerns (what disappears, what survives). A note on behavior when no review exists would close the remaining 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?

Schema description coverage is 100%, so the schema already explains title vs item_id precedence and the media_type enum. The description adds only 'of one item' — a 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 ('Delete') and resource ('the user's review of one item') and immediately bounds the effect ('rating and notes are untouched'), which separates it from clear_rating and update_notes in the sibling list.

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 implies what this tool does *not* touch, giving partial routing guidance away from rating/notes tools, but no sibling is named and there is no explicit when-to-use or when-not rule.

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 context beyond the annotations: edits are personal overrides, the shared catalog is untouched, and null reverts a field to the catalog value, which meaningfully softens the destructiveHint=true signal. It also documents a concrete failure mode (error when no change field is given). It does not say what relinking via new_external_id does to existing overrides, nor what the call 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?

Purpose and scope are front-loaded, which is good, but the middle collapses into one very long parenthetical enumerating ten media types' field lists, which is hard to scan and largely incompressible in prose form. Bullets or a summarized pattern would have carried the same information more cleanly.

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

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

For a 7-parameter mutation tool with a nested free-form object, the description covers scope, formats, revert semantics, relinking, and error behavior well. The remaining gap is the return value, which matters because there is no output schema to fall back on.

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

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

Schema coverage is already 100%, but the description still earns credit by enumerating the editable field names per media type (book, movie, show, album, anime, plus 'equivalents' for podcast/game/manga) and by specifying value formats: YYYY-MM-DD dates, arrays for lists, https links for images, null to revert. That is meaning the schema cannot convey because `fields` is an open-ended object.

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 ('Correct an item in THIS user's library') and immediately distinguishes the personal-override scope from the shared catalog entry. It also separates itself from the closest sibling by noting re_enrich only refetches the same entry, so an agent can pick between them without opening schemas.

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?

Explicit routing guidance for the trickiest decision: use new_external_id when the wrong film/show/album was added, because re_enrich cannot fix a wrong match. It also states the error condition when no change field is supplied. It does not cover when to prefer this over status/date/rating siblings such as set_dates, set_format or bulk_update_status, leaving overlap for the agent 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?

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description usefully adds the mode precondition, but says nothing about what happens on a duplicate item or whether anything is returned.

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 short sentence with the mode constraint parenthesized and front-loaded, no filler. It is efficiently structured, though very terse 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?

With only 2 fully documented params and an output schema absent, coverage is mostly adequate. What is missing is differentiation from add_item and any statement of the effect or return, leaving the agent to infer them.

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

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

Schema coverage is 100%, including descriptions for both title and media_type plus an 8-value enum, so the schema carries the semantics. The description adds no meaning beyond it; baseline 3 applies.

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

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

States a specific verb (add) and resource (item to the current research corpus), and the mode qualifier narrows intent. It does not, however, distinguish this from the sibling add_item, which reads as nearly the same 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?

'focused research mode only' is a genuine usage precondition, but no guidance is given on when to pick this over add_item or bulk_add_items, nor how it relates to get_scope_info. Usage is implied rather than explained.

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, non-destructive and closed-world, so the safety profile is covered. The description adds nothing beyond that — it does not say whose ratings are matched, what ordering is returned, whether results are paginated, or how an omitted min/max bounds the range.

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

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

A single front-loaded sentence with no filler; nothing wastes space. Its brevity is efficient but tips into under-specification rather than crispness.

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. However, for a three-parameter filtered-list tool with many sibling retrieval tools, the description omits range-default behavior and sibling disambiguation, which the agent would need to call it confidently.

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

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

Schema coverage is 100%, with enum values, ranges and half-star increments already documented, so the baseline is 3. The description adds only the notion that the range is a 'user rating,' and says nothing about the required media_type or the open-ended behavior when only one bound is supplied.

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: retrieve items filtered by a user rating range. It is clear enough on its own, but it never contrasts itself with near-neighbors like get_by_status or search_library, leaving the boundary to be inferred from the name 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?

No guidance on when to pick this over get_by_status (status-based retrieval) or search_library (broader filtering), and no mention of prerequisites. The agent has to guess which retrieval tool is appropriate.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive operation, and the description does not contradict them. The description adds useful filtering context but does not discuss return ordering, pagination, or how the limit interacts with results.

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

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

The purpose is front-loaded in the first sentence, followed by the necessary status lists. The description is somewhat long, but the enumeration is largely justified because the status schema field has no enum of its own.

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 and rich annotations present, the description need not explain return values or safety behavior. Still, it is incomplete for one supported media type because manga status values are not provided.

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

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

Schema coverage is 100%, so the schema already documents all parameters at a baseline level. The description adds valuable status vocabulary beyond the schema, but it omits manga statuses even though 'manga' is a valid media_type in the enum.

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 items filtered by status. It makes the tool's filtering role clear, but it does not explicitly distinguish this tool from siblings such as get_by_rating or search_library.

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 how to use the status parameter, including per-media-type values and the special value 'all'. However, it does not state when to choose this tool over alternatives like get_by_rating, get_recently_added, or search_library.

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, and openWorldHint=false, so "Reads only their Achriom library" largely restates what structured data already says. The enumeration of returned values (counts, days-since-last-add, stage buckets) adds some useful context but shades into return-value documentation rather than behavioral disclosure; nothing is said about cost, caching, or failure modes for a sparse/empty library.

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 that names the action, the target, the intended use, and the payload. The parenthetical stage enumeration is dense but each element is load-bearing since no output schema exists.

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

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

With no output schema and no parameters, the description must explain what comes back, and it does: counts per media type, recency in days, a four-value stage classification, and taste signals. That is enough to call it correctly, though it leaves the agent unsure how this differs from get_stats or get_taste when choosing among siblings.

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 takes zero parameters, so the schema carries the full contract and there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly avoids inventing 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?

States a specific verb ("Summarise") and resource (the Achriom library) and enumerates what the summary contains: per-media-type counts, recency, a stage bucket, and taste signals. It is clear what the tool produces, but it does not distinguish itself from heavily overlapping siblings like get_stats, get_taste, get_taste_portrait, or get_signals, several of which sound like subsets of this output.

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?

"For pitching a conversation" gives a genuine usage context and implicitly suggests this is the lightweight pre-conversation overview. However, there is no explicit when-to-use versus get_stats (counts) or get_taste/get_taste_portrait (taste signals), so an agent must guess which of these overlapping read tools to pick.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower; the description still adds real context about what is returned (AI analysis, notes, ratings, timeline, track lists with durations, box-set album expansion). It doesn't mention cost/rate limits or payload size for large box sets, which keeps it below a 5.

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

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

Three short sentences, front-loaded with the core purpose and the scope qualifier before the per-media-type specifics. The capitalized emphasis (FULL, ALL) is slightly noisy but functional rather than 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 read-only detail fetch with a full-coverage schema and an output schema, this covers purpose, scope, and notable return shapes adequately. The only gap is routing versus the near-duplicate siblings (lookup_item, show_item), which the agent must resolve on its own.

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

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

Schema coverage is 100% and every parameter is documented in the schema, including the item_id-overrides-title precedence and the ambiguous-partial-match behavior, so the description needn't compensate. Beyond media-type-specific output shapes (albums, box sets), it adds no parameter semantics of its own.

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 ('Get FULL details of an item FROM THE USER'S COLLECTION') and scopes it to owned items, which separates it from search-type siblings. It does not distinguish itself from close neighbors like lookup_item or show_item, so an agent still has to guess among detail-oriented 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 closing sentence ('Use this to answer specific questions about items the user owns') gives a usage context, and 'FROM THE USER'S COLLECTION' implies a precondition the item must already exist. However, there is no explicit when-not guidance or named alternative for lookup_item, show_item, or search_library.

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 that this is a safe, idempotent read; the description adds useful behavior beyond that data, namely ordered item output and count aggregation. It omits edge cases like what happens with an unknown list name, but overall it adds real context.

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, front-loaded with the main action, zero wasted words; the two modes are stated in parallel and immediately scannable.

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

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

For a single optional-parameter read tool with no output schema, the description covers both modes and what each returns. It could say a bit more about missing-name behavior, but nothing essential for invocation is missing.

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

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

Schema coverage is 100% and the schema already explains that name is a list name omitted to see all lists; the description essentially restates this without adding format or matching semantics. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Show the user's lists') and splits the two modes precisely, making it easy to distinguish from mutation siblings like create_list, update_list, and delete_list. It doesn't explicitly name those siblings, so no full 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?

Gives clear conditional usage: supply a name to get that list's ordered items, omit it for all lists with counts. No exclusions or pointers to related read tools (search_library, get_details), which keeps it at 4.

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, closed-world, so the safety profile needs no repetition. The description contributes beyond that by disclosing sort direction and the exact returned fields (title, creator, media_type, status, rating, added date), which is meaningful behavioral context. It stops short of covering empty-result behavior or pagination beyond the schema's max limit.

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

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

Three tight sentences: core behavior and ordering first, then example invocations, then the sibling disambiguation and return shape. No filler, and the most decision-relevant fact (addition order) 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?

No output schema exists, and the description compensates by enumerating the returned fields. With only two optional, fully specified parameters and annotations covering safety, an agent has everything it needs to select and invoke this tool correctly.

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

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

Schema coverage is 100% and both parameters (limit with min/max/default, media_type enum with default) are fully documented in the schema. The description never mentions limit or media_type, so it adds no meaning over structured data; baseline 3 applies.

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

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

States a specific verb and resource plus the ordering dimension ('List items by when they were ADDED to the library, newest first'). It also names the sibling it differs from (get_timeline) and how the orderings diverge, so the agent can distinguish them without opening schemas.

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

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

Gives concrete trigger phrasings ('show me the last N things I added', 'my last 8 vinyl records') and an explicit exclusion: this is addition order, not reading/watching dates as in get_timeline. The when-to-use and when-to-prefer-alternative conditions are both 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?

Beyond the annotations, it discloses important behavior: recommendations come from aggregate other-library data, never an individual's list; they exclude items the user already has; and each pick includes an external_id ready for add_item. It also explains the rating/finished basis for unseeded picks, which is meaningful context for interpreting results.

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

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

The description is front-loaded, dense but efficient, and every sentence contributes: it defines the recommendation source, the no-argument behavior, the seeded behavior, exclusion rules, and the external_id handoff.

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 recommendation tool with no output schema, the description gives enough behavioral context to invoke it correctly and understand the main return fields. It could more fully describe the returned pick structure, but the essential recommendation logic and follow-up external_id are covered.

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 100%, so parameter documentation is strong. The description adds useful mode semantics for based_on and item_id as seed sources, though it does not discuss limit or media_type, which remain schema-documented.

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 resource and behavior: recommendations derived from overlapping taste across aggregated libraries. It clearly distinguishes the no-argument mode from seeded modes, so an agent can understand what the tool returns without opening the schema.

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

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

It explicitly explains the two usage modes: no arguments for broad picks, and based_on or item_id for seeded recommendations. It does not name alternative sibling tools or when-not-to-use cases, but the mode selection is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorldHint=false, so the safety profile is fully covered. The description adds nothing on top of that — no indication of cost, caching, or whether the scope can change between calls.

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 short, front-loaded sentence with no filler or redundancy. It is efficient but only because it omits content rather than because it is 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?

There is no output schema and no parameters, so the description carries the entire burden of explaining what a caller receives and what 'scope' means in this domain. It delivers none of that, leaving the agent unable to judge whether the response is worth a 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 tool takes zero parameters, and the input schema is empty with full coverage, so there is nothing for the description to clarify. Baseline 4 applies; no parameter-level information is missing.

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 sentence restates the title almost verbatim ('Get research scope' → 'Get information about the current research scope') without saying what 'research scope' contains or what kind of information is returned. It is generic enough that an agent cannot distinguish it from get_context or get_signals on the basis of 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?

No when-to-use condition, no exclusions, and no mention of the obvious sibling expand_research_scope, which is the mutating counterpart to this read. The agent is left to infer the intended trigger from the name.

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 cover safety (readOnly, idempotent, non-destructive, closed-world), so the description's marginal contribution is its disclosure of what comes back: a season-by-season breakdown plus an 'up next' episode. That is meaningful output-shape context beyond the structured fields, though it omits whether unwatched-only or all seasons are returned.

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

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

A single well-formed sentence with the resource and the two returned artifacts front-loaded. No filler, no restatement of the title, and every clause carries information.

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

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

With no output schema, the description does the necessary work of sketching the return value (season-level progress and the next unwatched episode). For a two-optional-parameter read tool with full schema coverage and strong annotations, that is close to sufficient; only the shape of the season breakdown is left vague.

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

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

Schema description coverage is 100%, so both title and item_id are already fully documented, including the ambiguous-partial-match candidate behavior and the id-precedence rule. The description adds nothing further about parameter interplay, so the baseline of 3 applies.

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

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

States a specific verb ('Read') and resource ('a TV show's season-by-season watch progress') plus a distinctive payload ('next unwatched episode / up next'). It implicitly separates itself from the mutating set_progress and from metadata-oriented get_details, though it never names those siblings 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?

Usage is only implied: the word 'Read' signals this is the non-mutating counterpart to set_progress, but there is no explicit 'use this when...' or pointer to get_details for metadata versus this tool for progress. An agent can infer the context but gets no stated exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered and the description adds no contradiction. What it does add is the content of the result (theme repetition, consumption gaps, recent activity), which matters because there is no output schema. It stops short of explaining how those signals are computed, how far back 'recent' reaches, or how large the payload might be.

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

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

A single sentence with no filler, and the resource type is front-loaded before the enumerated signal categories. Nothing could be removed without losing information.

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

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

For a zero-parameter read tool with no output schema, the key remaining job is describing what comes back, and the description does list three categories. But terms like 'theme repetition' and 'consumption gaps' are left undefined, and the tool's relationship to four similarly named taste/stats siblings is unaddressed, so the agent still cannot confidently choose or interpret 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The absence of any parameters is itself consistent with the description, which offers no scoping or filtering options.

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 ('Get') and a specific resource ('behavioral signals') and enumerates three concrete signal types: theme repetition, consumption gaps, recent activity. That is well beyond a restatement of the name. It does not, however, distinguish itself from close siblings like get_taste, get_taste_portrait, get_stats, or get_timeline, so an agent must guess which of these overlapping analytics tools 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: no condition that selects this tool over get_taste, get_taste_portrait, get_stats, or get_timeline, and no stated prerequisites. The description simply names what comes back, leaving the routing decision entirely to inference from sibling names.

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=false, so the safety profile is fully covered. The description adds the aggregation behavior (combined stats when media_type is omitted), which is genuinely useful, but the enumerated stat categories largely restate what the existing output schema likely documents.

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, no filler. The content list comes first and the default-behavior caveat follows, so the agent gets the essentials 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 one-parameter read tool with an output schema and full annotation coverage, the description supplies what an agent needs to call it correctly. Only the lack of sibling routing guidance keeps it short of 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 description coverage is 100% and the single parameter has an enum plus an inline "optional - omit for all" description. The description's note about combined stats when media_type is absent adds only slight meaning beyond what the schema already conveys.

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 (Get) and resource (collection statistics) and enumerates the stat categories returned: progress, rating distribution, genre/theme breakdown, timeline. It is clearly distinguishable from mutation siblings, though it does not explicitly separate itself from read siblings like get_timeline or get_by_rating whose names overlap with the listed stat types.

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?

"If no media_type specified, returns combined stats" gives a usable default-behavior hint, but there is no explicit guidance on when to use this aggregate tool versus per-dimension siblings such as get_by_rating, get_by_status, or get_timeline. Usage 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?

Annotations already declare readOnly/idempotent/non-destructive, so the added value here is "One call, no generation" — signalling a cheap precomputed read rather than an expensive synthesis step. It does not discuss size, latency, or what happens when no taste data 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?

Front-loaded with what you get back, then the usage trigger. The long enumeration of taste facets is dense but each item informs the agent what is available; still, it could be trimmed without loss.

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

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

No output schema exists, and the description compensates by enumerating the returned facets and the Taste Portrait essence, including the conditional "when they have one". An agent can decide and call correctly with nothing else 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?

Schema description coverage is 100% and there is a single optional enum-array parameter, so the schema carries full meaning. The phrase "across everything they read, watch, listen to and play" loosely echoes the media types but never references the media_types filter or its omit-for-all behavior.

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

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

Clear verb+resource (their taste) with an explicit content inventory — loved items, returning creators, genres, in-progress, finished, misses, plus Taste Portrait essence. That inventory implicitly separates it from get_taste_portrait and get_stats, though no sibling is named directly.

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?

"Use it whenever knowing their taste would make your answer fit them better, including outside media (a trip, a gift, a reading list for a project)" gives explicit positive triggers with concrete examples beyond the media domain. It lacks any when-not guidance or named alternatives such as get_taste_portrait or get_signals for narrower needs.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is free to add genuinely new behavior: a 10-item unlock threshold and the fact that below it the call returns a remaining-count instead of the portrait. That gating behavior is the single most useful thing an agent could know here and would be invisible otherwise.

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

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

Three sentences, front-loaded with the return contents, then the usage trigger, then the gating caveat. No restatement of the title and no filler; every sentence changes how an agent would call the 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?

With no parameters, no output schema, and safety already covered by annotations, the description supplies exactly the missing pieces: what comes back and what happens before the 10-item threshold. An agent has everything needed to decide whether to call it and to interpret a below-threshold response.

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 takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. Nothing in the description misleads about inputs, and the schema is trivially complete.

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

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

The description names a specific verb and resource ('Get the user's full Taste Portrait') and then enumerates the exact contents (archetype, essence, core tension, preoccupations, unowned recommendation, blind spot). It also explicitly distinguishes itself from the compact portrait already in context, so an agent can tell when this deeper call is the right one.

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?

'Call this to go deeper when they ask about their portrait' gives a concrete trigger, and the compact-in-context note implies the alternative for shallow needs. It stops short of naming a sibling tool or stating an explicit when-not condition, so the routing is clear but not fully spelled out.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds the useful behavioral dimension that the timeline shows both started and finished items over time, but it omits ordering, date-range behavior, granularity, and any pagination or return-shape details.

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. It is efficient, though the terse size contributes to gaps in behavioral and contextual detail.

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

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

There is no output schema and no annotations about return values, so the description must carry more weight for a timeline-query tool. It does not explain what the timeline actually contains, how started and finished items are represented, the time window, ordering, or granularity.

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

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

Schema description coverage is 100% and the single required parameter has a fully documented enum, so the schema does the parameter-level work. The description adds no syntax or meaning beyond the schema, which warrants the baseline score of 3.

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 ('Get') and resource ('timeline') and scopes it to 'items started and finished over time', which is distinct from siblings like get_recently_added or get_stats. It does not explicitly contrast with any sibling, which keeps it just below a 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?

The description says what the tool does but gives no indication of when to use it versus alternatives such as get_recently_added, get_show_progress, or get_stats. No exclusions, prerequisites, or alternative-selection guidance are present.

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 adds useful behavioral context beyond the annotations: previews are 30 seconds long, playable, and restricted to albums in the user's library. The annotations already cover read-only, idempotent, non-destructive, and closed-world behavior, so this additional detail is meaningful without needing to repeat safety traits.

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

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

The description is a single, front-loaded sentence with no wasted words. It immediately states the resource and scope.

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

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

Given the low complexity, rich annotations, full schema coverage, and presence of an output schema, the description is largely complete. The main remaining gap is the absence of explicit usage alternatives, but that is partly covered by the library scoping.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description reinforces that album_title must refer to an album in the user's library, but it adds no further parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb+resource: get playable 30-second audio previews for tracks from an album in the user's library. This clearly distinguishes it from general search, but it does not explicitly differentiate it from the sibling tool preview_album.

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 only usage constraint is that the album must be in the user's library, which is embedded as a scoping condition rather than guidance. There is no explicit when-to-use or when-not-to-use information, and no alternatives such as preview_album are mentioned.

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 and closed-world, so the safety profile is covered. The description adds meaningful context beyond that: the data provenance (chats with the Achriom librarian and save_insight) and an explicit boundary on what it does not read.

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 compact sentences: contents and provenance first, scope exclusion second. Every clause adds information and nothing is 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?

With no output schema, the description carries the burden of saying what comes back, and it does so by enumerating the profile's contents. The only real gap is a missing comparison against the other taste-related siblings.

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?

Zero parameters, so there is nothing for the description to disambiguate; the baseline applies. No misleading parameter hints are given.

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 (read) plus the resource and enumerates its contents: taste patterns, key facts, cross-media connections, preferences. However, it does not differentiate itself from the near-identical siblings get_taste and get_taste_portrait, which an agent must still disambiguate on its own.

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 scope caveat ('Achriom data only; does not read Claude's memory or history') implies when the tool is valid, but there is no explicit when-to-use guidance or routing to alternatives like get_taste, get_taste_portrait or get_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?

Annotations already declare the write, non-idempotent, non-destructive profile, so the bar is lower; the description still adds that records surface in history and stats, which is real effect information. It does not address duplicate logging or what happens if the same repeat is logged twice, which is the notable gap for a non-idempotent write.

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 zero waste: what it does, when to use it with examples, and how it relates to the status mechanism. The key distinction 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?

With full schema coverage, no output schema, and annotations covering the safety profile, the description supplies everything needed to decide and invoke. Minor omission: it does not say whether the title must already exist in the library or what happens on an unknown title, though the schema hints at candidate resolution.

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

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

Schema description coverage is 100%, so media_type, event_type, event_date, title, item_id, rating and notes are all already documented, including defaults and enums. The description only reinforces that a date accompanies the log; it adds no syntax or disambiguation beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Log a completion or a re-watch/re-read/re-listen with a date') and explicitly separates itself from status-based tracking: 'The first finish is tracked by status; this records repeats.' An agent can distinguish this from update_status or set_progress without opening any schema.

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

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

Gives an explicit trigger ('Use when the user mentions finishing something again') plus two concrete utterance examples, and an explicit exclusion rule (first finishes go through status). The when/when-not/alternative structure is fully present.

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, so safety is covered; the description adds genuinely new behavior: per-media-type provider routing and the TVDB→TMDB fallback. It does not cover failure modes or result counts, but an output schema exists. Note: the description's 'EXTERNAL databases' framing sits uneasily with openWorldHint=false — the annotation appears stale rather than the text being wrong, so this is not scored as a contradiction.

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

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

Front-loaded with the highest-value distinction (external vs owned) before the provider list. Four short sentences, each doing work, though the closing anime/show sentence is redundant with 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?

Return values are covered by the output schema, and routing plus alternatives are well explained. One real gap: the media_type enum includes podcast and manga, but neither appears in the data-sources list, so an agent gets no signal about where those are resolved.

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

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

Schema description coverage is 100% and each of the four parameters is documented in the schema, so baseline 3 applies. The description's only added parameter guidance ('use anime not show') is already duplicated verbatim in the media_type schema description, so it adds no new meaning.

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

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

States a specific verb+resource (search external databases to find items) with an explicit scope contrast: external sources, NOT the user's collection. It then enumerates the exact provider per media type (OpenLibrary, TMDB, TVDB, Discogs, AniList, IGDB), which makes it unmistakable versus siblings like search and get_details.

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

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

Gives explicit timing ('BEFORE adding them') and names the alternative for the opposite case ('Use search/get_details for items the user already owns'). It also resolves the one enum ambiguity that would cause a miscall: anime vs show for Japanese animation.

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 the tool is not read-only, is idempotent, and is destructive. The description adds useful behavioral context by explaining that omitting season/episode marks the whole show and that watched=false unmarks. It does not add permission, error, or side-effect detail beyond the scope 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 a single compact paragraph with the core action front-loaded and each sentence carrying a distinct scope rule. There is no redundant restatement of the name or title.

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 mutation tool with rich schema descriptions and annotations, the description supplies the essential invocation matrix for episodes, seasons, whole shows, and unmarking. Schema details cover title ambiguity, item_id addressing, and parameter formats, so no critical gap remains.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining parameter combinations: season+episode targets one episode, through extends that to everything up to it, season alone marks a whole season, and neither marks the whole show.

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: marking TV progress at episode, season, whole-show, or unmark scope. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as set_progress or get_show_progress.

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

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

It gives clear invocation guidance for each scope: season+episode, through=true, season only, neither, and watched=false. It does not mention when to prefer or avoid this tool versus alternative progress-related siblings.

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

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

Adds real context beyond the annotations: it confirms no library mutation occurs and that results are 30-second playable previews, which the annotation set alone doesn't convey. Minor tension: 'any album from Apple Music' implies querying an external catalog while openWorldHint=false declares a closed domain, though the read-only/idempotent semantics are consistent.

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, no filler, and the critical constraint (no library side effect) is placed immediately after the purpose. Every clause 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-shape explanation is unnecessary, and the description covers the two things an agent most needs: no library mutation and the nature of the returned previews. For a 3-parameter read-only lookup with full schema coverage, nothing essential is missing.

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

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

Schema description coverage is 100%, so title, artist, and max_tracks are already documented with defaults in the schema. The description adds no format guidance (e.g., exact-match vs fuzzy artist names, what happens when title is ambiguous), so the baseline 3 applies.

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

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

Specific verb ('Preview') plus resource ('any album from Apple Music'), and it distinguishes itself from the library-mutation siblings by stating 'WITHOUT adding to library'. It does not, however, differentiate itself from the closely related 'get_track_previews' sibling, so an agent cannot fully tell the two apart 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?

'Use this to sample before committing to add' gives a clear situational trigger, effectively routing agents away from add_item/add_to_list for exploratory browsing. It stops short of naming an explicit alternative or a when-not condition (e.g., versus get_track_previews for track-level sampling).

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 says the tool picks random item(s), but the annotations declare idempotentHint=true. Random selection implies repeated calls may return different results, directly contradicting the idempotency claim.

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. The core action is stated first, and the phrase 'for serendipitous discovery' adds intended use without bloating the 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?

The tool is simple and the schema fully documents all parameters, so the description provides enough context to understand the basic action. Still, it does not clarify when to choose this over sibling discovery/recommendation tools, and it leaves the idempotency contradiction unaddressed.

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

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

Schema description coverage is 100%, so media_type, count, and filter are already well documented in the schema. The description adds no parameter-level meaning beyond the schema, which is acceptable as a baseline 3.

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

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

The description states a clear verb and resource: 'Pick random item(s)'. It conveys the distinctive random-selection behavior, but it does not explicitly differentiate itself from siblings like get_recommendations or search.

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 phrase 'for serendipitous discovery' implies when the tool might be used. However, it gives no explicit when-not conditions and does not name alternatives such as search or get_recommendations.

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=false, so the safety profile is fully covered and the description need not repeat it. The description adds only that the book must already be uploaded and that addressing is line-based; it says nothing about behavior on out-of-range line numbers, truncation, or return format, which is acceptable only because the annotations lower the bar.

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 no filler, and the key qualifier ('by line numbers') is front-loaded. It is perhaps too short given the sibling ambiguity, but nothing in it 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 simple read-only tool with full annotation coverage and a fully described three-parameter schema, the description supplies what is structurally missing: the concept of an already-uploaded book and line-range addressing. The remaining gap is routing guidance against search_book_content, which keeps it below a 5.

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

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

Schema description coverage is 100%: book_title (partial match), start_line, and end_line (max 200 lines) are all documented in the schema itself. The description confirms that start/end are line numbers but adds no format, ordering, or bounds information beyond what the schema provides, so the baseline of 3 applies.

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

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

Names a specific verb (read) and resource (a specific section of an uploaded book) plus the addressing mechanism (line numbers), so the operation is unambiguous. However, it never distinguishes itself from the close sibling search_book_content, which also reads book content, leaving the agent to infer the difference.

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 phrase 'by line numbers' implicitly signals that this is positional reading rather than content search, which is the key differentiator against search_book_content. But there is no explicit when-to-use/when-not-to-use statement, no note that you need line numbers in hand, and no mention of the alternative tool by name.

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 value beyond annotations: it discloses that the lookup is re-run unchanged and will yield the same result, which prevents a wasted retry loop. However, annotations declare destructiveHint=true and idempotentHint=false, and the description never mentions that a refresh can overwrite existing or already-corrected metadata — the destructive aspect is undisclosed. The 'same result as before' framing also sits awkwardly against idempotentHint=false, though not enough to be a contradiction.

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

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

Three sentences, front-loaded with what it does, then the caveat, then the redirect. Efficient overall; the last sentence runs long by carrying both the alternative and the rationale.

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

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

No output schema and only 3 simple params, so the description carries the semantic burden well, including ambiguous-match behavior and the relink path. The one omission an agent operating under destructiveHint=true would want — what existing data gets overwritten — is unaddressed.

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

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

Schema description coverage is 100%, so title vs item_id precedence and the candidate-on-ambiguous-match behavior are already fully documented in the schema. The description adds no further parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource (re-fetch metadata from external sources) plus the exact condition (item data incomplete), and explicitly contrasts itself with edit_item. An agent can separate it from the ~56 siblings without opening a schema.

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

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

Gives when-to-use (incomplete data), an explicit when-not (it does NOT fix a wrong match), and names the correct alternative with the exact tool and parameter (edit_item with new_external_id). This is the strongest kind of 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 only declare non-readOnly/non-destructive/non-idempotent; the description adds real behavior the agent can't infer — that the call may resolve an existing library title or create one, and that it sets happened/date/rating in a single call. It also prescribes a confirmation step after saving. It does not warn about duplicate risk given idempotentHint=false, which leaves one meaningful gap.

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

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

Front-loaded with the action and its scope, then examples, then the exclusion, then the follow-up. The example list is long but each example disambiguates a different 'happened' value, so they earn their place; the single run-on sentence carrying the workflow is the main readability cost.

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 10-parameter, non-idempotent mutation with no output schema, the description covers what the tool does, the resolution-or-create workflow, scope boundaries, and post-call behavior — enough to invoke it correctly. Missing only edge-case guidance such as re-logging the same title twice.

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

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

Schema coverage is 100%, so baseline 3; the description adds semantic meaning beyond the schema by describing the resolution order (title or item_id against their library, then set what happened/date/rating) and by tying the example phrasings to which fields they populate ('loved it' → no numeric rating).

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 (save) and a specific resource (the person's own reading/watching/listening/playing activity), and backs it with five concrete utterance examples that make the scope unmistakable. The phrase 'the person's own activity, not titles you are only discussing or recommending' cleanly separates it from add_item/log_event siblings.

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

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

Explicitly gives a when-not-to-use rule ('not for titles you are only discussing or recommending') and frames the trigger as 'something the person just told you'. It stops short of naming the nearest alternatives (log_event, add_item, bulk_log_events), which is the only gap.

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 safety semantics are covered. The description adds genuinely non-obvious information beyond that: removal affects only list membership while the item remains in the library — critical context an agent would otherwise have to infer. It does not describe behavior when the item is not found, which keeps it below a 5.

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

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

Two short sentences, front-loaded with the action and followed by the key scoping constraint. No redundant restatement of the tool name or schema fields.

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 fully documented schema and annotations carrying the destructive/idempotent profile, the description only needs to add the non-obvious scope distinction, which it does. A brief note on no-match behavior would make it fully complete.

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

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

With 100% schema description coverage, the schema already documents each parameter including the rule that item_id causes title to be ignored. The description restates the title vs. media_type+item_id pairing but adds no syntax, format, or edge-case detail beyond what the schema provides.

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

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

States the specific verb and resource ('Remove an item from a list') and immediately clarifies scope with 'The item stays in the library,' which distinguishes it from destructive siblings like delete_item. It does not name the inverse sibling (add_to_list) or contrast with delete_list/update_list, so it falls just short of full sibling differentiation.

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

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

The description explains the two lookup modes (by title, or exactly by media_type + item_id), which is useful selection guidance for parameters. However it never states when to use this tool versus alternatives such as delete_item or update_list, and 'the item stays in the library' only implies the distinction rather than spelling it out.

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

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

Annotations already declare the write semantics (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower. The description adds real value beyond them: it names the read-back path (get_user_profile), clarifies that each call stores exactly one insight, and imposes a consent requirement. It does not say what happens when the same insight is saved twice, which matters given idempotentHint=false.

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, both earning their place: the first establishes the action, target store, valid content types, and read path; the second establishes the consent gate. Nothing is redundant and the essential scoping information 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?

For a two-parameter write tool with full schema coverage and no output schema, the description covers the action, destination, read path, one-insight-per-call granularity, and the consent rule. The only meaningful gap is the lack of guidance relative to the overlapping 'remember' sibling and duplicate handling.

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

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

Schema description coverage is 100% and the category enum is fully documented with per-value meaning, so the schema carries the load and a 3 is the baseline. The description restates the four categories in prose but adds no format, length, or example guidance beyond what the schema already provides.

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

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

The description uses a specific verb and destination ('Save one insight to the user's Achriom taste profile') and enumerates exactly what qualifies as an insight, plus names the sibling that reads it back (get_user_profile). It loses a point because it never distinguishes itself from the sibling tool 'remember', which an agent could reasonably confuse with this one.

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

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

It gives an explicit trigger and an explicit prohibition: use only when the user asks you to remember or agrees to an offer, and 'do not save things they have not chosen to keep.' That is stronger than most definitions. However, it offers no guidance on choosing between this and the sibling 'remember' tool, leaving the main ambiguity unresolved.

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 cover readOnly, idempotent, non-destructive, and closed-world. The description adds critical context the annotations cannot: literal-only matching, empty result on wording mismatch, and that box sets expand to contained albums. The one gap is pagination/result-limit behavior, but overall it substantially enriches the 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?

Opens with the core scope, then the critical matching constraint, then the return summary, then the alternative-tool routing. Every sentence is load-bearing and front-loaded; no filler.

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

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

With an output schema already present, the description only needs matching semantics and alternatives — both are covered. An agent has everything needed to decide between `search` and `search_library` and to set expectations on empty results.

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

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

Schema description coverage is 100%, so all three parameters (query, filter, media_type) are already documented. The description restates the searchable fields (title/creator/genre/theme) but adds no syntax, escaping, or filter details beyond the schema, which is the expected baseline here.

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 with scope ('USER'S COLLECTION') and names the sibling it differs from (`search_library`). An agent can tell instantly this is literal keyword search over owned items, not semantic search or item 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?

Explicitly says when to use this ('questions about what the user has') and when not to, with concrete examples ('something about grief', 'a film podcast') routing to `search_library`. Every condition is stated, nothing inferred.

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, closed-world and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior — matching is embedding-based/semantic rather than keyword — but says nothing about result format, ranking, or what happens when the title doesn't match.

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 zero waste: the resource and scope come first, the mechanism second. Nothing could be cut without losing information.

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

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

Adequate for a 3-parameter read tool with no output schema, but it omits what a result looks like (passages only, or with page/chapter locations) and the failure mode when no book matches the title — both relevant to calling it correctly.

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

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

Schema description coverage is 100%, including the partial-match behavior of book_title and the limit default/max, so the schema carries the parameter burden. The description adds no syntax or format guidance beyond that 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+resource ('Semantic search within an uploaded book') and constrains scope to EPUB/PDF content, which implicitly separates it from library-wide siblings like search_library and search. It never names an alternative tool, so an agent must infer the boundary itself.

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 'within an uploaded book' — use when you already know the book and want passages. But there is no explicit when/when-not, no mention of read_book_section as the alternative for reading a known section, and no prerequisite note that the book must already be uploaded.

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 and closed-world, so the safety profile is covered. The description adds a real behavioral trait beyond that — retrieval is semantic ('by meaning as well as keywords') — but says nothing about result ordering, whether older chats are truncated, or how the limit interacts with ranking.

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, front-loaded with the resource and scope, and the second sentence earns its place by eliminating a costly misidentification with other assistants' history. No filler.

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

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

For a two-parameter read-only search with full schema coverage, the definition is nearly complete. Without an output schema, a brief note on what a result contains (the matched message plus context, excerpt length) would close the last 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?

Schema description coverage is 100%, with both query and limit documented in the schema itself, so the baseline is 3. The description contributes no additional detail on how the query is interpreted semantically or what the default of 5 means for ranking breadth.

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 (search) and resource (the user's past chats with the Achriom librarian) and bounds it by source. However it does not distinguish itself from the many search_* siblings (search, search_library, search_book_content, search_youtube) present in the toolset, leaving that ambiguity unresolved.

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 only implied by the scope statement: it applies to Achriom librarian chat history, not Claude's or other assistants'. The negative scoping is genuinely useful, but no positive when-to-use condition or named alternative is given for the other search-family tools.

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, closed-world behavior. The description adds meaningful behavioral context beyond that: search is semantic rather than literal, spans every media type as one corpus, and is intended for conceptual queries where exact wording may not appear. It does not describe result ordering or pagination, but the schema covers the limit and similarity floor.

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

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

The description is three tight sentences with no waste. The scope and primary use case are front-loaded, followed immediately by the sibling distinction.

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 semantic search tool with full schema coverage and no output schema, this description contains everything needed to select and invoke it correctly: purpose, corpus scope, query style, examples, similarity tuning context in the schema, and the alternative keyword tool.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description illustrates the kind of natural-language query to pass but does not add syntax, format, or parameter-specific guidance beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: semantic search across the user's entire library by meaning, theme, or vibe. It distinguishes this from the sibling `search` tool by explicitly contrasting meaning-based search with keyword lookups.

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

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

It gives explicit usage guidance with examples such as "things about grief" and "noir mood", and it names the alternative for specific title/creator lookups: the keyword `search` tool. The conditions for choosing this tool versus that sibling are clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered structurally. The description adds only the content-type examples as behavioral context; it says nothing about external network calls, result ranking, quotas, or latency. Note the annotation openWorldHint=false is questionable for what is intrinsically an open web search, but that is an annotation defect rather than a description contradiction.

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

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

A single sentence with the verb and resource front-loaded and no filler. The parenthetical examples earn their place by scoping the content domain, though the whole description is arguably thinner than the tool's role warrants.

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 annotations cover the safety profile for a two-parameter tool. What is missing is the disambiguation from the many other search-flavored siblings, which is the main thing an agent needs before invoking this one.

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

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

Schema description coverage is 100%, so both `query` and `max_results` (including the 1-5 range and default 3) are already fully documented in the schema. The description adds no query-syntax guidance (e.g., channel filters, quoting) and no semantics for what counts as a 'relevant' video, so baseline 3 applies.

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

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

Specific verb (Search) plus resource (YouTube) with parenthetical examples of expected content types (interviews, trailers, analysis, music videos), which clarifies it is a video-content search rather than a generic one. It is distinguishable from search_library and search_conversations by the YouTube resource, though it never explicitly contrasts itself with the bare `search` sibling.

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

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

The description states no when-to-use or when-not-to-use conditions and names no alternative. With siblings like `search`, `search_library`, and `search_conversations` present, an agent gets no signal about why it would pick YouTube search over those, leaving routing to inference from the name alone.

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 safety profile is known. The description adds useful format behavior (year-only values preserved rather than normalized to January 1st) but never warns that setting a date overwrites existing values or what happens to fields left out of the call — the main destructive risk an agent needs flagged.

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 the affected fields front-loaded and the format/clear semantics immediately after. No filler and nothing buried.

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 6-parameter mutation tool with no output schema, the description covers the fields, accepted formats, and clearing behavior well. The remaining gap is what a call does to dates not mentioned in it and how item identification resolves between title and item_id, which leaves slight ambiguity about the write's scope.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning beyond the schema: it restates the accepted formats in one place and clarifies the non-obvious semantic that a year-only finish stays a year rather than becoming January 1st. Minor gap: it says nothing about title vs item_id selection, though the schema covers that.

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 (set or clear), a specific resource (dates on one library item), and enumerates the three fields affected. An agent can distinguish it from siblings like set_progress, set_format, or update_status without reading any schema.

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

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

Gives two explicit use cases: imported histories that only carry years, and correcting a wrong date. That is clear positive guidance but it never names an alternative tool (e.g., set_progress for current reading position) or states 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 destructiveHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds genuinely new behavioral context: it is a two-way toggle (not just a set) and it will lazily create the favorites list when the user has none — a side effect the annotations do not reveal. It stops short of explaining why the call is flagged destructive or what happens if the item isn't found.

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, front-loaded with the action and scope, with the side effect in the second. The parenthetical UI hint is short and aids disambiguation 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?

For a 4-parameter mutation with no output schema and rich annotations, the description plus schema covers nearly everything an agent needs: the toggle semantics, identifier precedence, and the list-creation side effect. Minor gaps: no statement about failure modes (unknown title, ambiguous match) or what the response confirms.

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

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

Schema description coverage is 100%, including the title-vs-item_id precedence rule and the boolean's meaning, so the schema carries the weight. The description only reinforces that the boolean is bidirectional; it adds no format, casing, or resolution guidance beyond the schema — the baseline 3.

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 pair (mark/unmark) and a specific resource (one library item), plus a UI anchor ("the heart in the app"). The word "one" implicitly distinguishes it from the sibling set_profile_favorites, but that sibling is never named, so differentiation is left to inference.

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 only implied: the agent can infer this is the per-item toggle vs. a bulk/list operation like set_profile_favorites or bulk_add_items, but no alternative is named and no when/when-not condition is stated. Nothing tells the agent which identifier path (title vs item_id) is preferred at the description level.

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 destructiveHint=true and idempotentHint=true already declared, the description adds real context: formats and stores replace the saved lists rather than augmenting them, and an empty list clears them. It does not state that omitted fields are left untouched, which would be useful for a partial-update 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?

Front-loaded with the core purpose, then the per-type detail. It is a single dense paragraph, and the long enumerations are justified because the schema references them, though the store lists run heavy.

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?

Eight optional params at full schema coverage, no output schema needed, and the description supplies the value vocabularies plus the replace-vs-clear semantics an agent 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 100%, so baseline is 3, but the description goes further by enumerating the accepted format and store values per media type — values the schema itself defers to ("from the lists above"), making the description load-bearing.

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: record how the user has/consumes an item, broken out per media type. It is clearly distinct from siblings like update_status or set_dates, though it never names the neighboring edit tool it overlaps with.

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 the per-media-type breakdown, and it explains that formats/stores replace existing lists while an empty list clears them. However, it never says when to use this versus edit_item or add_item, nor which media_type to pick when ambiguous.

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 idempotent=true, destructive=false and openWorld=true; the description adds the genuinely useful fact that 'It stays in their library either way', clarifying the change is visibility-only and reversible rather than a delete. It does not discuss permission requirements or how the public page is re-rendered, which are minor given the 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?

Two short sentences, no filler, and the primary action with its boolean value is front-loaded. The second sentence adds only the non-obvious reassurance about library retention.

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 four fully documented parameters, rich annotations, and no output schema, the description covers what an agent needs: what changes, what persists, and implicitly the single-item scope. It could add one clause about what to do when a title is ambiguous, though the schema already directs agents to item_id.

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

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

Schema description coverage is 100%, so media_type, title, item_id and hidden are all documented in the schema, including the item_id-over-title precedence rule. The description only reinforces the meaning of `hidden` in plain language; baseline 3 applies since the schema carries the load.

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 effect ('Leave one item off the user's public page') plus the inverse ('let it show again'), so the toggle semantics are unambiguous. It implicitly separates itself from set_favorite/set_priority by scoping to public-page visibility, but never names a sibling to confirm that distinction.

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?

'Leave one item off... (hidden = true), or let it show again (false)' implies both directions of use, and 'one item' signals this is the single-item path rather than a bulk operation. There is no explicit when-not guidance and no named alternative for multi-item changes, so usage remains inferred.

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, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the semantic meaning of the priority tiers but says nothing about what happens to the prior priority value, whether the item must already exist, or permission requirements — modest added value against an already-rich annotation set.

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 compact sentences: the action first, then the tier definitions. Nothing is wasted and the core operation 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?

With full schema coverage, published annotations, and no output schema, the description covers the essentials for a simple attribute-setter. The one gap is that it never mentions how the target item is identified (exact title vs item_id, and how ambiguity is handled) — though the schema descriptions do carry that detail.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully enriches the 'priority' enum: the schema only says 'Priority level' while the description defines high as 'want this next', normal as 'standard backlog', and low as 'speculative or distant'. That is genuine semantic value beyond the structured fields.

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 ('Set') and resource ('priority of an item in the collection'), which is unambiguous and readily separable from siblings like set_favorite, set_progress, or update_status that touch other attributes. It does not explicitly name or contrast a sibling, but the resource is distinct enough that no confusion arises.

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 explains what each priority level means, which implies usage ('high = want this next'), but it never states when to call this tool versus alternatives such as update_status or set_favorite, nor any prerequisites. Usage is inferable but not spelled out.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is known. The description earns credit by spelling out exactly what the destruction looks like — full replacement of the prior selection, with an empty list as the clear operation — which is the key behavioral detail an agent needs. It stops short of permissions or per-item failure 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?

Two sentences, both front-loaded with the operation and then the replacement/clearing semantics. No filler and no duplication of enum values or schema details.

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 write tool with full schema coverage, no output schema, and annotations carrying the safety profile, this covers scope, limit, ordering, sourcing and replacement behavior adequately. What's missing is sibling disambiguation against set_favorite and whether media_type must already have library items.

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

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

Schema coverage is 100% and the schema already documents the 4-item cap, first-to-last ordering, the titles-vs-item_ids choice, and the media_type enum. The description mostly restates those facts; only 'from their own library' adds a constraint the schema does not encode, so the baseline 3 is appropriate.

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

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

The description gives a specific verb ('Choose') and a precisely scoped resource ('the favorites shown for one media type on the user's public page'), plus ordering, a 4-item cap and library sourcing. It implicitly separates itself from the near-namesake set_favorite by emphasizing the public-page, per-media-type, ordered, multi-item nature, but it never names that sibling outright.

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?

Useful in-tool guidance is present: it replaces the current choice and an empty list clears it, so the agent knows this is a whole-set write, not an additive one. However, with a sibling literally named set_favorite, the absence of any 'use set_favorite for a single favorite instead' routing is a real gap for tool selection.

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 destructiveHint=true and idempotentHint=true, so the safety profile is partly covered structurally. The description, however, never discloses that existing progress is overwritten or that null clears values, and gives no return-value information for a mutation with 11 params. It adds the per-format field mapping but not the destructive consequences.

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

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

Three tight sentences, front-loaded with the core action and followed by an efficient per-format breakdown. No filler, though the bullet-like enumeration is dense relative to the schema it duplicates.

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?

Covers which fields apply to which media type, which is the main complexity, but for a destructive 11-param mutation with no output schema it omits overwrite semantics, partial-update behavior, and the item_id-vs-title resolution path. Adequate rather than complete.

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

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

Schema coverage is 100%, so every parameter is already documented, including media-specific scoping and null-clearing. The description largely restates that mapping (books → page/percentage, shows → season+episode) without adding syntax, precedence between title and item_id, or cross-field constraints. Baseline 3 applies.

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

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

States a specific verb and resource ('Update how far the user is through an in-progress item') and enumerates the per-media-type progress fields, so the operation is unambiguous. It does not differentiate itself from plausible siblings such as mark_tv_watched or update_status, which keeps it from a 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?

'in-progress item' implies usage, and the media-type breakdown hints at applicability, but there is no explicit when-to-use guidance, no exclusions, and no routing to alternatives like mark_tv_watched or get_show_progress for shows/anime.

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

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

Beyond the annotations (non-readonly, idempotent replace, potentially destructive), it discloses the default-private posture and that public reviews go through a 'community check' before appearing on the user's page and the title's page. That moderation consequence is real context an agent can't get from the flags; the nature or latency of that check is left vague.

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, front-loaded with the operation, then the safety-relevant default, then the pointer to the sibling. No filler or restatement of the name.

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 6-parameter mutation with full schema coverage and no output schema, the description covers the operation, the replace semantics, and the risky visibility choice. It leaves the 'community check' undefined and says nothing about failure modes, which is a minor but noticeable 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?

Schema coverage is 100%, so the baseline is 3, but the description earns an extra point by explaining the consequence of the visibility enum (public page + title page after community check) rather than just repeating 'Defaults to private'. Other parameters (spoiler, item_id, media_type) are left entirely 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?

The description uses a specific verb+resource ('Write or replace the user's review') and bounds the scope to 'something they have finished', which separates it from delete_review and from the logging siblings. An agent can identify the operation without opening the schema.

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

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

It gives an explicit visibility decision rule ('Only make it public when the user asks') and points to update_notes for private jottings, which is a genuine alternative. It stops short of contrasting with update_rating or log_event, so the sibling routing is only partly covered.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, so the bar is lower, but the description still adds real value: it discloses the return value (a link to the item page) and the conditional side effect of opening the item in the app. It does not cover failure behavior when an item is missing, which limits it to a 4.

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, front-loaded with the action, followed by the trigger condition and the return value. Nothing redundant.

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

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

There is no output schema, and the description fills that gap by explaining what the caller gets back (a link, plus direct opening when the app is the client). Combined with 100% schema coverage on the three parameters, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3; the id/title precedence and ambiguous-match behavior are fully documented in the schema itself. The description adds nothing about parameters beyond 'one item', which is adequate since the schema does the work.

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 — 'Open one item from the user's library in Achriom' — which is unambiguous. It does not explicitly contrast with close siblings like get_details or lookup_item, so an agent must infer the difference, keeping it below a 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?

'Use when they ask to see, open, go to or pull up an item' gives concrete triggering user phrasings, which is strong positive guidance. No exclusions or alternatives (e.g. when to prefer get_details instead) are offered, 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 already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, but the description adds meaningful behavior beyond them: public list names/descriptions are checked before publication, and clearing is possible. It does not cover failure modes or response behavior, so it stops short of 5.

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

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

Front-loaded and appropriately sized: every clause identifies a capability or constraint, with no filler. The single long sentence is dense but readable; bullet structure would help marginally but is not required.

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 parameters, a nested item object, no output schema, and rich annotations, the description covers the mutation surface, visibility semantics, and public-page check. Minor gaps such as name-collision behavior or return details keep it from 5.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning by explaining the visibility enum distinction (link = anyone with the share link, public = also on the user's public page). Nested item fields such as title/item_id remain schema-only, keeping it at 4.

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 a specific verb and resource ('Change a list') and enumerates exactly what can be edited: name, description, visibility, and one entry's note/position. This clearly scopes it apart from create_list, delete_list, and add_to_list, though it does not explicitly name those siblings.

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

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

Gives a clear usage constraint: 'Only change visibility when the user asks.' It also implies the tool is for existing lists and existing entries, but does not name alternative tools for adding entries or editing notes elsewhere.

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