Keyboardia

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral richness: it reports uncertainty ('report where the analysis is uncertain instead of guessing') and notes the provenance of results (same module as Key Assistant and Chromatic Grid). This goes beyond what annotations provide.

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, each earning its place: purpose, usage guidance, and behavioral context. It is front-loaded with the core action and free of redundant filler.

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

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

For a simple read-only analysis tool with one parameter and no output schema, the description is quite complete: it explains what is analyzed, that nothing is changed, when to use it, and how it handles uncertainty. It could include what the returned analysis looks like, but that is not essential for the core understanding.

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

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

Schema description coverage is 100%, and the schema parameter description already explains the format ('The UUID after /s/ in a Keyboardia share URL. Pass only the UUID'). The tool description does not add parameter-specific details, but it doesn't need to since the schema is complete. This is the baseline 3 for 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 states a specific action ('Describe what is happening musically in a session') and lists concrete musical attributes (rhythm, pitch content, inferred key, chords). It also distinguishes itself from editing by saying 'Use this to explain music rather than to edit it', which clearly separates it from sibling tools like edit_session.

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

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

The description explicitly tells when to use it ('to explain music rather than to edit it') and clarifies it changes nothing. It does not enumerate all sibling alternatives, but it gives a clear usage contrast with editing. The context also implies it is for analysis, which is distinct from fetching or exporting.

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 indicate idempotent, non-read-only, non-destructive. The description adds practical behavioral details: the session starts empty ('starts with no tracks'), returns a shareable URL, and explains the idempotency_key retry semantics to avoid duplicates. These go beyond the annotation flags.

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 exactly three sentences, front-loaded with the primary action and outcome, followed by the empty-state behavior and idempotency note. Every sentence adds value with no redundant or filler content.

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 creation tool with no output schema, the description covers the core action, return value (shareable URL), initial empty state, and how to handle retries. It also points to edit_session for subsequent modifications, making the tool's role in the larger workflow clear.

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?

All three parameters (name, tempo, idempotency_key) have detailed schema descriptions, so the tool description does not need to repeat them. The phrase 'normal defaults' loosely references defaults but adds no new parameter-specific information beyond the schema. Baseline 3 applies 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 'Create a new editable Keyboardia session with the normal defaults and return its shareable URL' with a specific verb, resource, and expected output. This clearly distinguishes create_session from siblings like edit_session, publish_session, and remix_session.

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

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

The description explicitly directs users to 'use edit_session to add them' for tracks, establishing when to use this tool for initial creation versus edit_session. It also provides retry guidance for idempotency, reinforcing appropriate usage during uncertain attempts.

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

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

The description adds significant behavioral detail beyond the annotations: it explains retry-safe behavior (idempotent), warns that the returned snapshot is 'not authoritative verification', and details operation-specific preservation semantics (e.g., 'set_steps changes only the named steps; it never replaces a track or session'). 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?

The description is dense but every sentence earns its place: it front-loads the core action, states the mandatory next step, clarifies the response snapshot's limitations, and lists supported operations with key constraints. No fluff 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?

Given the complex oneOf schema, the lack of an output schema, and the absence of sibling guidance in annotations, this description covers all critical aspects: what the tool does, retry safety, the required follow-up call, and operation-specific edge cases. It is fully adequate for correct tool selection and invocation.

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

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

The input schema provides 100% description coverage for both parameters, including per-operation details and enum descriptions. The tool description adds contextual meaning about operation semantics but does not add new parameter-level information beyond what the schema already documents, so baseline 3 is appropriate.

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

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

The description clearly states it 'Make one narrow, retry-safe edit to an existing collaborative session', naming a specific verb and resource. It also enumerates the four supported operations, distinguishing it from sibling tools like get_session and create_session.

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

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

It gives explicit workflow guidance: 'After every attempt, the next Keyboardia call must be get_session for the same session' and later 'Read with get_session next.' It also constrains use to 'narrow' edits on 'existing' sessions, though it does not explicitly name alternatives like create_session for new sessions.

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

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

The description adds valuable behavioral context beyond the annotations. It states 'The session is not modified', which is redundant with readOnlyHint=true, but more importantly it reveals that 'The result lists any session features a MIDI file cannot carry rather than approximating them silently.' This explains handling of unsupported features, a behavior not covered by the annotations. The mention of matching Keyboardia's own export also sets fidelity expectations.

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

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

The description is concise, with three sentences all contributing meaningful information. It front-loads the primary action and format, and the additional behavioral notes are relevant and clearly stated without unnecessary fluff.

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

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

