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

No annotations are provided, so the description carries the full burden for behavioral disclosure. It does not state whether the tool is read-only, what the return format is, how it handles multiple input sources (path, content, session), or any side effects. The vague 'so a model can perceive what is written' does not provide concrete behavioral detail.

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 that efficiently conveys the core action and purpose. 'Describe a piece as sixteen numbers per bar' is direct and useful. The trailing clause 'so a model can perceive what is written' adds some context, though 'and the rest' is imprecise. Overall, it is appropriately concise.

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 six parameters, no output schema, and no annotations, the description is too brief to be complete. It does not explain the return structure, how to choose among path/content/session, or what all sixteen numbers represent. The schema covers parameter names but lacks usage context. This is inadequate for a tool of this complexity.

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 adds minimal parameter-related meaning by listing some feature types (density, register, tension), but it does not clarify the parameters themselves (bars, path, table, voice, content, session). Since the schema already documents each parameter, the description offers little extra value beyond a general context.

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: 'Describe a piece as sixteen numbers per bar' for feature analysis. It specifies the resource (a musical piece) and output format (sixteen numbers per bar), which distinguishes it from siblings like compile_score or write_score. However, the phrase 'and the rest' is vague and could be more precise.

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 offers no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or comparative context with sibling tools such as ensemble_report or notation_reference. The intended usage is only implied through the action of describing a piece numerically.

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 annotations are present, so the description carries the full burden. It discloses the exact return structure (directives as read, before/after arrangement, sixteen features per bar) and indicates a data-only result. However, it does not explicitly state whether the operation is side-effect-free or if it mutates the session, which would be valuable for a tool named 'apply'.

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 purpose, followed by the output summary and a clear cross-reference. Every sentence earns its place 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?

For a tool with 6 parameters and no output schema, the description covers the main return value and distinguishes the primary use case. It could benefit from clarifying the interaction of the 'features' flag with the described 'sixteen features per bar' and the exact relationship among path, content, and session, though the schema handles some of this.

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 new meaning beyond the schema; it reinforces that directives are applied to a piece or session, but the schema already explains each parameter. No extra parameter-level guidance is provided.

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 applies a bandleader's directive JSON to a piece or ensemble session and returns structured result data. It names the specific verb, resource, and return format, and distinguishes from conduct_score by contrasting its prose output.

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

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

Explicitly directs users to conduct_score when they want a timing report in prose, providing a clear alternative. The description also implies when to use apply_directives (for data-formatted results) and mentions both 'piece' and 'ensemble session' contexts.

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 annotations are provided, so the description carries the full burden. It notes audio rendering is slower but doesn't clarify whether files are written, what diagnostics contain, or any side effects. The 'Slower' tip is useful but insufficient.

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 purpose and key usage alternatives. No unnecessary information.

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

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

With no output schema and no annotations, the description should clarify return content and effects. It gives a high-level summary but lacks specifics on the 'arrangement summary' format and diagnostics, though it is acceptable for a straightforward compile 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?

Schema already documents all three parameters with descriptions. The description adds the important relationship that path and content are alternatives ('Pass either a path or inline content'), which the schema does not explicitly state. This aids correct selection.

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 compiles notation to MIDI and audio, returning an arrangement summary and diagnostics. The verb 'compile' with resource 'notation' is specific and distinguishes it from sibling tools like analyze_features or transpose_score.

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 no explicit guidance on when to choose this tool over alternatives. It mentions input modes but does not clarify use cases, prerequisites, or exclusions relative to sibling 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?

