Achriom

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

Annotations declare write operation (readOnlyHint=false) and external system interaction (openWorldHint=true). Description adds workflow context implying external dependency ('external_id', 'lookup_item'). Could explicitly mention non-idempotent nature (idempotentHint=false) but aligns with creation semantics.

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

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

Three sentences, zero waste. Front-loaded with purpose ('Add a new item'), followed by workflow guidance, then critical domain rule. Each sentence serves distinct function: purpose, prerequisite, classification.

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?

Mutation tool with good annotation coverage. Prerequisites (lookup_item) and domain constraints (anime classification) included. No output schema exists but description adequately covers input requirements and workflow for a creation 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 coverage is 100% so baseline is 3. Description adds critical semantic clarification for media_type parameter ('anime... for ALL Japanese animation including series, movies, OVAs'), which is domain logic not present in schema enum descriptions.

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

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

States specific verb ('Add'), resource ('item'), and destination ('to the library'). Clearly distinguishes from sibling tools like edit_item, delete_item (mutation vs update/removal), and lookup_item (creation vs 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?

Explicitly names sibling tool 'lookup_item' as prerequisite ('use lookup_item first'). Provides clear when-to-use guidance for media_type enum values ('Use anime... for ALL Japanese animation'), preventing misclassification errors.

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?

Mentions 'at once' implying batch/atomic behavior, but fails to disclose critical behavioral traits signaled by annotations (idempotentHint:false) such as retry safety, nor does it explain what happens when the optional 'filter' parameter is omitted. No contradiction with annotations.

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

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

Extremely brief (6 words) with zero filler, earning a high score for efficiency. However, 'appropriately sized' is questionable for a bulk mutation tool with complex filtering options; it borders on under-specification rather than conciseness.

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

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

Adequate for identification but incomplete for safe invocation. Lacks explanation of valid 'status' values, default behavior for the optional 'filter' parameter, and handling of partial failures in the bulk operation. Annotations provide safety context, but description should elaborate on the filter logic.

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%, establishing a baseline of 3. The description adds no parameter-specific context (e.g., valid status strings, filter default behavior), but does not need to compensate for missing schema documentation.

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

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

States a specific verb ('Update') and resource ('status'), and clearly indicates bulk scope ('for multiple items at once'). This distinguishes it from the singular sibling 'update_status', though it could be more explicit by mentioning 'media' items given the schema context.

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?

Provides no guidance on when to use this bulk tool versus the singular 'update_status', nor does it mention prerequisites or when to use specific filter values ('all' vs 'unrated'). The agent must infer usage from the parameter names 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 declare destructiveHint=true and idempotentHint=false, but the description adds no context about recoverability, side effects on related data (ratings, notes from sibling tools), or the partial match behavior mentioned in the schema. Fails to elaborate on what 'delete' entails beyond the annotation.

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?

Extremely concise at six words. Front-loaded with action verb and target resource. Efficient structure but arguably insufficiently elaborated for a destructive operation requiring two specific parameters.

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?

Inadequate for a destructive mutation tool with no output schema. Missing critical context: permanence warnings, error conditions (item not found), interaction with related records (ratings/notes), and confirmation requirements. Description meets only the bare minimum definition.

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

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

Schema coverage is 100% with detailed parameter descriptions including the partial match capability for titles. Description adds no param-specific guidance, meeting baseline expectations when schema documentation is comprehensive.

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 'Delete' and resource 'item from the library'. The schema clarifies specific media types (book, movie, etc.), though the description could explicitly mention these to distinguish from generic 'items' in sibling tools like edit_item or lookup_item.

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?

Provides no guidance on when to use this versus edit_item or update_status, and lacks critical warnings about permanent deletion despite the destructiveHint=true annotation. No mention of prerequisites (e.g., should user confirm item exists first?).

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

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

Adds critical workflow context not in annotations: changing external_id requires a subsequent re_enrich call to populate metadata, explaining the two-step process. Annotations mark it as non-read-only and non-destructive, which the description's 're-link' language supports without contradicting.

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 efficient sentences. First establishes scope; second provides specific usage pattern for external ID with named follow-up action. No wasted words or redundant explanations of schema mechanics.

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?

While it covers the re_enrich workflow well, it misses explaining the lookup-vs-update parameter pattern (identifying items by current title while updating via new_* fields), which is critical given the schema structure. No output schema exists, but description appropriately doesn't speculate on returns.

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, baseline is 3. Description adds conceptual grouping ('metadata') and explains the specific semantics of new_external_id ('re-link to correct database entry') and its relationship to re_enrich, adding value beyond the schema's individual field descriptions.

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

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

Specific verb 'Edit' with explicit resource 'metadata' and enumerated fields (title, creator, external ID). Effectively distinguishes from siblings like update_rating, update_status, or delete_item by scope and mentions unique re_enrich workflow.

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?

Provides explicit workflow guidance: use new_external_id to 're-link,' then call re_enrich. This identifies when to use the tool (re-linking scenarios) and names a specific sibling as the next step. Could improve by contrasting explicitly against other update_* 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?

No annotation contradictions. The description adds the critical behavioral trait that this only works in 'focused research mode,' which is not captured in the annotations. However, it omits details about what happens if the item already exists (relevant given idempotentHint=false) or failure modes.

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?

Single sentence, front-loaded with the action verb. Every word earns its place: 'Add' (action), 'item' (object), 'research corpus' (target), and the parenthetical constraint provides essential context without bloating. No redundancy.

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

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

Appropriate for a simple 2-parameter mutation tool with clear annotations. The description covers the mode restriction adequately. However, given the existence of sibling 'add_item', the description could better clarify corpus scope versus general item addition to achieve completeness.

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 fully documents both parameters ('title' and 'media_type'). The description provides no additional parameter semantics beyond the schema, warranting 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?

Clear verb ('Add') and specific resource ('current research corpus'). The parenthetical '(focused research mode only)' distinguishes this from generic add operations, implicitly differentiating it from sibling 'add_item' by specifying the research corpus context, though it could explicitly name the sibling alternative.

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

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

Provides a usage constraint '(focused research mode only)' which implies when to use it, but lacks explicit guidance on when NOT to use it versus alternatives like 'add_item'. The constraint is present but stops short of full comparative 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 declare readOnlyHint=true and destructiveHint=false, establishing safe read behavior. Description adds minimal value beyond this, noting 'user rating' (clarifying personal vs. external ratings) but omits return structure, pagination, or cost 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?

Six-word sentence is maximally concise with no redundancy. Front-loaded with action verb 'Get' followed immediately by filter criteria. Zero wasted words.

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

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

Tool is relatively simple with comprehensive annotations and schema coverage, but lacks output schema. Description omits return value structure and doesn't clarify relationship with 22 sibling tools, leaving gaps in operational context.

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

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

With 100% schema description coverage, the schema fully documents all three parameters (media_type, min_rating, max_rating). The description mentions 'rating range' which loosely maps to the min/max parameters but adds no syntax, format, or dependency details beyond the schema.

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

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

States specific verb (Get), resource (items), and filter mechanism (user rating range). Implies media domain via 'rating' context but does not explicitly distinguish from sibling tools like 'get_by_status' 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?

Provides implied usage context by specifying the filtering criterion (rating range), but lacks explicit guidance on when to prefer this over 'search' or 'lookup_item', and does not mention prerequisites like requiring 'media_type'.

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 readOnly/idempotent/destructive hints, so the description focuses on adding domain-specific constraints: valid status strings per media type. This behavioral context (what values are accepted) is critical for successful invocation and not present in structured data.

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?

Perfectly front-loaded: first sentence states purpose, subsequent clauses enumerate valid values by media category. Zero redundancy; every clause delivers necessary domain constraints for parameter selection.

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 invocation: covers all required parameters and their valid values. Minor gap: no description of return value structure (list of items, pagination behavior), though this is mitigated by the readOnly annotation indicating a safe query operation.

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?

While schema coverage is 100%, the status parameter schema only defines it as a generic string. The description adds essential domain semantics by enumerating valid values (unread/reading/finished, etc.), effectively providing the enum constraints missing from 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?

Clear verb 'Get' + resource 'items' + mechanism 'filtered by status'. The enumeration of media-specific status values (unread/reading/finished for books, etc.) sharply distinguishes this from siblings like get_by_rating and search, making the specific scope unmistakable.

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?

Provides implicit usage guidance by enumerating valid status values for each media type, ensuring correct parameterization. However, lacks explicit when-to-use/when-not-to-use guidance versus alternatives like search (full-text) or get_by_rating (numeric filtering).

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 this is read-only, idempotent, and non-destructive. The description adds valuable behavioral context by specifying the return payload ('lifecycle stage and behavioral signals') beyond what annotations provide, clarifying what 'context' actually contains without contradicting the safety hints.

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 efficient sentences with no filler. First sentence establishes purpose and use-case context ('adaptive conversation'), second sentence specifies return values. Appropriately sized for a parameterless read tool—every word earns its place.

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

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

Adequate for a simple read tool with no parameters and full annotation coverage. While lacking an explicit output schema, the description compensates by listing the specific data categories returned ('lifecycle stage and behavioral signals'). Given the low complexity and rich annotations, this is sufficient for agent selection.

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

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

Input schema has zero properties. Per scoring rules, zero parameters warrants a baseline score of 4. The description appropriately makes no mention of parameters since none exist, and doesn't need to compensate for missing schema documentation.

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

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

States specific action ('Get') and resource ('user context'), and elaborates what 'context' means ('lifecycle stage and behavioral signals'). However, it fails to distinguish from siblings like 'get_user_profile' or 'get_signals', which could also return user data or signals. The 'adaptive conversation' phrasing adds context but doesn't clarify when to prefer this over similar read 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?

Provides only implicit usage guidance via 'for adaptive conversation', suggesting it's meant for conversational adaptation scenarios. No explicit when-to-use vs. when-not-to-use guidance, no prerequisites mentioned, and no comparison with alternatives like 'get_user_profile' that might return overlapping data.

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 readOnly/destructive hints, but description substantially adds behavioral context: specifies exact data returned (AI analysis, notes, ratings, timeline), conditional behavior based on media type (albums return track lists, box sets return contained albums), and scope constraints (user's collection only).

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 well-structured sentences. First sentence front-loads purpose and enumerates return fields efficiently. Second provides usage context. Slightly diminished by aggressive capitalization ('FULL', 'FROM THE USER'S COLLECTION'), but remains appropriately sized with no wasted words.

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

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

No output schema exists, but description compensates by listing specific return fields (AI analysis, metadata, track lists, etc.). Combined with complete annotations and full schema coverage, the description provides sufficient context for invocation, though it could mention error handling for missing 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% so baseline is 3. Description adds value by explaining behavioral semantics of the media_type parameter—specifically that 'album' returns track durations and 'box sets' return contained albums, enriching understanding of how enum values affect output.

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

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

Description uses specific verb 'Get' with resource 'details of an item' and scope 'FROM THE USER'S COLLECTION'. It distinguishes from siblings by detailing the comprehensive return data (AI analysis, user notes, rating, timeline, metadata, track lists, box set contents) that lighter tools like lookup_item or show_item likely don't provide.

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?

Provides explicit when-to-use: 'Use this to answer specific questions about items the user owns.' This clearly signals it's for deep dives on known owned items, distinguishing it from search or discovery tools. Lacks specific named alternatives or explicit when-not-to-use (e.g., 'don't use for bulk operations').

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=true, idempotent=true, and destructive=false. The description adds the semantic context that this retrieves 'current research scope' information, but does not disclose output format, what fields constitute scope, or behavior when no scope is defined.

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 waste. For a zero-parameter read tool, this length is appropriately minimal while conveying the essential purpose.

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

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

Given the tool has zero parameters and clear read-only annotations, the description adequately covers the tool's purpose. While an output schema is missing, the description indicates 'information' is returned, which is sufficient for this low-complexity getter.

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

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

The input schema contains zero parameters. Per evaluation guidelines, zero-parameter tools receive a baseline score of 4. The description appropriately makes no parameter claims since none exist.

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 phrase 'Get information about' and identifies the specific resource 'current research scope'. It effectively distinguishes from the sibling mutation tool 'expand_research_scope' (get vs expand), though it could clarify how it differs from other getters like 'get_context' or '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?

Usage is implied by the verb 'Get' and the resource 'scope' contrasted with sibling 'expand_research_scope', but there are no explicit when-to-use guidelines or named alternatives. The agent must infer when scope information is needed versus general 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 declare the operation is read-only, idempotent, and non-destructive. The description adds semantic value by defining what 'signals' means (the three specific behavioral patterns), but omits operational details like rate limits, caching behavior, or response size expectations that would help an agent plan invocation.

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?

Extremely efficient single sentence with zero filler words. The colon structure front-loads the action and efficiently lists the three signal types. However, the brevity comes at the cost of usage context, preventing a perfect score.

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?

Without an output schema, the description partially compensates by listing the conceptual signal types returned, but fails to describe the data structure, format, or what constitutes empty results. Given the 0-parameter input and analytical nature, additional guidance on return shape would be expected.

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

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

Input schema contains zero parameters, triggering the baseline score of 4. The description correctly implies no filtering is possible (returns all signals), but does not need to document nonexistent parameters.

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

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

The description uses a specific verb ('Get') and identifies exactly what 'signals' entails: theme repetition, consumption gaps, and recent activity. This distinguishes it from generic siblings like get_stats or get_context by specifying analytical/behavioral pattern detection rather than raw data retrieval.

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 provided on when to use this tool versus similar analytical siblings like get_stats, get_context, or get_timeline. The description lacks prerequisites, exclusions, or explicit alternative recommendations despite the crowded namespace of getter 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 declare read-only, idempotent, and safe properties. The description adds valuable behavioral context by specifying exactly what statistical dimensions are returned (progress, rating distribution, genre/theme breakdown, timeline), which helps the agent predict if this tool satisfies the user's need for aggregate analytics.

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 tightly constructed sentences with zero waste. The first front-loads the specific statistical categories returned; the second efficiently handles the parameter default behavior. Every word earns its place.

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

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

Given the lack of output schema, the description effectively compensates by enumerating the specific statistical categories returned. With annotations covering safety profiles and only one optional parameter, this provides sufficient context for agent invocation decisions.

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 description restates the parameter's optional nature. The mention of 'combined stats' adds slight semantic value over the schema's 'omit for all', but doesn't significantly elaborate on format, constraints, or interaction effects beyond the well-documented 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 (Get) and resource (collection statistics) with concrete scope details (progress, rating distribution, genre/theme breakdown, timeline). However, it could more explicitly distinguish from siblings like `get_timeline` or `get_by_rating` by clarifying this returns aggregate/analytics data rather than individual records.

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?

Provides clear parameter usage guidance ('If no media_type specified, returns combined stats'), but lacks explicit guidance on when to select this tool versus the numerous sibling 'get_' tools (e.g., get_details, get_timeline, get_by_rating) that might overlap in functionality.

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 read-only, idempotent, non-destructive safety profile. The description adds valuable domain context that the timeline specifically tracks start and completion dates ('started and finished over time'), which helps agents understand the temporal nature of the returned data.

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?

Nine words in a single sentence. Excellent density with no redundancy. Front-loaded with verb and noun. However, extreme brevity leaves gaps in behavioral specification that a slightly longer description could address.

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 simple read-only tool with complete annotations and single parameter. Lacks description of output structure, time range granularity, or pagination (since no output schema exists), but mentions 'showing items' which hints at return content.

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 and only one parameter (media_type), the schema fully documents the enum values. The description adds no parameter-specific guidance, but baseline 3 is appropriate when structured data carries the full semantic 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 specific verb (Get) and resource (timeline), and clarifies domain scope by mentioning 'items started and finished over time.' However, it does not explicitly distinguish from sibling tools like get_stats or get_by_status which also retrieve item data.

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?

Provides no guidance on when to use this tool versus the many sibling 'get_' tools (get_stats, get_by_status, get_details, etc.), nor does it mention prerequisites or filtering capabilities beyond the media_type parameter.

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 readOnly/idempotent/destructive=false, so safety is covered. Description adds crucial behavioral specifics: '30-second' duration constraint, 'playable' nature (implies audio URLs/files vs metadata), and 'IN THE USER'S LIBRARY' scope alignment with openWorldHint=false. No contradictions with annotations.

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

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

Single sentence with high information density. Front-loads the action and key constraints. Slight deduction for ALL CAPS emphasis on 'IN THE USER'S LIBRARY' which is unconventional formatting, though the constraint itself is valuable.

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 read-only tool with 3 well-documented parameters and safety annotations. Lacks description of return format (URLs? streaming endpoints? base64?) since no output schema exists. Missing pagination details (though max_tracks suggests simple limiting).

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 complete descriptions for all three parameters (album_title, max_tracks, track_numbers). Description mentions 'from an album' loosely mapping to album_title, but with high schema coverage, baseline 3 is appropriate as description doesn't need to duplicate param docs.

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

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

Clear specific verb ('Get') and resource ('playable 30-second audio previews'). Explicitly scopes to 'IN THE USER'S LIBRARY' (all caps emphasis), which distinguishes it from general catalog queries. However, fails to explicitly differentiate from sibling tool 'preview_album' which sounds functionally similar.

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 use this versus alternatives (particularly 'preview_album'). No mention of prerequisites (e.g., album must exist in library) or when to prefer 'track_numbers' filtering versus getting all tracks.

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 this is read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond these safety properties by explaining the data source ('built from past conversations') and specific content categories returned, which helps the agent understand the tool's utility for personalization tasks.

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 efficiently structured sentences with zero waste: the first establishes the operation and data persistence model, the second catalogs specific return content categories. Front-loaded and appropriately sized for a simple read operation.

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 zero-parameter complexity, rich annotations (4 hints provided), and absence of output schema, the description adequately explains what data is returned (taste patterns, preferences, etc.). It successfully compensates for the missing output schema by enumerating return content categories.

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

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

The input schema contains zero parameters. Per rubric guidelines, zero-parameter tools receive a baseline score of 4. The description appropriately requires no parameter explanation since the schema carries no arguments needing semantic clarification.

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

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

The description clearly states the action ('Get') and resource ('persistent profile'), and distinguishes it from siblings by specifying the content is 'built from past conversations' and contains 'taste patterns, key facts, cross-media connections, and preferences'—clearly identifying this as a user preference/profile tool versus item-specific gets like 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?

The description implies usage by detailing what the profile contains (taste patterns, preferences), suggesting when to use it (when needing user preference data). However, it lacks explicit guidance distinguishing this from similar siblings like get_context or get_details, and provides no 'when not to use' or alternative 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 cover safety profile (readOnly/idempotent/destructive), so description adds value by disclosing external data source mappings (OpenLibrary, TMDB, Discogs, AniList) and the anime/show distinction that annotations don't capture.

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

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

Four sentences, zero waste. Front-loads critical negative constraints (NOT user's collection) and logically flows from purpose → alternatives → data sources → type distinctions.

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?

Comprehensive given 100% schema coverage and rich annotations. Minor gap: no mention of return value structure (though no output schema exists). Data source mappings and sibling distinctions provide strong context.

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

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

Schema coverage is 100%, so baseline applies. Description adds minimal parameter-specific semantics beyond schema—it repeats the anime/show guidance already in schema but doesn't elaborate on year/creator usage syntax.

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?

Excellent specificity: states exact action (search EXTERNAL databases), scope (NOT user's collection), timing (BEFORE adding), and distinguishes from siblings search/get_details by specifying use for items user already owns.

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 when-to-use (before adding items) and when-not-to-use (for owned items, use search/get_details instead). Clear alternates named that exist in sibling list.

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

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

Annotations declare read-only/non-destructive safety, but description adds critical behavioral context: return format ('playable 30-second previews') and side-effect disclaimer ('WITHOUT adding to library'). The latter is especially important since users might fear previewing affects their 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?

Three sentences, zero waste. First sentence establishes scope and constraints, second provides usage guidance, third specifies return value. Perfectly front-loaded with the core action and most critical constraint (no library modification).

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 its complexity: covers Apple Music source, 30-second preview return value (compensating for no output_schema), and library-non-mutation guarantee. Aligns well with annotations (readOnly/idempotent) without redundancy.

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% (title, artist, max_tracks all documented in schema). Description doesn't add parameter-specific semantics (like explaining max_tracks defaults), so baseline 3 applies—adequate given schema completeness.

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?

Excellent specificity: 'Preview any album from Apple Music' provides clear verb (Preview) and resource (Apple Music album). Crucially distinguishes from sibling 'add_item' by emphasizing 'WITHOUT adding to library' and 'sample before committing to add', establishing the distinct workflow step.

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?

Provides clear usage context ('Use this to sample before committing to add') establishing this as a try-before-you-buy step in the workflow. Implies the alternative (adding) exists, though it doesn't explicitly name the 'add_item' sibling tool, which would have earned 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 readOnlyHint=true and idempotentHint=true, covering safety profile. Description adds 'serendipitous discovery' as intent but lacks behavioral details like whether selections are truly random, if repeats are avoided, or what happens if no items match filters.

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?

Extremely concise at 6 words. Front-loaded with action verb, zero redundancy. Every word earns its place.

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

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

Given 3 simple parameters with complete schema coverage and safety annotations, the description meets basic needs but fails to clarify the source pool (user's existing library vs external catalog), which is relevant context given the 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% with all parameters fully documented. Description implies plurality with 'item(s)', lightly signaling the count parameter capability, but otherwise adds no semantic detail beyond the schema.

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

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

States specific action ('Pick random item(s)') and target resource, with 'serendipitous discovery' providing use-case context. Does not explicitly distinguish from sibling 'search' tool, though the randomness aspect is implicitly clear.

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

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

No guidance on when to use this versus targeted retrieval tools like 'search' or 'get_by_rating'. Missing prerequisites (e.g., requires existing items in library) and exclusion criteria.

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

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

Annotations declare readOnly/idempotent/non-destructive behavior, which matches the description's verb 'Read'. The description adds context that the book must be 'uploaded' (implied scope), but omits behavioral details like error handling for out-of-bounds lines, return format, or the partial matching behavior mentioned in the schema.

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

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

Single sentence, front-loaded with the action. Every word serves a purpose: 'Read' (action), 'specific section' (scope), 'uploaded book' (resource constraint), 'by line numbers' (filtering mechanism). Zero redundancy.

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

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

Adequate for a read-only tool with 100% schema coverage and comprehensive annotations. The description covers the core purpose; detailed constraints (200-line max, partial matching) are appropriately delegated to the schema. Minor gap: does not describe the output structure (though output schema is absent).

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 clear descriptions for all three parameters ('book_title', 'start_line', 'end_line'). The description phrase 'by line numbers' reinforces the relationship between start and end parameters, but adds no semantic detail beyond what the schema already provides, meriting the baseline score.

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 specific verb ('Read'), resource ('section of an uploaded book'), and access method ('by line numbers'). Clearly defines scope but does not explicitly differentiate from sibling tool 'search_book_content' or mention when line-number access is preferred over content 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?

Implies usage prerequisites through 'by line numbers' (suggests user needs specific line ranges), but provides no explicit guidance on when to use this versus 'search_book_content' or other book-related tools. Lacks explicit prerequisites like 'book must be uploaded first'.

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

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

Adds valuable context about 'external sources' (aligning with openWorldHint) and 'all metadata' (scope). However, fails to disclose implications of idempotentHint=false (multiple calls may create side effects) or behavior when external sources are unreachable.

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 tightly constructed sentences with zero waste. Front-loaded with the action (re-fetch), followed immediately by usage condition. Every word earns its place.

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

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

Adequate for a 2-parameter tool with good annotations covering safety profile. Missing: failure mode disclosure for external fetches (openWorldHint=true), idempotency warnings, and whether this preserves user edits or overwrites all fields.

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 clear parameter descriptions. The description refers to 'item' generically without elaborating on parameter interaction (e.g., that partial title matches are supported), meeting the baseline for well-documented schemas.

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 specific verb 'Re-fetch' and resource 'metadata from external sources'. Clear scope. However, lacks explicit differentiation from siblings like 'edit_item' (manual correction) vs automated re-fetch.

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?

Provides specific trigger condition 'Use when item has wrong data'. However, lacks explicit 'when not to use' guidance and doesn't mention alternatives like manual editing via edit_item vs automated re-enrichment.

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 crucial durability context ('lasting', 'persistent profile') beyond annotations. The examples of insight types (patterns, preferences) clarify content semantics that annotations don't cover. Complements the write-operation annotations (readOnlyHint:false) without 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?

Two sentences, perfectly structured: first defines operation, second defines usage trigger. Zero redundancy, front-loaded with action verb, no filler words.

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

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

Fully complete for a 2-parameter write operation. No output schema exists, but description sufficiently establishes the persistent side effect. Annotations present, parameters fully documented.

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 detailed parameter descriptions. The tool description doesn't add parameter syntax or format details, but doesn't need to given complete schema coverage. Baseline score 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?

Excellent specificity: verb 'save' + resource 'insight' + destination 'persistent profile' clearly distinguishes this from sibling get_user_profile (read-only) and update_notes (general notes). The 'lasting' qualifier differentiates from temporary operations.

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?

Strong positive guidance with 'Use when you discover...' specifying exact trigger conditions (patterns, preferences, cross-media themes). Lacks explicit negative guidance (e.g., 'don't use for temporary thoughts') or reference to sibling update_notes as alternative.

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

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

Annotations mark this as read-only and safe, but the description adds valuable behavioral context by detailing what gets returned: 'items they own with status, ratings, and for box sets, the list of contained albums.' This compensates for the missing output schema.

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

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

Three sentences, each serving a distinct purpose: action (what it does), return values (what it returns), and usage guidance (when to use). The description is front-loaded with the core operation and contains no redundancy.

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

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

Given no output schema exists, the description appropriately describes return values and status information. It covers the essential scope for a personal collection search tool, though it could optionally mention result limits or pagination behavior.

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

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

With 100% schema description coverage, the baseline is 3. The description mentions searchable fields ('title, creator, genre, or theme') which aligns with the schema's description of the query parameter, adding minimal new semantic value but confirming the multi-field search capability.

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 ('Search') and resource ('USER'S COLLECTION') and distinguishes from siblings like 'search_youtube' and 'search_conversations' by emphasizing the user's owned collection. The all-caps 'USER'S COLLECTION' effectively signals scope.

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?

Provides clear guidance with 'Use this to answer questions about what the user has.' However, it could be improved by explicitly naming alternative search tools (e.g., 'search_youtube' for external content) rather than relying solely on the implicit 'COLLECTION' distinction.

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

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

The annotations already establish read-only, idempotent safety properties, so the description appropriately focuses on adding implementation details: specifying the AI embeddings mechanism and supported formats (EPUB/PDF). It discloses that the tool returns 'relevant passages,' providing some insight into the return structure despite the lack of output schema.

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

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

Two information-dense sentences efficiently convey format constraints, underlying technology (AI embeddings), and return type ('passages') with zero redundancy. The description is front-loaded with the core value proposition (semantic book search).

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 complete parameter schema and comprehensive annotations, the description successfully establishes the tool's AI-powered nature and scope. Mentioning 'relevant passages' partially compensates for the missing output schema, though explicit details on result structure (e.g., whether location metadata or relevance scores accompany passages) would further strengthen completeness.

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 description adds crucial semantic context: clarifying that 'book_title' refers to previously uploaded content (EPUB/PDF) and that 'query' supports natural language semantic search rather than just keyword matching. This helps agents construct appropriate parameter values beyond the schema's literal descriptions.

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

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

The description explicitly identifies the action ('Semantic search'), resource ('uploaded book'), and supported formats ('EPUB/PDF'). It distinguishes from siblings like the generic 'search' and 'read_book_section' by emphasizing the semantic/AI-driven nature of the retrieval mechanism.

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?

While 'semantic search' implies meaning-based retrieval suitable for conceptual queries, the description lacks explicit guidance on when to select this tool over the generic 'search' sibling or 'read_book_section'. It does not state prerequisites (e.g., books must be uploaded first) or provide exclusion criteria.

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

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

Adds substantial behavioral context beyond annotations: clarifies semantic search behavior ('finds conceptually related conversations, not just keyword matches') and scope constraint ('with this user'). Annotations cover safety profile (readOnly, non-destructive), allowing description to focus on functional 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 with zero redundancy. First sentence establishes purpose and scope; second sentence adds critical behavioral distinction (semantic vs keyword). Every word earns its place.

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

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

Complete for a read-only search tool of moderate complexity. Annotations adequately cover safety/transactional behavior. Absence of output schema is acceptable for standard list-returning search operations, though mentioning result structure would elevate to 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 has 100% description coverage ('What to search for', 'Max results'), establishing baseline 3. Description does not add parameter-specific guidance (e.g., query syntax, optimal limit values) but this is acceptable given complete schema documentation.

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

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

Excellent specificity: verb 'Search' + resource 'conversations' + scope 'with this user' clearly defines the operation. Explicitly distinguishes from generic 'search' sibling by targeting conversation history specifically.

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?

Provides implicit usage guidance by highlighting 'semantic search' capability (conceptually related vs keyword matches), helping agents select this tool for conceptual similarity searches. However, lacks explicit 'when not to use' or direct comparison to the generic 'search' sibling.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive properties. The description adds value by specifying content types available (interviews, trailers, etc.), but omits external API rate limits, authentication requirements, or latency implications despite openWorldHint=true suggesting external API usage.

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?

Single sentence that front-loads the core action ('Search YouTube') and uses parenthetical examples efficiently. No wasted words; every element 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?

Given the simple 2-parameter schema, 100% coverage, and clear annotations, the description is minimally complete for tool selection. However, with no output schema provided, the description should ideally characterize return values (e.g., video metadata format) rather than just input intent.

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%, documenting both 'query' and 'max_results' completely. The description implies the search intent but adds no semantic detail beyond the schema definitions. Baseline 3 is appropriate given full schema coverage.

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

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

The description clearly states the action (search), resource (YouTube), and return type (videos) with specific content examples. While it effectively distinguishes from siblings like 'search' and 'search_book_content' through the tool name and 'YouTube' reference, it lacks explicit comparative language against the generic 'search' tool.

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

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

No explicit guidance on when to use versus alternatives like 'search' or 'search_book_content'. The parenthetical examples '(interviews, trailers, analysis, music videos)' hint at use cases but do not constitute explicit when-to-use guidance or 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?

Adds valuable operational context beyond annotations: specifies client compatibility ('ALL clients: web app, iOS app, Claude Desktop') and dual-mode behavior ('triggers navigation OR returns clickable URL'). Annotations cover safety profile (readOnly/idempotent), description covers practical execution 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?

Four sentences with zero waste: trigger conditions, action, client coverage, prohibition. Front-loaded with urgency 'ALWAYS'. Every phrase earns its place including specific quoted user intents.

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 2-parameter navigation tool with full schema coverage. No output schema exists, but description adequately covers return behavior (URL or navigation trigger). Minor gap: doesn't specify error handling for non-existent items, but sufficient for complexity level.

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 has 100% description coverage with 'partial match supported' already documented. Description uses generic term 'item' without explicitly mapping to schema parameters, but baseline 3 is appropriate when schema carries full semantic 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?

Excellent specificity: states the tool 'navigates them to the item's detail page' and distinguishes from siblings by emphasizing 'Do NOT just describe the item when they want to SEE it' - clearly differentiating from lookup_item/get_details which presumably return metadata without navigation.

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?

Exceptional guidance with explicit trigger phrases ('show me', 'open', 'go to', 'take me to', 'pull up') using imperative 'ALWAYS use this tool when'. The prohibition 'Do NOT just describe' clearly defines when NOT to use descriptions/alternatives.

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

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

Description confirms the write operation (consistent with readOnlyHint=false) but fails to disclose the critical lookup behavior: items are identified by partial title match, not explicit ID. Does not explain the non-idempotent nature (idempotentHint=false) or what happens if multiple titles 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?

Compact single sentence with strong verb-first structure. No redundant words, though 'an item' could be more specific given the media context.

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

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

Adequate for a 3-parameter tool with complete schema coverage and annotations present. However, given the ambiguity of item lookup (partial match vs exact) and the lack of output schema, the description could better explain the identification mechanism.

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 carries the semantic weight. The description aligns with parameters ('personal notes' maps to notes param, 'item' maps to media_type/title) but adds no syntax details or examples 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?

Clear verb ('Add or update') and resource ('personal notes'), but refers to 'an item' vaguely without specifying it targets media items by partial title match. Does not distinguish from sibling tool edit_item which likely updates core metadata rather than personal notes.

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 prefer this over edit_item or save_insight. Does not mention that the item must exist beforehand (though implied by 'update') or warn about the partial title matching behavior.

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 notes the 1-5 star constraint but fails to clarify critical behavior around the 'partial match supported' title parameter—specifically whether updates apply to the first match, all matches, or fail on ambiguity. It also does not explain the idempotentHint=false annotation (e.g., if repeated calls create multiple ratings or replace existing ones).

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?

Extremely concise single sentence with no redundant words. Key information (action, resource, scale) is front-loaded efficiently.

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

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

The description covers the basic operation but leaves significant gaps for a mutation tool: it omits output information (though none is defined), success semantics, and crucially, the behavior when partial title matches return multiple 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?

With 100% schema coverage, parameters are fully documented in the schema. The description adds minimal semantic value beyond restating the 1-5 range already defined in the schema constraints, warranting the baseline score.

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

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

The description clearly identifies the action (set/update) and resource (user rating) with specific constraints (1-5 stars). However, it does not explicitly differentiate from sibling tools like 'edit_item' or 'update_status'.

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

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

No guidance is provided on when to use this tool versus 'edit_item', 'add_item', or 'update_status'. It does not mention prerequisites like item existence or warn about the implications of partial title matching.

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 indicate write access (readOnlyHint:false) and non-destructive nature. The description adds critical behavioral context not in the schema: the valid status values are enumerated per media_type (e.g., albums use 'unheard, listening, played, saved'), which is essential domain logic for correct invocation.

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?

Highly efficient single-sentence structure front-loaded with the action verb. The colon-separated lists of valid values pack dense information without redundancy. No filler text, though 'Update status.' alone is terse.

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 mutation tool with no output schema, the description provides complete domain constraints (status enums per type) necessary for correct usage. The schema already covers partial matching for titles, so the combination is sufficient.

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 has 100% coverage but defines 'status' only as 'New status value' (generic string). The description adds substantial semantic value by documenting the actual valid enum values for status depending on media_type (books/movies/albums), which is necessary for the agent to provide correct inputs.

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 action (update status) and distinguishes scope via enumerated valid values per media type (e.g., 'unread, reading, finished' for books vs 'unwatched, watching, watched' for movies). Implicitly distinct from sibling 'bulk_update_status' (single vs batch) and 'update_rating'/'update_notes' (different attributes).

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

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

No explicit guidance on when to choose this over siblings like 'bulk_update_status', 'edit_item', or 'add_item'. While the enumerated values imply usage context, there are no stated prerequisites, exclusions, or comparisons to alternatives.

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