HumMatch

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond these by explaining that the tool not only scores but also 'explain why it fits or does not, including a suggested key to transpose to.' This describes the output behavior without contradicting the annotations.

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

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

The description is three sentences long, front-loaded with the core purpose, and each sentence contributes necessary information: what it does, when to use it, and a prerequisite. No wasted words or redundant restating of the 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?

Given the tool's moderate complexity, the presence of rich annotations, a complete input schema with 100% descriptions, and an output schema, the description fully covers the necessary context. It tells the agent exactly when and how to invoke the tool, and the schema/output schema cover the technical details.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds valuable semantic context for the slug parameter by noting it comes from search_songs. This extra guidance helps the agent understand the parameter's provenance beyond the schema.

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

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

The description clearly states the tool's function: 'Score a specific catalog song against a singer's range and explain why it fits or does not.' It distinguishes itself from siblings like recommend_songs and group_song_fit by focusing on a single song evaluation, and directly mentions the search_songs prerequisite.

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

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

The description provides explicit usage context: 'Call this when someone asks whether they can sing a particular song.' It also gives a clear instruction to resolve the song via search_songs first. While it doesn't explicitly state when not to use it or name alternatives, the context is unambiguous and actionable.

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 and idempotent, and the description adds context by noting the profile is 'normalized' and 'persistent', and that it is reusable. This clarifies that the tool transforms input into a stable, shareable profile, complementing the annotation-level safety information.

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

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

The description is two sentences with no fluff: first sentence defines the function, second provides usage timing. It is front-loaded with the core purpose and ends with actionable guidance.

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 complete input schema, an output schema, and comprehensive annotations, the description does not need to explain return values. It adds the essential workflow context and is fully self-contained for an agent to decide when to invoke 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?

Input schema covers all three parameters with detailed descriptions (e.g., 'Lowest comfortable note, as a note name like "D3" or a raw MIDI number'). The description does not add parameter-specific meaning beyond the schema, which is acceptable given 100% schema coverage.

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

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

The description states a specific action: 'Turn a singer's vocal range into a normalized HumMatch vocal profile' and identifies the output components (Vocal ID, voice type, tone label). It clearly differentiates this tool from sibling tools, which focus on song fitting and recommendations, by being a profile-building prerequisite.

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 instructs when to use: 'Call this first when you know someone's range and want a profile to reuse across the other HumMatch tools.' This provides both a trigger condition and a contrast with alternative tools, establishing this as the initial step in a workflow.

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, and non-destructive behavior. The description adds context about the task but does not disclose behavioral details like handling of non-overlapping ranges or note format assumptions. It does not contradict 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?

The description is two sentences, front-loaded with the core function and then enriched with use-case examples. Every sentence adds value with 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?

The description is sufficiently complete for a read-only analysis tool with an output schema. It explains the input, purpose, and when to use it. Minor missing details around edge cases (e.g., no overlap) are not critical given the output schema.

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

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

Schema covers 100% of parameter descriptions, including the structure of profiles with rangeLow/rangeHigh. The description simply restates 'two or more singers' ranges' without adding new semantic 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?

The description clearly states the tool's function: finding the shared vocal range and songs within it for two or more singers. It also distinguishes itself from siblings by focusing on group compatibility rather than individual song checks or recommendations.

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

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

The description provides explicit usage contexts (karaoke, duets, choir, worship team) and suggests when to call it ('what can we all sing' question). It lacks explicit exclusions or alternative tool names, but the context is clear enough.

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, and destructiveHint as safe, so the bar is lower. The description adds behavioral context: 'scored for range fit, karaoke difficulty, and voice-type suitability' and the output structure with named buckets. This goes beyond the annotations without contradicting them.

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 sentences: purpose, when-to-use, and return structure. Every sentence adds value, is front-loaded, and avoids redundancy with 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?

Given the tool's moderate complexity, an output schema exists (so return values are covered), and the description explains the key behavior, use cases, and output buckets. It is complete for an agent to understand when and how to invoke 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%, so the baseline is 3. The description does not add significant syntax or domain meaning beyond the schema—'range' and 'voice-type' are mentioned but not expanded with new parameter-specific details.

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 ('Rank') and resource ('the HumMatch catalog') and clearly states the outcome: 'return the songs they can actually sing, scored for range fit, karaoke difficulty, and voice-type suitability.' It also distinguishes from siblings by emphasizing 'one singer' versus group-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?

Provides explicit call scenarios: 'when someone asks what they should sing, what suits their voice or range, or wants karaoke song suggestions.' It does not mention when-not-to-use or alternatives, but the context is clear and sufficient for correct 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?

Beyond readOnlyHint annotations, the description discloses that providing rangeLow/rangeHigh scores every result and ranks by fit, and that it resolves songs to catalog slugs. This adds behavioral context not captured in annotations, though it could mention behavior when no results are 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?

Three sentences, each serving a purpose: purpose, use cases, and parameter behavior. No filler or 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?

Output schema exists, so return format is covered. The description explains use cases, relation to check_song_fit, ranking behavior, and parameter usage, making it complete for this 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 fully describes all 4 parameters, and the description adds semantic context: q searches title or artist, rangeLow/rangeHigh are used for scoring/ranking results. Limit is self-explanatory, so the description provides meaningful value beyond the schema.

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

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

The description opens with 'Search HumMatch by song title or artist' – a specific verb and resource. It further distinguishes from siblings by noting check_song_fit needs the catalog slug from this tool and that it can look up a song's measured vocal range.

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 resolve a song someone named into the catalog slug that check_song_fit needs' explicitly gives when-to-use context, and the rangeLow/rangeHigh guidance explains when to enrich the search. This clearly positions the tool relative to alternatives.

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