With no annotations, the description carries the full burden of behavioral disclosure. It mentions reporting outcomes but uses metaphorical language ('bandleader's directive', 'hands moved') that obscures whether this is a simulation or an actual mutation of the score. It does not state side effects, permissions, or reversibility, making the tool's behavior ambiguous for an AI agent.

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 sentence with no wasted words, though it uses a metaphor that could be more direct. It is front-loaded with the core action and outcome, making it relatively concise and structured.

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

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

The tool has four parameters and no output schema, so the description should explain return values and potential edge cases. It does mention return content (timing and hand movements) but lacks information about error conditions, required parameter combinations, or what happens with invalid directives. The description is adequate but not complete for a moderately complex 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 the baseline is 3. The description adds no extra parameter-level context beyond what the schema provides; it loosely refers to 'directives' and 'a piece' but does not clarify relationships between path, content, or frame. It does not compensate for any gaps, but the schema is sufficient.

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 purpose: applying a directive JSON to a piece and reporting its effects on timing. The verb 'apply' and resource 'a piece' are specific, and the description distinguishes from siblings like apply_directives by emphasizing the reporting aspect ('report what it did').

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: when you want to apply directive JSON and see its impact on ensemble timing. It does not explicitly mention exclusions or alternatives, but the context is clear enough to guide usage. A minor gap is that it doesn't tell when to prefer this over apply_directives.

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

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

With no annotations provided, the description carries the full burden. It indicates a read-only operation via 'Read' and provides context that this is a reference lookup. It does not disclose output format or edge cases, but for a simple reference tool the essential behavior is clear.

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 sentence that is front-loaded with the verb and resource, and every clause adds meaning. There is no wasted wording, making it highly concise and well-structured.

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

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

Given the tool's simplicity (no parameters, no output schema, no annotations), the description adequately covers what it does, what content it reads, and when to call it. It is complete 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?

The tool has zero parameters, so the schema is trivially 100% covered. The description adds no parameter-specific detail, but none is needed. The baseline for zero parameters is 4.

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

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

The description uses a specific verb ('Read') and resource ('conductor's directive vocabulary') and elaborates on the content (JSON, actions, windows, targets). This clearly differentiates it from sibling tools like apply_directives, which focus on writing/applying directives.

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 states when to call the tool: 'before writing directives for the first time in a session.' This provides clear context, but it does not name alternatives or explicitly 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.

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

No annotations are provided, so the description must carry the behavioral burden. It discloses the exclusive ownership constraint and that it returns everything needed to start writing, but does not explain error conditions, reversibility, or prerequisites for the takeover parameter.

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 wasted words. It front-loads the main action and then adds purpose and return context. Every sentence 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?

For a tool with 4 parameters, no annotations, and no output schema, the description covers the core purpose, exclusivity, and return value. It lacks failure-mode details, but the overall context is sufficient for an agent to understand and invoke the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific details beyond the schema; it only mentions 'voice' generally. The schema already documents all parameters adequately.

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 'Claim' with the resource 'voice of a session', clearly stating the action and scope. It also explains the purpose ('avoid choosing the same part') and distinguishes from sibling tools like ensemble_read or ensemble_leave.

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 indicates when to use the tool: claiming is how agents secure a voice before writing. It provides clear context but does not explicitly mention alternatives or when not to use it, though the context is sufficient.

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 annotations are provided, so the description carries full burden. It does not disclose side effects (e.g., whether the voice is permanently removed, whether it becomes instantly available, or if session state is affected). The phrase 'so another agent can take it' hints at availability but lacks concrete behavioral 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?

One sentence, front-loaded with the verb 'Release', and no wasted words. Every word contributes to the meaning.

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

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

With no output schema and no annotations, the description needs to explain return values, prerequisites, and side effects. It does not mention what the tool returns, whether a session is required, or what happens to the released voice beyond being available. Incomplete for a state-changing 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 covers all three parameters with simple descriptions. The tool description adds some context (e.g., 'voice you hold' aligns with the 'voice' parameter), but it doesn't provide additional format or semantics beyond the schema. Baseline 3 applies.

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

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

The description clearly states the action ('Release a voice you hold') and the purpose ('so another agent can take it'). It distinguishes from sibling tools like ensemble_join by focusing on the handoff/release action.

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 usage is implied: use this tool when you want to give up a voice for another agent. However, there is no explicit mention of when not to use it or alternatives, making it only minimally useful for decision-making.

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?

Without annotations, the description carries the full burden. It states the tool reads the log and orders entries oldest first, but does not disclose potential side effects, return format, or error behavior. For a simple read operation, this is adequate but not rich in behavioral detail.

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 action and ordering, and the second sentence adds valuable context without 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?

For a simple two-parameter tool without output schema, the description clearly explains what it does and why it exists. It could mention what the log entries contain or what happens with an empty log, but overall it is sufficiently complete for an agent to use it correctly.

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

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

Schema coverage is 100%: both 'session' and 'limit' have descriptions. The tool description does not add parameter-specific meaning beyond the schema, 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 reads the session's change log with a specific ordering ('oldest first') and explicitly identifies the use case for a joining agent. This distinguishes it from sibling tools like ensemble_read or ensemble_report.

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: it is intended for a joining agent to learn what has happened. While it doesn't explicitly mention alternatives, the purpose is unambiguous and the context implies when to use it.

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

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

No annotations are present, so the description carries the burden. It does add useful context: the session is writable by several agents and the tool initializes musical parameters. However, it doesn't disclose what happens when reopening an existing session (e.g., overwriting settings), permissions, or return behavior, leaving gaps.

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 action, and every word earns its place. It is concise without being under-specified.

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 complexity (9 parameters) and lack of annotations and output schema, the description covers the essential purpose and shared-session context. However, it omits other parameters (though schema covers them) and doesn't mention return values or relationships with sibling tools, reducing 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?

Input schema coverage is 100%, so the baseline is 3. The description mentions key, tempo, metre, and form, which map to existing schema properties, but adds no additional semantic meaning beyond what the schema already provides.

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

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

The description clearly states the tool opens or reopens a shared session that multiple agents can write to, and that it sets session-wide key, tempo, metre, and form. This specific verb+resource phrasing distinguishes it from siblings like ensemble_join or ensemble_write_part.

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 conveys when to use it: to start a new shared session or reopen an existing one. It doesn't explicitly name alternatives or exclusions, but the context is clear enough for an agent to choose it over sibling 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?

With no annotations, the description carries the full burden. The verb 'Read' explicitly signals a non-destructive operation, and the phrase 'in one call' discloses atomic behavior. It also hints at internal logic by including 'what has changed recently' and linking to the session listing fallback (via schema). It doesn't discuss error handling or auth, but the read-only nature is strongly implied.

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, well-structured sentence with a front-loaded verb and resource, followed by a colon and a comma-separated list of content items. Each listed item earns its place and collectively conveys the full scope without redundancy or filler. It is both concise and information-dense.

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 that there is no output schema, the description appropriately enumerates the return content in detail (key, tempo, voices, parts, version, changes). It also conveys the primary use case of preparing to write. It does not specify the output format or how the version should be interpreted, which is a minor gap, but overall it provides a solid mental model.

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

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

Schema coverage is 100%, so the baseline is 3. The main description adds value by connecting parameters to usage: 'bars' to 'the bars you are about to write', 'agent' and 'voice' to 'your own part' and 'the version to write against', and 'history' to 'what has changed recently'. This enriches the schema's brief descriptions and clarifies how each parameter shapes the read operation.

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 verb 'Read' and the resource 'session', then enumerates a comprehensive list of specific data it retrieves (key, tempo, metre, form, voice assignments, parts, version, recent changes). This explicit scoping distinguishes it from sibling tools like ensemble_status or ensemble_log, which likely focus on narrower aspects. The phrase 'in one call' further emphasizes its consolidated 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 situational context by mentioning 'the bars you are about to write', implying it is intended for use before composing. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of offering exclusions or direct comparisons. This matches the criterion of clear context without explicit 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?

No annotations are provided, so the description must carry the burden of behavioral disclosure. It only states the basic action without mentioning side effects, output format, or whether existing files could be overwritten.

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 sentence that efficiently communicates the core action. No unnecessary words or repetition.

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

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

With no output schema and no annotations, the description should clarify return values or output artifacts. It does not state what the tool returns or where the MIDI/audio is written, leaving significant ambiguity for the agent.

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%: 'session' and 'audio' are both described. The description adds no additional parameter semantics, so a baseline of 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 merges parts and compiles the session to MIDI, optionally audio. It uses specific verbs and a clear resource (session), but does not explicitly differentiate from sibling tools like compile_score, so it doesn't fully reach a 5.

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

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

No guidance is provided on when to use this tool versus alternatives, no prerequisites, and no exclusions. The usage context is only implied by the action itself.

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 annotations are provided, so the description carries full responsibility for behavioral disclosure. It describes the report's contents but fails to state whether the tool is read-only, has side effects, or requires certain conditions (e.g., an active ensemble session). This leaves uncertainty about its behavior.

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

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

The description is a single, information-dense sentence that leads with the report's core purpose and then specifies its contents. It avoids irrelevant details, though the long middle section could be slightly unwieldy.

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 three parameters are fully described in the schema and the description thoroughly explains the report's scope and content (including spread at all listeners), the tool is adequately specified for a reporting operation. No output schema exists, but the description covers the main return value 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 fully documents all three parameters (path, frame, content) with clear descriptions. The tool description adds no additional parameter-level detail, but since schema coverage is 100%, the baseline of 3 applies.

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

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

The description uses the specific verb 'Report' and identifies the resource as 'what a listener on the stage actually hears', listing specific metrics (distance, speech time, propagation delay, player action moment, spread). This clearly distinguishes it from broader sibling tools like ensemble_read or ensemble_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?

The description clearly implies the tool is for obtaining a detailed listening report, but does not explicitly state when to use it over alternatives such as ensemble_read or ensemble_status, nor does it mention any exclusions or prerequisites.

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

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

With no annotations, the description carries the burden. It explicitly describes the output content (version, voices, holdings, bar count, compile status) and behavior when the parameter is omitted. The word 'view' implies read-only, and the description adds context about the merged score compilation check.

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 that efficiently communicates the tool's purpose and the main usage variation. Every clause 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?

For a simple read-only status tool with one optional parameter and no output schema, the description is fairly complete. It explains what the return view includes and how to list sessions. It could potentially mention whether it requires an active session, but that is not essential for basic usage.

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% (the single parameter's description already states 'Omit to list the sessions'). The tool description repeats this same information, adding no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool provides a short view of a session, listing specific attributes (version, voices, holdings, bar count, compile status). This distinguishes it from sibling tools like ensemble_report or ensemble_log, and the optional session parameter for listing sessions is clearly described.

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 gives clear context: provide a session name for status, omit it to list sessions. However, it does not explicitly mention when to use this over alternatives like ensemble_report or ensemble_read, so it lacks explicit exclusion/alternative 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?

With no annotations, the description carries the full burden and does well: it discloses that notation is parsed and validated against the session header before disk write, and explains the optimistic concurrency behavior (stale writes refused, current part returned for rebase). This goes beyond a simple 'write' statement. It does not mention permission requirements or return value shape, but the provided behavioral details are substantial.

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

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

Two sentences, front-loaded with the core purpose, and every clause adds necessary information. No fluff or repetition. The structure is ideal for quick agent scanning.

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

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

For a write tool with no output schema and no annotations, the description covers the essential workflow: write action, validation, conflict handling, and rebase instruction. It does not describe the success return value or the summary parameter, but the schema covers parameters well, and the description adequately covers the concurrency context. Slight gap on return values, but still strong.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the semantics of base_version (optimistic concurrency) and reinforces that content is 'for your voice only, no header block.' This goes beyond the schema's already-detailed descriptions, meriting a 4.

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

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

The description opens with a specific verb and resource: 'Write your voice's part.' It clearly distinguishes from siblings like ensemble_read (read) and write_score (full score) by focusing on a single voice's part within a session. The additional context about notation parsing and version checking reinforces 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 gives explicit actionable guidance: 'Pass the base_version you read; if the voice has moved on the write is refused and you are given the current part to rebase onto.' It clearly explains the precondition (read first) and the conflict workflow. It stops short of explicitly naming sibling tools (e.g., 'use ensemble_read to get the version') or stating when not to use this tool, hence one point off.

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 annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action and location scope without mentioning recursion, hidden files, output format, or whether directories are included, leaving critical behavioral traits unspecified.

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, immediately clear sentence that front-loads the core action and scope. It is appropriately sized for a simple tool and contains 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?

The tool is simple, but with no annotations and no output schema, the description should provide more context about return values and behavioral specifics. The current description is too sparse to inform the agent about what the response looks like or how the listing is performed, making it incomplete for autonomous 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 fully describes the single optional 'path' parameter with its meaning and default value, so the description does not need to add parameter details. With 100% schema coverage, the baseline of 3 applies because no additional semantic value is required.

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 ('List') and the resource ('files in the working directory'), making its purpose unambiguous and distinct from sibling tools like read_file or write_file, which operate on file contents. The scope is also specified, so there is no confusion about what is being listed.

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 no explicit guidance on when to use this tool versus alternatives or any prerequisites. While the purpose implies it is for discovering available files, there is no mention of exclusions, conditions, or comparisons to sibling tools, leaving the agent without clear usage context.

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

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

With no annotations provided, the description carries the full burden. 'Read' implies a non-destructive operation, and the 'first time in a session' hints at session-scoped behavior. However, it does not explicitly state that the tool is safe, has no side effects, or detail what the reference contains or returns. The transparency is adequate but not rich.

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 exceptionally concise, consisting of two short sentences that earn their place. It leads with the action and resource, then adds the temporal usage hint. There is zero wasted text, and the structure is effective for quick scanning.

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

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

For a zero-parameter reference tool, the description covers the essential context: what it does and when to call it. It doesn't explain what TapScript notation is or what happens on repeated calls, but these are likely known or not critical for invocation. The description is complete enough for its simplicity, though a bit of extra detail on the reference's content would elevate it.

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

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

The tool has zero parameters, so the baseline for parameter semantics is 4. The description adds no parameter-specific meaning, but none is needed since the schema has no properties. The tool is simple and the description does not need to compensate for undocumented 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 clearly states the tool's function: 'Read the TapScript notation reference.' This is a specific verb+resource pairing that distinguishes it from sibling tools like directive_reference and stage_reference by explicitly focusing on notation. The purpose is unambiguous and immediately identifiable.

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 timing guidance: 'Call this before writing notation for the first time in a session.' This tells the agent when to use the tool. However, it does not mention alternatives or exclusions, so it lacks the full 'when-not/alternatives' guidance that would earn 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?

No annotations are provided, so the description carries the full burden. It transparently lists the kinds of information reported (platform, libraries, soundfonts, MIDI ports, audio playback, network), implying a read-only inspection of host capabilities. However, it does not explicitly state whether it has side effects or requires any setup, so it is not fully transparent about operational behavior.

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

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

The description is two sentences, front-loaded with the core purpose and then a usage directive. Every phrase adds value, with no filler or repetition.

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 simplicity (no params, no output schema), the description provides sufficient information about what it reports and when to use it. It could be more detailed about the response format, but the listed categories give the agent a clear picture of expected information.

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

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

The tool has no parameters, and the schema is empty, so schema coverage is effectively 100%. Per the rubric, a 0-parameter tool gets a baseline of 4 since there are no parameter semantics to clarify.

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 'Report' and clearly defines the resource as 'what this machine can do', listing concrete categories (platform, libraries, soundfonts, MIDI ports, audio playback, network). This distinguishes it from siblings like analyze_features or read_library, which focus on musical content rather than host capabilities.

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 final sentence explicitly states when to use the tool: 'Use it before choosing how to render or connect.' This gives clear contextual placement, though it does not name specific alternative tools or exclusions, hence a 4 rather than 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?

With no annotations, the description carries full burden, but it only states a generic read action without disclosing behavioral details such as encoding, error handling, or constraints. The minimal wording does not enrich beyond the tool name.

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

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

The description is a single, short, front-loaded sentence with no unnecessary words, perfectly suitable for a simple tool.

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

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

For a simple one-parameter read tool without annotations or output schema, the description is adequate, specifying the resource type (text file) and location (working directory/project). It may lack details like return format or error behavior, but these are less critical for a basic read 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?

The schema has 100% coverage with the parameter description 'Path to read,' which is minimal. The tool description adds context that the path is relative to the working directory or project, providing slightly more meaning than the schema alone.

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 reads a text file from the working directory or project, providing a specific verb and resource. However, it does not explicitly distinguish itself from sibling tools like read_library or ensemble_read, so it lacks explicit sibling differentiation.

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

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

The description provides no guidance on when to use this tool versus alternatives. 'Working directory or project' implies a scope but no explicit comparison or exclusion of other read 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?

With no annotations provided, the description must carry the burden. It clearly indicates a read-only operation but does not disclose potential errors, permission requirements, or return value semantics beyond the implicit file content.

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

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

One clear, front-loaded sentence with no redundancy. Each word contributes to understanding the tool's function.

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 single-parameter read tool, the description is adequate but leaves out return format and error behavior. Without an output schema, the description could be more explicit about what is returned or what happens if the file is not found.

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% (parameter 'name' is described as 'Library entry name or title'). The tool description repeats 'by name or title' but adds no additional semantic meaning 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 uses a specific verb ('Read'), identifies the resource ('one file from the bundled notation library'), and clarifies lookup by 'name or title', distinguishing it from sibling tools like read_file and search_library.

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

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

No explicit guidance on when to use this tool versus alternatives such as read_file or search_library. The description implies usage for bundled-library files but does not state exclusions or prerequisites.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It indicates a mutation ('append') but does not mention permanence, reversibility, permissions, or any side effects. This is a significant gap for a state-changing 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?

The description is a single, clear sentence that front-loads the action and purpose. It contains no filler or redundant information, earning the highest score for 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?

For a simple tool with one parameter and no output schema, the description is adequate but sparse. It does not mention what the build journal is, whether it must already exist, or what happens after the append, which might be needed for complete 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?

The input schema fully describes the only parameter 'note' as 'What was decided and the reason.' The description adds no additional meaning beyond restating this, so it meets the baseline 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 uses a specific verb 'Append' with a clear resource 'build journal', and further clarifies the purpose as 'recording a decision and why it was made.' This clearly distinguishes it from sibling tools like write_file or ensemble_log, which have broader or different scopes.

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 no explicit guidance on when to use this tool versus alternatives, nor any exclusions or situational context. It simply states what it does, leaving the agent to infer when it should be used.

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

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

With no annotations, the description carries the burden of disclosing behavior. 'Search' and 'reference material' convey a read-only lookup, and the searchable dimensions are named, but the description does not disclose result format, matching behavior (fuzzy vs exact), or any rate limits. This is adequate but thin for a search 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?

The description is a single, front-loaded sentence that wastes no words. It immediately communicates the action, target, and search scope.

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

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

The tool is simple with two parameters fully documented in the schema, and the description covers the core purpose and search dimensions. While there is no explicit mention of return values or pagination, the scope is sufficiently bounded for a straightforward search 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% (query and limit are described in the schema), which warrants a baseline of 3. The description adds value by clarifying that the query can match title, key, or style, giving semantic meaning beyond the schema's 'What to look for.'

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') with a clear resource ('bundled notation library') and search dimensions ('by title, key or style'). This distinguishes it from siblings like read_library and notation_reference, which suggest broader or different access to the same library.

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

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

The description provides clear context: it is for finding reference material in the bundled library via title, key, or style. It implies when to use it (targeted search) but does not explicitly contrast with sibling tools such as read_library or state when not to use it.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool lists profiles with timing and attack placement info, implying a read-only operation. However, it does not mention whether the list is exhaustive, any limitations, or the return format, which would be valuable for transparency.

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 sentence, front-loaded with the verb 'List', and contains no redundant words. Every word adds value, efficiently conveying both the action and the content of the result.

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

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

For a zero-parameter list tool with no output schema, the description covers the essential return value (list of profiles) and the key fields (duration, ear placement). It could explicitly state that the output is a list of names or that these are available options, but the simplicity of the tool makes this adequate.

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

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

The tool has zero parameters, so schema_description_coverage is trivially 100% and no parameter explanation is required. The description adds domain context but doesn't need to describe parameters, fitting the baseline for 0-parameter tools.

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 'List' and identifies the resource as 'instrument speech profiles' within the context of '[Stage] block', clearly stating what the tool does. It further details the output content (duration and ear placement), making it unambiguous and distinct from generic list 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?

The description provides no guidance on when to use this tool versus sibling tools like stage_reference or analyze_features. It implies usage in the context of Stage blocks but does not state conditions, exclusions, or alternatives, leaving the agent without direction for tool selection.

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

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

With no annotations provided, the description carries the transparency burden. It clearly indicates a read-only operation ('Read') and frames itself as a prerequisite ('Call this before...'), implying no side effects. It also states the content scope, which adds context beyond a bare 'Reference' label.

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 filler. The first sentence front-loads the verb and resource, and the second sentence provides the usage context. Every word contributes value.

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 parameterless reference tool with no output schema, the description covers everything: what it provides (Stage block writing guidance), its content areas, and when to call it. No additional information is needed.

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

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

The tool has 0 parameters, so the baseline is 4. The description doesn't need to explain parameters, and the empty schema is self-explanatory. There is nothing more to add.

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 ('Read') and resource ('[Stage] block'), and elaborates on the contents: 'positions, listeners, speech profiles and feel'. This clearly distinguishes it from sibling reference tools like directive_reference and notation_reference, which target different blocks.

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 gives explicit timing/context: 'Call this before writing arrival-centric timing for the first time in a session.' This tells the agent when to invoke it. However, it does not mention alternatives or explicit when-not-to-use, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does mention the side effect 'writing the result next to it', which clarifies output placement, but it omits details like whether the original is modified, how the result file is named, or what happens on conflict. This is partial transparency, not comprehensive.

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 one concise sentence, front-loaded with the verb, and contains no filler words. Every phrase ('notation file', 'another key', 'writing the result next to it') carries necessary information.

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

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

For a simple tool with only two required parameters and no output schema, the description provides the essential context: what action it performs and where output goes. It is brief but adequately complete for an agent to invoke correctly, though it could benefit from naming the result file format.

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

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

Schema coverage is 100% and both parameters (path and key) have descriptions. The description adds no additional semantic meaning beyond what the schema already provides, so the baseline score of 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 starts with the specific verb 'Transpose' and clearly identifies the resource ('notation file') and the action's scope ('to another key'). This uniquely distinguishes it from sibling tools like write_score or compile_score, which serve different purposes.

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 when to use this tool—whenever a notation file needs to be transposed—but does not explicitly contrast it with alternatives on the sibling list. There is no when-not-to-use guidance or reference to other tools, so usage context is only weakly 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool executes specs and reports pass/fail outcomes, but it does not mention potential side effects, execution duration, or how failures are reported (e.g., exit codes or output structure). This is adequate but not rich.

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 short, front-loaded sentences with no filler. 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?

This is a simple tool with one optional parameter and no output schema. The description states what it does and when to use it, and though it doesn't detail the output format, 'report what passes and what fails' is sufficient for basic 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 description covers 100% of the single optional 'tag' parameter, so the baseline is 3. The tool description does not add additional parameter context, but none is needed given the schema is self-explanatory.

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 ('Run') and names the resource ('the project's specs'), and clarifies the outcome ('report what passes and what fails'). This clearly differentiates it from sibling tools like compile_score or analyze_features, which serve other purposes.

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 gives explicit guidance on when to use it: 'Use this after making a change to check whether it worked.' It does not mention exclusions or alternative tools, but the context is sufficiently clear.

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

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

With no annotations, the description must disclose behavior; it mentions creating parent directories, which is a useful side-effect. However, it does not state whether existing files are overwritten, nor any other safety or error 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?

A single sentence that is direct and front-loaded, with no filler. It communicates the action, target, and a key side-effect 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?

For a simple write tool with two parameters and no output schema, the description covers the core purpose and one behavioral detail. It is adequate but not exhaustive—missing overwrite semantics and usage alternatives, though these are lower priority for such a 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?

Both parameters are fully described in the schema, and the description's phrase 'text file' aligns with content being a string. The description adds no additional parameter-level semantics beyond the schema, so the baseline for high coverage 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 writes a text file to the working directory, using a specific verb and resource. It also notes the parent-directory creation behavior, which distinguishes it from other write tools like write_score.

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—writing text files to the working directory—but does not explicitly compare with sibling tools or provide when-not/exclusion guidance. It is clear enough for basic selection but lacks explicit alternative 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?

The description discloses that notation is parsed first and the result reports any problems, which is a behavioral trait beyond the schema. However, no annotations are provided, and the description does not mention overwrite semantics, permissions, or return format, leaving some transparency gaps for a 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?

The description is two concise sentences, front-loaded with the core purpose and immediately followed by a valuable behavioral note and usage recommendation. Every sentence earns its place 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?

For a simple two-parameter tool with no output schema, the description covers purpose, parsing behavior, and usage guidance. It lacks a detailed description of the return format, but the mention of 'reports any problems' gives some indication, making it mostly complete.

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

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

Both parameters are fully described in the schema with 100% coverage, so the description does not need to add parameter details. The description's mention of 'notation' and '.tap file' slightly reinforces the schema but does not add significant new meaning.

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

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

The description clearly states the tool writes TapScript notation to a .tap file, using a specific verb and resource. It also distinguishes from sibling write_file by explicitly saying 'use this rather than write_file for music,' which 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 explicitly provides an alternative: 'use this rather than write_file for music.' This gives clear when-to-use guidance and names the sibling tool, satisfying the highest level of usage guidance.

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