For a simple tool with one parameter and no output schema, the description is sufficiently complete. It covers what the tool does, the return format (base64-encoded SMF), side effects (none), and behavior for unsupported features. An agent can correctly select and invoke this tool based on the information provided.

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

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

The schema already provides 100% coverage for the sole parameter (session_id), including a clear description ('Pass only the UUID, not the full URL'). The tool description adds no additional parameter information, so the baseline score of 3 applies.

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

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

The description clearly states the tool 'Exports the session as a base64-encoded Standard MIDI File', specifying both the action and the resource. It also distinguishes this from sibling tools (analyze, create, edit, get, publish, remix) by focusing on the export functionality and its specific output format.

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 for exporting MIDI files but does not explicitly state when to use this tool versus alternatives or provide exclusions. There is no mention of 'use this when...' or references to other tools for different scenarios. The purpose guides the user, but explicit guidance is lacking.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful context by specifying that it reads 'current tempo and compact track patterns' and constrains to an 'existing' session, which gives expectations beyond 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 a single concise sentence with no redundant words. It front-loads the action ('Read') and clearly states the resource and the data involved.

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 one-parameter nature and presence of annotations, the description adequately conveys the core purpose and the type of returned content. However, since there is no output schema, the description could have more explicitly stated what the response includes, but it does enough for a basic 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 already fully documents the single session_id parameter with its UUID format and the instruction to pass only the UUID. The description provides no additional parameter detail, so it relies entirely on the schema's already strong 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 uses the specific verb 'Read' and identifies the resource as an 'existing Keyboardia session,' then names the exact data returned ('current tempo and compact track patterns'). This clearly distinguishes it from write-oriented siblings like edit_session or create_session.

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 the tool is for reading existing sessions by saying 'existing,' but it does not explicitly contrast with siblings such as analyze_session or state when to prefer this tool. There is no 'when not to use' guidance, so usage context is only implied.

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 provide readOnlyHint=false and idempotentHint=false but little else. The description adds valuable context: the source session remains editable, the new session is immutable, and a URL is returned. This goes beyond the basic annotation signals, though it doesn't cover edge cases like auth or rate limits.

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 front-loaded action and clear caveats. Every word serves a purpose; no redundant filler or 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?

For a single-parameter tool with no output schema, the description sufficiently explains the core behavior, the effect on source and new session, and the returned value. It also provides usage restrictions, making it complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, including a detailed explanation of session_id (UUID after /s/, pass only the UUID). The description itself adds no additional parameter meaning, but the schema already fully documents the single parameter, so baseline 3 is appropriate.

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

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

The description clearly states the tool 'freeze[s] the current music into a new immutable session and return[s] its URL,' which is a specific, distinctive action. It differentiates from siblings like create_session, edit_session, and export_midi by emphasizing immutability and publication.

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 'Only call this when someone explicitly asks to publish; it is never a side effect of editing or exporting.' This provides both when-to-use and when-not-to-use guidance, clearly separating it from other 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 indicate this is not read-only and not destructive. The description adds useful context beyond that: the new session records the original as its source and is editable. It reinforces the non-destructive nature ('source is never modified'). While it doesn't detail side effects like permissions or output, the annotation coverage lowers the burden, and this is adequate for a simple mutation tool.

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

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

Two sentences, no wasted words. It front-loads the primary action, then clarifies the key safety guarantee (source never modified) and gives a usage hint. Every sentence contributes directly to the agent's understanding.

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

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

The tool is simple (one parameter, no output schema), and the description covers what it does, when to use it, and the key side-effect guarantee. It doesn't explicitly describe the return value, which could be a gap since there's no output schema, but the phrase 'into a new editable session' strongly implies the result. For this complexity level, it is complete enough for correct invocation.

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

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

The schema already provides 100% parameter coverage with a thorough description of session_id (UUID format, what to pass, what not to pass). The tool description adds minimal extra meaning beyond calling it an 'existing session,' which is already implied by the schema. Per the rubric, high schema coverage sets a baseline of 3, and there is no compensatory detail in the description.

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 copies an existing session into a new editable one, with a specific verb (copy), resource (session), and outcome. It also mentions the source is never modified, distinguishing it from sibling tools like edit_session (which implies in-place editing) and create_session (which likely creates from scratch). The phrase 'this is how to continue from published work' further clarifies its unique role.

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 clear context for when to use the tool: 'this is how to continue from published work.' It implicitly contrasts with other actions like publishing or editing, and emphasizes that the source is left untouched. However, it does not explicitly name sibling tools or state when not to use it, so it falls short of a 5.

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