GMA2 MCP

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation3/5
Many tools have overlapping purposes (e.g., multiple variable setters, numerous effect control tools, and many executor actions). Descriptions are clear, but the sheer number and similarity create ambiguity for an agent.
Naming Consistency3/5
Naming follows a verb_noun pattern in snake_case but with notable inconsistencies: some verbs are standalone (locate_fixtures, next_fixture), some tools have a '_tool' suffix (delete_macro_tool, sync_effects_tool), and one is just 'capabilities'.
Tool Count2/5
101 tools is excessive for a single server. While the domain is broad, many operations could be consolidated (e.g., effect parameters split into 9 separate tools). This overwhelms the agent.
Completeness4/5
The tool set covers most major workflows: patch, groups, cues, presets, macros, effects, timing, executor control, timecode, MIDI, variables, and show management. Minor gaps exist (no delete_sequence tool, but create_song_objects partially covers it).
Average 3.7/5 across 100 of 101 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 30 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavioral traits. 'Temporarily activate' is vague—does it destructively change state? Is it safe? There is no mention of side effects, return value meaning, or permissions. The description lacks transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: 4 lines with the main purpose upfront. It efficiently states the action and parameters without extraneous text. While it could be expanded, it is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity among many executor tools, no annotations, and an output schema declared, the description fails to provide necessary context. It does not explain the concept of temporary activation, how it interacts with other executor states, or what the return string means. The description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds minimal semantics: 'executor_id: Executor number' and 'page: Optional page number for page-qualified addressing'. It does not explain valid ranges, the concept of page-qualified addressing, or how to use the parameters effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Temporarily activate an executor', specifying a verb and resource. However, among sibling tools like flash_executor, top_executor, stomp_executor, etc., it does not differentiate what 'temporarily activate' means compared to them, making the purpose somewhat ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, no prerequisites, and no context for scenarios. It fails to help an agent decide between this and similar executor tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 only states 'Fix (lock)' without explaining what locking entails—whether it's reversible, if it prevents modifications, or what side effects occur. The lack of detail reduces transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is front-loaded with the action. However, it is so brief that it may be under-informative, but conciseness itself is a strength.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no annotations, output schema exists), the description should at least explain the parameter and the outcome of locking. It fails to provide sufficient context for an agent to confidently select and invoke this tool among many selection-related siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter 'target' with no description, and schema description coverage is 0%. The tool description does not explain what 'target' does—it might limit the lock to a specific fixture, but this is unclear. The agent cannot infer the parameter's purpose from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Fix (lock) the current fixture selection.' The verb 'Fix' is clarified by 'lock', making it specific. While it does not explicitly distinguish from siblings like 'align_selection' or 'invert_selection', the action of locking is unique enough to infer differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives, nor does it mention prerequisites or scenarios where locking is appropriate. This leaves the agent without guidance on optimal invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description labels the tool as 'destructive' but provides no details on side effects (e.g., deleting associated cues), required permissions, or reversibility. Without annotations, more behavioral context is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence) and to the point, but lacks necessary detail. It is concise but under-specified for a deletion tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature and single parameter, the description should explain consequences (e.g., does it also remove from cues? Is it permanent?) and required state of the fixture. It falls short of being complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain the fixture_id parameter (e.g., how to obtain it, what range of values are valid). The schema states it's an integer, but no additional meaning is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and resource (fixture from patch) with a note that it's destructive. It distinguishes from sibling tools like clone_fixtures, park_fixture, and unpark_fixture by indicating a permanent removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention prerequisites (e.g., fixture must be unparked?) or situations where other tools might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It mentions the fan pattern but does not disclose behavioral traits such as whether it is destructive (overwrites values), requires authentication, or has side effects. The lack of detail on what happens to existing values is a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with 12 words, front-loading the verb and resource. It is concise but may sacrifice clarity for brevity. Every word contributes, but jargon ('fan first-to-last') might be opaque to some agents.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one optional parameter and an output schema (not shown), the description should explain the parameter's effect and what the output contains. It fails to do so, leaving the agent with insufficient context to invoke the tool correctly. The description is incomplete for a parameterized tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter 'target' with no description, and the tool description does not explain its purpose. Schema description coverage is 0%, and the description adds no semantic value to the parameter. The agent cannot infer what 'target' refers to (e.g., target value, attribute, or fixture).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool aligns attribute values across selected fixtures with a fan first-to-last pattern. It uses a specific verb and resource, helping distinguish it from sibling tools like set_fixture_attribute or apply_effect. However, the term 'align' could be more explicit about the nature of the alignment (e.g., gradient or spread).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fan alignment across fixtures but does not provide explicit guidance on when to use this tool versus alternatives like set_fixture_attribute for uniform values or apply_effect for effects. No when-not-to-use or prerequisite information is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions 'clean removal' and 'respecting tracking', but does not clarify side effects, authorization needs, or what happens to the executor's current state. This is insufficient for a mutation operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and follows a standard docstring format with Args and Returns sections. Every sentence adds information, though the Returns section could be more specific than 'Operation result message'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple with two params and an output schema. The description adequately explains the core function but leaves gaps: it does not explain the return value format, interpret 'respecting tracking', or cover edge cases. The output schema exists but the description does not leverage it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. The Args descriptions add minimal value: 'Executor number' for executor_id is redundant, and 'Optional page for page-qualified addressing' is cryptic. It does not clarify the role of page or its interaction with serving.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Release an executor' and adds context with 'clean removal from output, respecting tracking'. It distinguishes the tool from other executor operations like 'assign_to_executor' or 'flash_executor', though the jargon 'respecting tracking' could be clearer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 its siblings (e.g., stomp_executor, swop_executor). The description does not mention prerequisites, conditions, or when to avoid using it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only states the basic action without mentioning side effects, prerequisites (e.g., effect selected), or whether this overrides previous assignments.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no extraneous words. Efficient, but could add a bit more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 an output schema (not shown), the description is minimally complete. However, it lacks context about prerequisites, side effects, or typical use cases. Adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (parameter has a title but no description). The description does not explain what 'group_id' refers to or how to obtain valid values. With only one parameter, more context is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action: assign the effect to a speed group for synchronized control. It uses a specific verb and resource, but does not differentiate from siblings like 'set_effect_speed' or 'sync_effects_tool'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Lacks context such as prerequisites or typical scenarios for using speed groups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It states 'Assign a sequence to an executor' but does not specify whether this overwrites existing assignments, requires the executor to be free, or any side effects. For a mutation tool, this is insufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a one-line summary, followed by structured Args/Returns/Example sections. Every component earns its place. The example is helpful. There is no extraneous text, and the structure makes information easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two integer parameters and an output schema (return string), the description is adequate in providing an overview and example. However, it lacks context about preconditions, side effects, and how this tool fits among siblings. Given the number of sibling tools related to executors and sequences, more context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% coverage, so the description should add meaning. It does: it interprets 'sequence_id' as 'Sequence number' and 'executor_id' as 'Target executor number', and provides an example (1 and 6). This adds basic semantics beyond the schema titles and types, but lacks format or constraints (e.g., ranges, required permissions).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Assign a sequence to an executor'. This is a specific verb and resource, and it distinguishes the tool from sibling tools like 'execute_sequence' (which runs a sequence) or 'release_executor' (which removes an assignment). The purpose is immediately clear and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It includes an example but does not explain the context or prerequisites (e.g., when to assign vs execute vs control). Without such guidance, an AI agent may struggle to select this tool appropriately among the many related sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. While it mentions 'destructive', it does not elaborate on whether deletion is reversible, what happens to fixtures in the group, or if there are side effects on cues or sequences. The output schema exists but is not described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (one phrase), which is concise but lacks necessary detail. It is front-loaded with the action and resource, but the brevity borders on under-specification. A moderate score of 3 reflects that it is not verbose, but could be improved.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's single parameter, lack of annotations, and rich set of sibling tools, the description is incomplete. It does not explain the return value (despite an output schema existing), error states, or how the deletion affects related data. The agent lacks sufficient context to use this tool safely and effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has only one parameter 'group_id' with no description, and schema description coverage is 0%. The tool description does not explain that 'group_id' is the identifier of the group to delete or how to obtain it. This leaves ambiguity for the AI agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'delete' and the resource 'fixture group', with a parenthetical '(destructive)' that further distinguishes it as a dangerous operation. This differentiates it from sibling tools like 'create_fixture_group' or 'list_groups'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, such as when to delete a group versus modifying it. It does not mention prerequisites (e.g., the group must exist) or suggest alternative tools for non-destructive operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 states the action but does not explain what setting an executor to 'top priority' entails, whether it is reversible, how it affects other executors, or what the return message contains. Critical side effects and operational context are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short: one sentence plus inline parameter definitions. It is efficient with no wasted words. However, the structure could be improved by separating parameter descriptions or using bullet points, but it is still concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the large number of sibling tools and the lack of annotations, the description is incomplete. It does not address return value format, preconditions, error conditions, or how this tool fits into the broader workflow. The output schema exists but is not described, leaving the agent without critical usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal meaning beyond the schema: 'executor_id: Executor number' and 'page: Optional page for page-qualified addressing.' It clarifies the type of executor_id (number) and introduces the concept of page addressing, but it does not explain valid values or how 'page-qualified addressing' works. With 0% schema description coverage, the description should provide more, but it offers some help.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Set an executor to top priority (Top).' It specifies the verb 'set' and the resource 'executor', making the purpose understandable. However, it does not differentiate from sibling executor tools like 'assign_to_executor' or 'control_executor', missing context on what 'top priority' specifically means.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. There is no mention of prerequisites, context, or exclusions. The sibling list contains many executor-related tools, but the description offers no direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It only states 'destructive', but fails to disclose critical behavioral traits such as whether the operation is irreversible, requires specific permissions, or has side effects on other entities.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the core action. The example is useful and integrated. However, it could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema and many sibling tools, the description is too sparse. It lacks details on error handling, prerequisites, and the exact behavior when deleting a preset. For a destructive operation, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides an example for 'preset_type' ('color', 'dimmer'), but does not explain 'preset_id' or the format/constraints. This adds partial value, but incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete a preset'), the resource ('preset'), and marks it as destructive. The example 'e.g. 'color', 'dimmer'' adds specificity and helps distinguish from sibling tools like 'apply_preset' or 'store_preset'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, no prerequisites, and no explicit when-not-to-use advice. The only hint is 'destructive', which implies caution but does not provide actionable usage guidelines.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description labels the action as 'destructive', indicating it is a mutation with potential data loss. However, it does not elaborate on side effects, authentication needs, or whether the deletion is permanent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the action and destructiveness. It is concise but lacks structured details like prerequisites or examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 an output schema, the description minimally covers the purpose and destructiveness. However, it does not explain the deletion process, reversibility, or what happens to associated data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not provide any additional meaning for the show_name parameter beyond what is already in the schema. Schema coverage is 0%, and the description adds no context on the parameter's format, constraints, or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (delete), resource (show file), and location (console drive). It distinguishes this tool from sibling tools like list_shows_tool, new_show_tool, and load_show_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use or not use this tool. No mention of prerequisites, alternatives, or context for deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must fully disclose behavior. It only states the basic action without specifying whether other fixture attributes are affected, if the operation is reversible, or if it requires specific permissions. For a potentially destructive move, more detail is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that gets straight to the point. However, it could be more efficient by also including a hint about context (e.g., 'Use to reset positions').
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the zero parameters and existence of an output schema, the description adequately covers the basic operation. However, it lacks behavioral context (e.g., effect on other attributes, whether it's a destructive reset), which is needed for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds meaning by clarifying that the tool acts on 'selected fixtures' and sends them to 'home/default position', which aligns with the parameterless operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Send') and the resource ('selected fixtures') with a specific outcome ('to home/default position'). However, it does not differentiate from sibling tools like 'park_fixture' or 'set_fixture_value' that might also move fixtures.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as 'park_fixture' or 'set_fixture_value'. The term 'Locate' is mentioned in parentheses but without explanation of context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It only states it sets effect speed, a write operation, but lacks details on range, validation, side effects, or success/failure outcomes. This is insufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but omits essential information. It achieves brevity at the cost of completeness. Could be restructured to include parameter details without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only one required parameter and no output schema description (though output schema exists), description lacks example, validation rules, or success indication. The tool's behavior is under-specified for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet description adds no meaning to the 'value' parameter. It does not specify unit (seconds), range, constraints, or typical values. The parameter is left completely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states clear verb 'Set', resource 'effect speed', and unit 'seconds', distinguishing it from sibling tools like set_effect_speed (likely BPM/Hz). It explicitly mentions being an alternative, clarifying its specific role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions 'alternative to BPM/Hz' implying when to use seconds, but does not explicitly state when not to use or list alternatives like set_effect_speed. Provides directional guidance but not full exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should convey behavioral traits. It only states 'Toggle' without explaining side effects (e.g., whether it resets other states, if it is destructive, or permissions needed). The return value message is mentioned but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, with two brief sentences. While concise, it could include more useful information without sacrificing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 details), the description is borderline adequate. It fails to explain the term 'grand blackout' or provide any context among sibling toggle tools, leaving room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to add parameter information. The baseline of 4 is appropriate as there is nothing to clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Toggle') and the resource ('grand blackout state'), distinguishing it from sibling toggles like toggle_blind. However, it does not explain what 'grand blackout' means, which could be ambiguous for new users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as toggle_blind or toggle_highlight. The description lacks context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as required permissions, side effects (e.g., does toggling preview clear the programmer?), or whether the operation is reversible. Only the basic toggle action is stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using a clear Args/Returns structure. Every sentence adds value, though it could be slightly more compact. It front-loads the purpose in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and an output schema labeled as present but not shown, the description adequately explains parameters and the return type as a string. However, it lacks context on side effects, preconditions, or postconditions, making it incomplete for a tool that modifies state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining each parameter in the 'Args' section: executor_id, page, and edit_mode. It adds meaning beyond the schema by describing the effect of each parameter, such as 'Optional page for page-qualified executor addressing'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool toggles preview mode and explains it visualizes output without affecting DMX. It is a specific action on a distinct resource, differentiating it from the many sibling tools that deal with fixtures, macros, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description assumes the user knows when to toggle preview, which limits its helpfulness for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It describes a mutation ('Apply') but does not mention side effects (e.g., whether it overrides existing effects, requires permissions, or is reversible). This lack of detail is insufficient for an agent to understand the tool's impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, fits in a few lines, and includes an explicit prerequisite, parameter description, return type, and example. The main sentence is front-loaded. However, the 'Args' and 'Returns' sections are somewhat redundant given the schema, but they don't add excessive length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and only one parameter, the description covers the basic purpose and prerequisite but lacks details about return values (output schema exists but is not described), error cases, or behavioral context like whether the effect applies immediately or requires confirmation. It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter, effect_id, has no description in the schema (0% coverage). The description adds minimal meaning: 'Effect number from the effect pool' and an example 'Apply effect 5'. This explains what the parameter represents but provides no constraints (e.g., valid range) or format details, leaving room for ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Apply a predefined effect') and the target ('to the current fixture selection'). It distinguishes from sibling tools like set_effect_speed which modify effect parameters rather than apply a stored effect. However, it could be more specific about what 'apply' means (e.g., start the effect, load parameters).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states a prerequisite: 'Fixtures must be selected first using set_fixture_value or create_fixture_group.' However, it does not provide guidance on when to use this tool versus sibling effect-modification tools (like set_effect_speed), nor does it mention when not to use it or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and only a single verb, the description fails to disclose behavioral traits such as whether the operation is destructive, reverts on next action, or affects stored selections. The minimal text leaves the agent to infer behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no extraneous words. It is appropriately concise for a simple toggle operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal but largely sufficient for a straightforward tool with no parameters. However, it lacks detail on the exact outcome (e.g., what 'invert' means for fixture selection) and does not leverage the existence of an output schema to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so the description needs no additional parameter explanation. The baseline score of 4 is appropriate as no parameter-related value is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'invert' and the resource 'current fixture selection', making the tool's purpose unambiguous. However, it could further clarify that 'invert' means selecting all unselected fixtures and deselecting currently selected ones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No information is provided about when to use this tool versus alternatives like 'next_fixture' or 'fix_selection'. The description gives no context for appropriate usage or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as side effects, preconditions (e.g., a selection must exist), or what happens if no previous fixture is available. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: a single sentence that communicates the essential purpose without any filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple navigation tool with no parameters and an output schema, the description is adequate but lacks detail on what 'step to' means operationally and whether it returns any information. Could be more helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage is 100%. The description adds meaning by explaining the tool's effect on the selection, going beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (step to) and resource (previous fixture in current selection). It is specific enough, though it does not explicitly differentiate from the likely sibling 'next_fixture', but the name itself implies direction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 over alternatives like 'next_fixture' or 'locate_fixtures'. The description provides no context for appropriate use cases or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description is the sole source for behavioral traits. It does not disclose side effects such as whether the programmer is cleared after storing, whether existing cues are affected, or if authorization is needed. It only mentions a return message, leaving significant gaps in transparency 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a single-purpose sentence, followed by a parameter list, return type, and examples. It is concise without unnecessary words, and the purpose is front-loaded. Each section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema (returns str) and parameter descriptions, the tool is fairly complete for a store operation. Examples clarify typical usage. However, it misses behavioral context like side effects on programmer state, which would elevate it further. Still, it is not incomplete given the tool's straightforward nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description provides meaningful explanations for all five parameters: cue_id as 'Cue number to store', name as optional, merge as 'Merge new values into existing cue', overwrite as 'Overwrite existing cue entirely', and noconfirm as 'Suppress store confirmation pop-up'. This adds clear semantics beyond the schema's type/default values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Store the current programmer state as a cue', identifying the verb (store) and resource (programmer state as a cue). It distinguishes the tool's core function from siblings like store_cue_across_sequences, but does not explicitly differentiate within the description, though the tool name itself provides context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides examples but lacks explicit guidance on when to use this tool versus alternatives like store_preset or store_cue_across_sequences. No mention of prerequisites, when merge vs overwrite should be used, or when noconfirm is appropriate. This leaves the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description discloses basic actions but lacks details on side effects, permissions, or state changes. Does not describe return value beyond 'Operation result message'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with Args, Returns, Examples. Front-loaded purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all parameters, actions, and return type. With output schema present, explanation of return value is sufficient. Missing prerequisites but adequate for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, description adds meaning: action lists allowed values, cue_id is clarified as required for goto. This compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it executes sequence operations (go, pause, goto). However, there is a sibling 'goto_cue_tool' that may overlap; no explicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like 'goto_cue_tool'. Examples show usage but do not exclude other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 states that any subset of parameters can be set (at least one required) and returns a string result. However, it does not disclose whether settings overwrite or merge with existing envelope, or if the operation is destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose, one for usage constraints, and one for return type. It is front-loaded with no extra words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 nullable parameters and no nested objects, the description covers the basic operation and return type. However, it lacks details about parameter semantics and does not provide enough context among many sibling effect tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 0% with no parameter descriptions. The description only repeats the parameter names (attack, decay, delay, fade) without adding units, ranges, or behavior. This does little to compensate for the lack of schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets effect envelope parameters (attack, decay, delay, fade) on the selection. It distinguishes from sibling tools like 'set_effect_phase' by naming specific parameters. However, it does not explain what an 'envelope' is, which may be unclear to agents unfamiliar with audio effects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'on the selection' implying the tool acts on a current selection, but gives no explicit guidance on when to use this tool versus alternatives. It does not state prerequisites or 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the action without revealing side effects, permissions, range constraints, or error behavior. The parameter hint 'percentage of cycle' is helpful 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, but includes an Args and Returns block that are redundant with the schema and output schema. It could be more concise by removing these formal sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, return value explanation is not needed. However, among many effect-setting siblings, the description lacks a fuller explanation of how width fits into effects. It is minimally complete for a simple setter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter 'width' has 0% schema description coverage, but the tool description adds meaning by specifying 'Width value (percentage of cycle)'. This clarifies the unit and domain, going beyond the schema's bare title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set') and resource ('effect width') for the current selection. It effectively distinguishes from sibling tools like set_effect_envelope or set_effect_form by specifically targeting width.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like set_effect_envelope or set_effect_form. There is no mention of prerequisites or context such as needing an active selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully disclose behavior. It omits details on side effects (e.g., whether it overrides a running cue), required permissions, or state changes beyond setting the fader level. The return type is mentioned but not fully explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose. The Args, Returns, and Examples sections are structured clearly with no wasted words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers core functionality and parameters adequately. The output schema exists but is not detailed; the description mentions a result message. Some additional context about executors and fader effect would improve completeness, but it's sufficient for a basic setter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% as the schema only provides titles and types. The description adds meaningful context: executor_id is 'Executor number' and value is 'Fader value (0-100)', including a range. This goes beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Set' and resource 'executor's fader level', making the purpose unambiguous. It distinguishes from sibling tools like set_executor_rate or set_executor_speed by specifying the fader level, but does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as control_executor or flash_executor. The description lacks context about prerequisites or use cases, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose side effects, permissions, or real-time behavior beyond 'livetempo matching'. Minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with purpose first, followed by parameter list and return type. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers essential aspects for a simple tool with output schema. Could benefit from more detail on 'live tempo matching' but sufficient as is.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description explains all three parameters including mode values ('set', 'half', 'double', 'reset'), which adds significant meaning over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it controls playback rate with 'live tempo matching', distinguishing it from sibling tools like set_executor_speed. However, 'control' is somewhat generic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like set_executor_speed. Lacks context about prerequisites or timing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that setting value to None deletes the variable and mentions the input dialog behavior. However, it does not address other behavioral aspects like persistence, permissions, or error handling. No annotations are provided to supplement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with Args and Returns sections, but includes some redundant technical details (e.g., 'SetUserVar'). It is adequately short but could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter tool with 3 parameters and an output schema (returning a string), the description covers the core behavior, including deletion and dialog. It does not mention persistence or scope, but is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Given 0% schema description coverage, the description adds meaningful context: var_name should start with '$, value can be numeric, text, or None, and input_dialog triggers a prompt. This goes beyond the raw schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets a user-profile-specific variable, using the verb 'set' and specifying the scope. However, it does not explicitly differentiate from sibling tools like 'set_variable' or 'add_user_variable', which are contextually similar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The description implies it is for user-specific variables, but lacks explicit when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. However, it only says 'Clear the programmer' without explaining what 'clear' entails (e.g., resets values, deletes data, irreversible). The behavioral impact is unclear, which is especially concerning for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: a single sentence for the action, followed by clear parameter documentation and examples. No unnecessary wording. However, the core description could benefit from slightly more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter) and the existence of an output schema, the description is adequate but leaves gaps. It does not explain the nature of the return value or the broader implications of clearing the programmer (e.g., whether it affects other parts of the system).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides the 'mode' parameter with a default but no enum or description. The description compensates by listing four specific values ('all', 'selection', 'active', 'default') and giving examples. This adds significant meaning beyond the schema's bare definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Clear the programmer') and provides specific modes ('all', 'selection', 'active', 'default') that define the scope. This verb+resource combination is distinct from sibling tools, as no other sibling explicitly deals with clearing the programmer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives. It lists modes but does not explain when each mode is appropriate or what the implications are. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It only states the action 'Delete' without disclosing irreversibility, required permissions, side effects, or impact on sequence. This is insufficient for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and structured with 'Args:', 'Returns:', and 'Examples:' sections. It is efficient, though the example line is minimal and could be more illustrative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with one parameter and a return type, the description covers the basics. However, it omits behavioral context like irreversibility, which is crucial for deletion, making it merely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions in schema), so the description must compensate. It defines 'cue_id' as 'Cue number to delete', adding meaning beyond the schema's 'Cue Id' title. However, it could specify valid ranges or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Delete') and resource ('a cue from the current sequence'), leaving no ambiguity about the tool's function. It is distinct from siblings like 'update_cue' or 'store_cue'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., 'update_cue' for modifications, or 'store_cue' for addition). No prerequisites or exclusions are provided, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as whether labeling overwrites an existing label, whether it requires specific permissions, or any side effects. The example is basic 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear structure (Args, Returns, Example). Every sentence adds value, though it could be slightly more streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 parameters and an output schema (returns str), the description covers the basics. However, it could mention whether labeling is idempotent or if it overwrites existing labels, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds clear, actionable meaning for both parameters: 'macro_id: Macro number to label' and 'name: Label text for the macro', which compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Label' and the resource 'macro in the macro pool', which distinguishes it from siblings like 'create_macro' (creating a new macro) and 'delete_macro_tool' (deleting a macro).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like 'create_macro', 'run_macro', or 'set_macro_line'. No prerequisites or exclusion criteria mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It indicates the return type (raw console response) but says nothing about side effects, permissions, error handling, or whether it is read-only. The description lacks critical behavioral context beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear first sentence stating purpose, followed by parameter descriptions and return type. No unnecessary text, and the structure is front-loaded with the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and moderate complexity (3 optional parameters, no output schema), the description fails to cover important context: what happens with invalid inputs, what the raw response format looks like, or how the 'selected executor' is established. An agent would need additional documentation to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description adds meaning for all three parameters: cue_id (specific ID or start of range), end_cue_id (end of range), sequence_id (sequence to list). However, it does not clarify the exact range semantics (inclusive/exclusive), what happens when only cue_id is given, or how the selected executor is determined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists cues on a grandMA2 console, distinguishing it from siblings like 'delete_cue' or 'goto_cue_tool'. It specifies it lists from the selected executor or a specific sequence if sequence_id is provided, which is a specific verb-resource combination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to list cues from an executor or sequence) but does not provide explicit when-not-to-use guidance or mention sibling tools like 'read_cue_info'. The usage context is clear from the purpose, but exclusions are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavioral traits. It only describes inputs and return type, but does not state if the operation is destructive, requires permissions, or has side effects (e.g., overwriting existing speed).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args, Returns, and Examples sections. It is concise but includes necessary details. However, the Args section partially duplicates schema info; could be more streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with 2 parameters and an output schema. The description covers inputs, return type, and examples. However, it lacks context on what 'current selection' entails (e.g., multiple fixtures, effect types) and any dependencies (e.g., an active effect).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds significant meaning: it explains that 'value' is a speed number, 'unit' can be 'bpm' or 'hz' (not an enum in schema), and notes default 'bpm'. This clarifies usage beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Set the effect speed for the current selection' with a clear verb ('Set') and resource ('effect speed'), and specifies scope ('current selection'). Among sibling tools like set_effect_phase, set_effect_range, etc., this uniquely identifies the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, when-not-to-use, or contrast with related tools like set_effect_speed_group or set_effect_seconds.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description is the sole source of behavioral disclosure. It only states that the tool controls speed and returns a result message, without mentioning side effects, permission requirements, or what happens in error cases (e.g., missing executor).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main purpose. The docstring format efficiently conveys parameter details and return type. However, it could be slightly more streamlined by omitting the generic 'Args' and 'Returns' headers.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic operation, parameters, and return type. It lacks details on valid speed values (e.g., if mode 'set' requires a separate parameter) and error handling. For a tool with 3 parameters and no annotations, this is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema has no property descriptions (0% coverage), the tool's docstring explains each parameter beyond type information: executor_id as 'Executor number', mode with possible values 'set', 'half', 'double', and page as 'Optional page for page-qualified addressing.' This adds significant meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool controls an executor's playback speed and mentions 'live tempo matching,' which distinguishes it from sibling tools like set_executor_rate or control_executor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as set_executor_rate or when not to use it. The phrase 'live tempo matching' implies a specific context but does not clarify exclusions or preferred scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It mentions that the tool 'first selects the fixture(s), then applies the attribute value' but does not discuss side effects, error conditions, or safety (e.g., destructive or read-only nature). This is insufficient 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear format: a one-line summary, a brief process note, an Args list with bullet points, a Returns line, and Examples. Each part serves a purpose without redundancy. Minor improvement could be removing the 'Args:' prefix since the schema already lists parameters, but overall well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters (3 required) and an output schema, the description covers the main points: what the tool does, parameters, return type, and examples. It does not detail output schema behavior but the output schema itself provides that. The description is complete enough for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions beyond titles and types (0% coverage). The description adds meaning by listing fixture_id as 'Fixtures number (or start of range)', attribute as 'Attribute name (e.g., "Pan", "Tilt", "Dimmer")', value as 'Value to set', and end_fixture as 'End fixture for range'. Examples clarify usage, compensating for the schema's lack of detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set a specific attribute on fixture(s)' and explains the selection-then-apply process. Examples like 'Set Pan to 128' clarify the purpose. It distinguishes from siblings like 'set_fixture_value' by focusing on attributes (e.g., Pan, Tilt) rather than generic values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool vs alternatives (e.g., set_fixture_value, park_fixture). However, the examples and parameter names (attribute, value, range) imply usage for setting parameter attributes on one or a range of fixtures. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 return type but does not mention side effects, permissions, or error conditions. The description adds minimal behavioral context beyond parameter semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear structure: purpose statement, usage note, parameter list, return type. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no required params, and no annotations, the description is adequate but lacks context such as typical values, effect on system, and scope of 'current selection'. It meets minimum viability but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description includes an Args section that explains each parameter (e.g., 'snap_percent: Snap percentage (hard-cut portion)'). This adds meaning beyond the schema titles, though units and ranges are missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it sets step/chase timing parameters for the current selection. It specifies the verb 'Set' and the resource 'step/chase timing parameters', but does not differentiate from sibling tools like set_cue_timing or set_effect_speed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a usage guideline: 'Provide any subset (at least one required).' However, it does not mention when to use this tool vs alternatives or 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that variables are global, can be deleted with None, and input_dialog prompts operators. However, it does not mention side effects, permissions, or the nature of the return message (beyond 'operation result message'). This is adequate but 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args, Returns, and Examples sections. It is concise yet includes helpful examples. No superfluous content, though the examples slightly lengthen it without being wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter tool, the description covers variable naming, value types, deletion, and operator prompt behavior. It mentions the return type, and with an output schema present (not shown), additional detail is unnecessary. It is complete for common use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It explains var_name should start with '$', value can be numeric, text, or None for deletion, and input_dialog triggers an operator prompt. This goes well beyond the schema's type-only information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets a global show variable with the verb 'Set' and resource 'global show variable'. Examples reinforce the purpose. However, it does not explicitly differentiate from sibling tools like set_user_variable or add_variable, missing an opportunity for clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use set_variable versus alternatives (e.g., set_user_variable, add_variable). The description focuses solely on mechanics without indicating context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 states the tool applies a preset (a mutation) but does not disclose side effects, authorization needs, or limitations such as what happens if the preset doesn't exist. It fails to add behavioral context beyond the obvious action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear one-line purpose, followed by structured Args, Returns, and Examples sections. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 required parameters and an output schema, the description is fairly complete. It covers the operation, parameter details, return type, and examples. However, it omits error conditions or prerequisites like requiring a valid selection, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description compensates by listing valid preset_type values (dimmer, position, gobo, etc.) and the integer preset_id, and includes usage examples. This adds significant meaning beyond the schema's bare types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb+resource structure: 'Apply an existing preset to the current selection.' It distinguishes from sibling tools (e.g., store_preset, delete_preset) by using the verb 'apply', which clearly indicates action, though it does not explicitly differentiate from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when there is a current selection and an existing preset, but it provides no explicit guidance on when to use this tool versus alternatives like store_preset or effect-related tools. No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It mentions returning a result message but does not describe side effects (e.g., whether 'kill' stops playback), required permissions, or if the operation is reversible. This is insufficient for a control tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with sections for Args, Returns, and Examples. Every sentence adds value, and the main purpose is front-loaded in the first line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers parameters and return type, but given the tool's potential impact (controlling executor state), it lacks context on error conditions, prerequisites, or typical use cases. It is moderately complete but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds significant meaning: it explains executor_id as 'Executor number' and action with enumerated values ('on', 'off', 'go', 'kill', 'toggle') plus examples. This compensates well for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool controls an executor with actions: on, off, go, kill, toggle. It lists these explicitly and provides examples, making the purpose unambiguous. It distinguishes from sibling tools that focus on setting properties (e.g., set_executor_fader) or other operations (e.g., release_executor).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists available actions but does not provide guidance on when to use this tool versus alternatives like flash_executor, release_executor, or stomp_executor. It lacks explicit context about when this tool is appropriate or not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose important behavioral traits such as whether the tool modifies show state, requires special permissions, or what happens on invalid tc_id. It only mentions return type without side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with a clear purpose statement, Args/Returns sections, and examples. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple control tool with two parameters, the description provides basic functionality. However, it lacks details on return values (e.g., success/error messages) and potential side effects, leaving some gaps for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at 0%, the description compensates well by defining tc_id as 'Timecode show ID' and listing valid actions with their meanings (e.g., 'go' means play). Examples further clarify usage, adding significant value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool controls timecode playback/recording and lists specific actions (go, pause, off, top, record) with examples. It differentiates from siblings like 'query_timecode' and 'control_executor' by focusing on timecode operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It does not specify prerequisites, when not to use it, or mention sibling tools like 'query_timecode' for reading timecode state.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that the tool selects a range of fixtures, saves them as a group, and optionally assigns a name. It also mentions the return type. However, it does not disclose whether overwriting an existing group is possible, which is a behavioral gap. Since no annotations are provided, the description carries full burden but is only partially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear summary, detailed explanation, parameter listing, and examples. It is concise and front-loaded, with no unnecessary sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters and returns a string message. The description covers the core functionality and provides examples, but lacks details on edge cases like overwriting existing groups or behavior when invalid fixture numbers are provided. It is adequate for basic use but incomplete for comprehensive understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 0%, meaning no descriptions in the schema. The description's 'Args:' section restates the parameter names and types almost verbatim from the schema, adding minimal additional meaning. For example, 'start_fixture: Starting fixture number' does not provide context beyond the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create a group containing a specified range of fixtures.' It uses a specific verb and resource, and is easily distinguishable from sibling tools like delete_group or list_groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides examples that imply usage scenarios (e.g., saving fixtures 1-10 as a group with an optional name), but does not explicitly state when to use this tool versus alternatives or mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description only states action and return type. No disclosure of side effects, error behavior, permissions, or what 'current selection' must be. No annotations provided to compensate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with clear structure: purpose sentence, then Args and Returns sections. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a single-parameter tool, but lacks context about selection requirements, effect state, and potential errors. Output schema exists but not exposed in description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has no description (0% coverage); description adds unit 'degrees' and example values, providing crucial context for the numeric parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Set the effect phase offset for the current selection', specifying verb, resource, and context. Distinct from siblings that set other effect parameters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use or when-not-to-use guidance provided. Does not mention prerequisites or alternatives among sibling effect tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'Toggle highlight mode' without disclosing side effects, toggling behavior (on/off?), or other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no redundancy. First sentence states purpose, second describes return value. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity and no parameters, the description is minimally adequate. However, it lacks details on return value behavior and toggling specifics, making it incomplete for an agent to fully understand the tool's effect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100%. The description adds no parameter information, but baseline for 0-param tools is 4 since the schema already covers it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Toggle' and resource 'highlight mode for fixture programming', clearly stating the action and object. It distinguishes from sibling tools like toggle_blackout, toggle_blind, and toggle_preview which toggle different modes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. There is no context on when highlight mode is appropriate or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It only states the assignment action and does not disclose side effects (e.g., overwriting existing assignments), error conditions, or the nature of the return message. The behavioral transparency is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a clear one-line summary followed by a structured Args/Returns section. Every element is relevant and no words are wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 simple integer parameters, no nested objects) and the presence of an output schema, the description adequately covers the core functionality. However, it omits any mention of error handling or slot validation, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to both parameters beyond the raw schema: 'tc_id' as 'Timecode show ID' and 'slot' as 'Timecode slot number'. With 0% schema description coverage, this compensation is valuable, though it lacks details like valid ranges or formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Assign'), the resource ('timecode show to a timecode slot'), and the purpose ('for cue triggering'), making the tool's function unambiguous and distinct from siblings like 'query_timecode' or 'control_timecode'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 vs alternatives. There is no mention of prerequisites or conditions for assignment, leaving the agent without context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions that the tool modifies an object by assigning a name, but it does not state whether it overwrites existing labels, requires special permissions, or has any side effects. The return type is specified, but overall transparency is moderate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the purpose, and includes an organized list of parameters and examples. A bit more structure (e.g., separating examples) would improve readability, but it is already efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the basics: purpose, parameters, and return value. However, it lacks mention of prerequisites (e.g., connection to grandMA2) and does not explain whether labeling is immediate or requires further steps. The presence of an output schema (though not shown) is acknowledged via the return statement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% coverage, so the description adds significant value by listing parameter names with explanations and examples ('object_type: Object type (e.g., "group", "cue")'). This clarifies meaning beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Assign a name label to a grandMA2 object' with a specific verb and resource. It distinguishes itself from sibling tools like 'label_macro_tool' or 'label_sequence_cue' by being a general labeling tool for any object type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 the many sibling labeling tools (e.g., label_cue_across_sequences, label_macro_tool). The examples illustrate typical usage but do not define selection criteria or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the basic action and parameters without disclosing side effects, error conditions, or safety (e.g., is it destructive?). For a non-destructive MIDI message, more detail on behavior would be expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a docstring with Args and Returns sections. It is relatively concise but could remove the Returns line since an output schema exists. The structure is clear and front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters and an output schema, the description covers the basics. However, it lacks usage context like when to use vs. send_midi_note, and the term 'Setup MSC channel' may be unclear to novices. For a technical user, it is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains controller (0-127), value (0-127), and channel (optional with default behavior). This adds meaning beyond the schema's type/title fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it sends a MIDI control-change message via the MIDI Out port. The verb 'Send' and resource 'MIDI control-change (CC) message' are specific. The sibling tools like send_midi_note and send_midi_program are distinct, so no confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a hint about the channel default ('uses the Setup MSC channel if omitted'), but lacks explicit when-to-use versus alternatives. It does not explain when to prefer this tool over other MIDI sending tools or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses return type but does not mention destructive or mutation traits, permissions, side effects, or reversibility. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args and Examples sections, but some redundancy exists (e.g., repeating parameter names in Args). Could be more concise, but front-loads purpose effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, 3 required, no enums, and presence of output schema, the description covers parameter semantics and return type. However, it lacks usage guidelines and behavioral context for a mutation tool, making it adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description's Args section explains each parameter beyond just titles: macro_id as 'Macro number', line as 'Line number within the macro', command with example, and pool with default. This adds meaningful context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set the command for a specific line within a macro', providing a specific verb and resource. It distinguishes from sibling tools like create_macro, read_macro_lines, and run_macro by focusing on setting a line's command.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through examples but does not explicitly state when to use this tool versus alternatives like read_macro_lines. No guidance on prerequisites (e.g., macro must exist) or 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool solos an executor with blackout on others and explains three modes (swop, swop_on, swop_go). However, it lacks details on permissions, side effects, or what happens to state, leaving some behavioral uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear one-line summary followed by parameter explanations and return type. It is front-loaded and avoids redundancy, though the docstring format could be slightly more streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and three parameters, the description covers purpose, parameters, and return value. However, it omits prerequisites, error handling, and deeper context for mode selection, which could help an AI agent in real-world use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds significant meaning beyond the input schema: it explains each parameter (executor_id, page, mode) and explicitly enumerates mode values with their behaviors. Since schema description coverage is 0%, this is crucial and well-handled.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Swop an executor (solo with blackout on others) — a live busking control.' It specifies the verb 'swop' and the resource 'executor' with context of soloing and blackout, effectively distinguishing it from sibling tools like stomp_executor or temp_executor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as stomp_executor or temp_executor. It only describes what it does without clarifying selection criteria or context of use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that numeric values are summed and text concatenated, and that the variable is user-profile-specific. However, it does not clarify whether the variable must already exist or if it is created on first use, nor does it mention potential errors (e.g., type mismatch). This is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 lines) with clear sections: a headline, behavioral rules, argument description, and return type. It is front-loaded with the core purpose and every sentence adds value. No redundant or verbose phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity and presence of an output schema, the description covers the basic behavior and return type. However, it lacks details about variable creation, error handling, and idempotency, which are important for a mutation tool. The sibling list suggests there are similar tools, but no comparative context is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema: it notes that var_name should start with '$', and explains how value type affects behavior (summed vs. concatenated). The schema lists types but lacks this context. Since schema coverage is 0% (no param descriptions in schema), the description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds to or extends a user-profile-specific variable. It specifies the resource ('user-profile-specific variable') and action ('Add to / extend'), and distinguishes from siblings like 'set_user_variable' by describing the additive behavior. The behavior for numeric (summing) and text (concatenating) values is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like 'add_variable' or 'set_user_variable'. The description does not mention prerequisites (e.g., variable must exist), nor does it contrast with setting vs. adding. An agent would have to infer usage from the sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose side effects, prerequisites, or error conditions. It minimally states the operation but omits behavioral impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, well-structured with header, args, returns, and examples. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with an output schema, the description covers basics but misses error handling, constraints, and behavioral context. Adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds basic meaning for each parameter (e.g., 'Target cue number') but lacks details on ranges, formats, or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it jumps to a specific cue, targeting an executor or sequence, which distinguishes it from sibling tools like store_cue or list_cues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context and examples but lacks explicit exclusions or comparisons to alternatives like execute_sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions listing and returns raw response, but does not disclose whether the tool is read-only, destructive, or requires any permissions. Minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two sentences for purpose and one parameter explanation. No fluff, front-loaded with main action. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (1 param, no required, output schema present), the description is adequate but could be more complete: e.g., mention ordering, behavior on empty result, or error scenarios. It doesn't cover edge cases or full behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'filter' has 0% schema description coverage. The description adds meaning by explaining it as an optional filter pattern with an example ('Mac*'). This adds value beyond the schema, though syntax details are minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'available show files', and the context 'grandMA2 console'. It distinguishes from sibling tools like 'load_show_tool' and 'new_show_tool' that operate on shows but do different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you want to see available shows) but does not explicitly state when to use this tool vs. alternatives or when not to use it. No mention of exclusion criteria or alternative tools for listing other resources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It does not specify what happens at boundaries (e.g., wrap-around, no effect) or how selection state changes. This lack of detail leaves the agent uncertain about side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence. It contains no redundant or extraneous words. Every word contributes to understanding the function, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple but lacks explanation of boundary behavior or prerequisites. Given the presence of an output schema (not shown), the description is adequate for basic use but incomplete for robust understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema coverage is 100%. The description adds no parameter information, but none is needed. It correctly states the action without requiring parameters, meeting the baseline for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Step to the next fixture') and the resource ('in the current selection'). The verb 'Step to' and noun 'fixture' are specific and unambiguous. The purpose is immediately understandable and distinguishes from sibling 'previous_fixture'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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 like 'previous_fixture' or 'locate_fixtures'. Usage context is implied but not detailed, e.g., no mention of behavior when at the last fixture or with an empty selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose non-obvious behaviors like prerequisites, side effects, or idempotency. It only states it retrieves data, which is implicit from the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise two short paragraphs with clear Args/Returns section. No redundant or extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers parameters and basic return concept, but output format is vague ('parsed cue info') and no expected keys are listed. With no output schema, more detail would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, description adds meaning: sequence_id is 'Sequence ID containing the cue', cue_id is explained with type guidance and example ('int or str for decimal cue numbers like "2.5"'). This compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Read cue information for a specific cue in a sequence' with specific verb and resource. It distinguishes from siblings like get_cue_annotation or list_cues by specifying details like label, fade time, and CMD field.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives. While the verb 'read' implies a safe query, no conditions or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits like state mutation or side effects. It only says 'Starts the specified macro' and returns a message, lacking detail on what changes occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with a clear structure: summary, parameter descriptions, return type, and examples, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers parameters and return type but lacks detail on error handling or edge cases like invalid macro_id, which would be important for an execution tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Given 0% schema description coverage, the description adds meaning by describing macro_id as 'Macro number to execute' and pool as 'Macro pool number (default: 1)', with example values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute a macro by ID' and mentions the Go+ command, which distinguishes it from other macro-related sibling tools like list_macros and create_macro.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides example usages but does not explicitly state when to use or avoid this tool, nor does it mention alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It warns that mode='overwrite' replaces existing target programming, which is a key behavioral trait. However, it does not disclose other side effects, permissions needed, or whether the operation is reversible. The return value is mentioned as a string but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a one-line purpose, a warning, and a structured parameter list. Every sentence serves a purpose, and the information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, the description adequately covers purpose, parameters, and a warning. It could explain what 'programming' includes and clarify that source_end/target_end are for ranges, but overall it's fairly complete for a mutation tool with 5 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It provides a clear Args section explaining each parameter's meaning, including the mode values 'default', 'overwrite', 'merge'. This adds significant meaning beyond the schema's minimal type info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool clones all programming from source fixture(s) to target fixture(s). The verb 'Clone' and resource 'programming' are specific, and the tool is distinct from sibling tools like copy_object or assign_appearance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. The description does not mention any prerequisites, when to prefer this over other cloning or copying tools, or 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full behavioral disclosure. It states it stores a sequence and page, but does not mention what happens if objects with the same ID already exist (overwrite vs error), or any other side effects. This leaves ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose, followed by structured sections (Args, Returns, Example). It is concise without being overly terse, though the pattern explanation could be integrated more tightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 2 parameters and an output schema that is not shown, the description covers the core creation behavior. However, it lacks details on idempotency, error cases, or concurrency implications, which are relevant for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning by specifying 'song_id: ID for both the sequence and page' and 'song_name: Name to assign to both objects'. This clarifies the shared use and compensates for the lack of schema descriptions. However, no constraints or formats are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'Create and label' and resource 'Sequence + Page pair for a song', distinguishing it from sibling tools like create_fixture_group or create_macro. It explicitly mentions the pattern of using same ID and name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates it is the 'standard pattern for per-song programming in music show workflows', which implies when to use. It does not explicitly mention when to avoid or provide alternatives, but the purpose is self-contained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the three modes (flash, flash_on, flash_go) and mentions 'momentary intensity bump', but does not detail state changes, whether the executor returns to previous level, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a one-line summary followed by a clean Args and Returns section. Every sentence is necessary and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 params, 1 required, output schema exists), the description covers the key parameters and behavior. It lacks information on prerequisites or error conditions but is adequate for a live control tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description's Args section adds necessary meaning: executor_id is 'Executor number', page gets 'Optional page number for page-qualified addressing', and mode lists the three options. This compensates well for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (flash) and resource (executor), and explains it's a 'live busking control', distinguishing it from other executor manipulation tools like set_executor_fader or release_executor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like stomp_executor, swop_executor, or temp_executor. The phrase 'live busking control' implies usage context but does not provide comparative decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description mentions it 'uses the generic list command' but does not disclose whether the operation is idempotent, read-only, has side effects, or requires special permissions. The name implies reading, but the description should explicitly confirm safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single purpose sentence, a brief explanation of the command, a special case note, and clear Arg definitions. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains return format ('dict with parsed label and raw response') and covers a key edge case (macro IDs). However, it lacks error handling information (e.g., what happens for invalid object_type or ID) and does not mention if all object types are supported as claimed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining parameter semantics: object_type is described as 'Object type (e.g., ...)' and object_id is clarified with the distinction between integer for most types and 'pool.id' string for macros. This adds significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Read the label/name of any grandMA2 show object.' The verb 'read' and resource 'label/name' are specific. It distinguishes from siblings like label_object (which writes labels) and read_cue_info (which reads cue-specific info) by focusing on reading labels for any object type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a note for macros about pool-qualified IDs, but does not explicitly state when to use this tool versus alternatives like label_object or read_cue_info. There is no guidance on when not to use it or which sibling tools to prefer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'Set fixture(s) to a dimmer value' with no disclosure of side effects, undoability, or permissions needed. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args, Returns, and examples. It is slightly verbose for a simple tool but every sentence adds value. Could be more terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers basic usage, parameter ranges, and return type. It lacks error handling or fixture existence checks, but is largely complete for the intended function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 0%, but the description adds meaning: fixture_id is 'Fixture number (or start of range)', value is 'Dimmer percentage (0-100)', end_fixture is 'Optional end fixture for range'. This fully clarifies parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set fixture(s) to a dimmer value' and provides examples for single and range fixtures. It distinguishes from siblings like set_fixture_attribute which handles other attributes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through examples (setting single or range of fixtures to a percentage) but does not explicitly state when to use this tool vs alternatives like set_fixture_attribute or apply_preset.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions using the 'Off command', but does not disclose side effects (e.g., whether it affects only programmer values or also fixture states), required permissions, or whether the operation is reversible. Minimal behavioral context beyond the core action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two precise sentences: the first states the primary purpose, the second describes the mechanism. No redundant information. Efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, straightforward action), the description is largely complete. It includes a return type, though no output schema is shown. Could briefly mention which effects are stopped (all? selected?) but current content suffices for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description needs no parameter explanations. Baseline is 4, and the description adequately covers the operation without needing to reference parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Stop all running effects for the current selection' and elaborates with 'Removes effect values from the programmer using the Off command.' This provides a specific verb and resource, distinguishing it from sibling tools like apply_effect or sync_effects_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for stopping effects on the current selection, but does not explicitly state when to use this tool versus alternatives (e.g., sync_effects_tool, apply_effect) or provide when-not-to-use scenarios. No guidance on prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only mentions resetting timing and aligning phase, but does not disclose side effects, requirements (e.g., permission), or what happens to effects that are not running. With no annotations, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences with no wasted words. It front-loads the action and explains the effect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema declaring a string return, the description is mostly complete for a simple action. However, it could mention whether synchronization is instantaneous or has duration, and if it only affects currently running effects. But overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the description need not add parameter info. Baseline 4 applies as the empty schema is fully covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Synchronize all running effects' with a specific verb and resource, and explains that it resets timing to align phase. This distinguishes it from sibling tools like stop_effects or set_effect_phase.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when wanting to align running effects, but provides no explicit guidance on when to use this tool versus alternatives like set_effect_phase or set_effect_speed. No when-not or context given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It explains the iteration over sequences and parameter constraints but does not disclose side effects, permission requirements, or behavior when parameters conflict (e.g., RGB and color both provided).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args, Returns, and Examples sections. It is slightly verbose but efficiently conveys necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no annotations, and no output schema, the description covers the main features but omits validation details (e.g., order of sequence_start/sequence_end) and conflict resolution between RGB and color inputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description fully explains all 7 parameters, including allowed values (e.g., RGB 0-100, hex codes) and provides examples, adding significant meaning beyond the schema's types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set appearance (color) on a cue across a range of sequences.' This specific verb+resource+scope differentiates it from sibling tools like label_cue_across_sequences and store_cue_across_sequences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides examples but no explicit guidance on when to use this tool versus alternatives. Usage context is implied but not clearly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosing behavior. It clearly states it iterates over sequences and labels a cue, and specifies the return type (a dict with 'commands_sent', 'count', and 'summary'). However, it does not mention whether labeling overwrites existing labels or if there are side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise, front-loaded with the main action, and uses a logical structure (description, iteration detail, args, returns, examples). However, the docstring-style re-statement of args is somewhat redundant given the schema. Still, it is not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (4 required parameters, no nested objects, no output schema), the description provides enough context: it explains the iteration, parameter semantics, and return value. It is complete for a basic labeling operation, though it could benefit from edge-case notes (e.g., if cue_id doesn't exist).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It lists and briefly explains each parameter (e.g., 'cue_id: Cue number to label (e.g., 1, 0.5)'), but lacks details on accepted ranges, format constraints, or default values. The examples provide context, but the explanation is minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Label a cue across a range of sequences.' It specifies the action (label), resource (cue), and scope (range of sequences), distinguishing it from siblings like 'label_macro_tool' or 'label_sequence_cue'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the iterative labeling behavior but does not provide explicit guidance on when to use this tool versus alternatives like 'label_sequence_cue' (for a single sequence) or 'appearance_cue_across_sequences' (for appearance). It lacks any 'when not to use' or conditional context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 states the return type (str, raw console response) but does not disclose safety (read-only), error handling, or performance characteristics. Minimal behavioral insight beyond the obvious listing operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two clear paragraphs: one for parameters and one for return value. No redundant information, front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, output schema exists), the description is largely complete. It covers the purpose, parameters, and return type. Minor gap: no mention of potential errors or limitations, but acceptable for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It explains variable_type with valid values ('show', 'user') and filter with an example pattern, adding meaningful semantics beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists show or user variables on the grandMA2 console, with a specific verb and resource. It distinguishes from sibling tools like add_variable and set_variable which perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to use the tool with the variable_type parameter and optional filter, but does not provide explicit guidance on when not to use it or alternatives. Usage is implied but not contrasted with other listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description discloses the action and examples but does not explain behavioral traits such as prerequisites (e.g., requires a selection), idempotency, side effects, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one action sentence, a clear Args section, a Returns note, and examples. No redundant or verbose content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple setter with one parameter. However, lacks context about how this tool fits into the broader effect system, return value details, or prerequisites, given no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds value by specifying the 'form' parameter accepts waveform names (e.g., 'sin', 'ramp') or numbers, providing examples beyond the schema's simple type string.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Set the effect waveform' and specifies the scope 'for the current selection', distinguishing it from sibling tools like set_effect_speed or set_effect_phase.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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 like set_effect_envelope or apply_effect. The sibling list implies this is for waveform type, but lacks when-to/when-not context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It includes a warning about modification and briefly explains each flag (merge, cueonly, tracking). However, it lacks detail on side effects, auth requirements, or error states. The flag meanings are minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a summary sentence, a distinguishing paragraph, an Args list, and Returns. It is concise with no superfluous content. The warning is effectively placed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters (1 required) and an output schema (string), the description explains the tool's purpose, differentiation from store, and flags. It lacks detail on return value format and error handling but is sufficient for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It lists parameters with one-line explanations ('Cue number to update', 'Add /merge flag'). While better than nothing, the explanations are very basic and do not fully clarify usage or valid values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and resource 'existing cue', and explicitly distinguishes itself from the sibling tool 'store' with the line 'Unlike store, Update merges programmer changes into an existing cue without re-storing.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description contrasts with 'store', giving a clear scenario when to use this tool instead. The warning about modifying existing programming advises caution. However, it does not mention other alternatives like delete_cue or store_cue_across_sequences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains the operation (assign, copy, reset) and return type but does not disclose side effects (e.g., overwriting existing appearance) or permissions needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose, then parameter details and examples. It is front-loaded and each sentence adds value, though the parameter list is lengthy due to tool complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all parameters thoroughly, provides examples, and mentions return type. However, it lacks discussion of error cases or responses, and no output schema details are provided beyond the return string.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates. It explains all 13 parameters with types, ranges, examples, and optional usage, adding significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool assigns an appearance (frame/background color) to grandMA2 pool objects or cues. This specific verb-resource combination distinguishes it from sibling tools like apply_effect or build_color_palette.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides examples but no explicit guidance on when to use this tool vs alternatives. Usage is implied by the narrow purpose, but the description does not cover prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it returns raw console output and mentions the List Group command. However, without annotations, it lacks explicit statement of read-only nature or side effects. The behavior is fairly transparent but could be improved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, using a clear docstring format with Args and Returns. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with an output schema, the description covers the essential behavior. It could mention that omitting both parameters lists all groups, but the context is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description compensates by explaining the meaning and usage of both parameters, including the range query relationship between group_id and end_group_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all defined groups on the grandMA2 console, with optional filtering by group ID. It distinguishes from sibling tools that create, delete, or annotate groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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 vs alternatives. Usage is implied by the name and description, but there is no mention of when not to use it or which sibling tools to consider for related tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
States it reads and returns raw console response, implying no side effects. However, without annotations, it lacks explicit safety guarantees, error conditions, or permissions needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with argument documentation. Front-loaded purpose, no wasted words, includes return type.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, param behavior, return type. Low complexity (1 optional param, no nested objects), and output schema exists to describe response structure. Lacks example usage or error handling details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema: explains that tc_id is optional and omitting it lists the whole pool. Schema had 0% description coverage, so this value is significant, though format of ID is not detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Read timecode pool status / configuration'. Distinct from sibling tools like control_timecode, assign_timecode_slot, and create_timecode_pool, which involve modification or creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly indicates read-only usage, but no explicit guidance on when to use vs alternatives (e.g., before modifying with control_timecode) or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only describes parameters and return type but does not mention safety, idempotency, or potential side effects (e.g., if MIDI port is unavailable). This is insufficient for an AI agent to assess risks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a brief summary, use case, clear parameter documentation in a structured format, and return type. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return values are covered. Parameter descriptions are thorough. The tool's purpose and usage context are well explained, though it could mention whether the operation is blocking or if prerequisites exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds detailed meaning: note range 0-127, velocity default 127, channel defaults to Setup MSC channel, off defaults to false. It explains each parameter's behavior beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Send a MIDI note message via the console's MIDI Out port', providing a specific verb and resource. It also explains the use case for triggering external devices, distinguishing it from siblings like send_midi_control and send_midi_program.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it is 'Used to trigger external devices (video servers, audio, pyro, fog)', giving clear context. However, it does not explicitly state when not to use it or mention alternative MIDI tools among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It discloses the default channel behavior and return type, but omits side effects, permissions, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, using a clear header and bullet-style args, with no superfluous sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool, the description covers purpose, parameters, and return value. Missing are error handling or prerequisites, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description adds essential meaning: program number range and channel default behavior, though it does not define 'Setup MSC channel'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sends a MIDI program-change message via the MIDI Out port, which is a specific action distinct from siblings like send_midi_note or send_midi_control.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool's function but does not provide explicit guidance on when to use it versus alternatives, leaving usage context implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states it sets values for the current selection but does not disclose side effects, permissions, or whether the operation is reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with purposeful sections (purpose, constraints, args, returns, examples) and no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the essential constraints and provides examples. The output schema exists, so return value explanation is not required. It is largely complete, though mentioning the effect on the current selection could add context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description compensates by documenting the parameters in the Args section and providing examples, adding meaning beyond the bare JSON schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Set' and the resource 'effect high and/or low values for the current selection', which is specific and distinguishes from sibling tools like set_effect_envelope or set_effect_form.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes the constraint 'At least one of high or low must be provided', but does not provide explicit guidance on when to use this tool versus alternatives or 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It explains that it stores a macro, labels it, and assigns a SetVar command on line 1, but does not address idempotency, permissions, side effects (e.g., overwriting existing macros), or error scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, details, args, returns, examples) and is not unnecessarily verbose. Minor redundancy could be trimmed, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (returning a string) and the description's coverage of arguments and return value, the tool is well-documented. It lacks details on error conditions or prerequisites (e.g., valid macro_id range), but these are minor omissions for a straightforward tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description includes a full docstring with Args and examples for all three parameters, explaining their roles, defaults, and usage. This fully compensates for the absence of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'macro' with a specific purpose: setting a user variable to the song name. It distinguishes from sibling tools like 'create_macro' and 'set_user_variable' by detailing the combined action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it is used 'to track the current song in music show workflows,' providing context, but it does not explicitly state when not to use it or suggest alternatives like 'create_macro' for generic macros or 'set_user_variable' for direct variable setting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose side effects, permissions, error cases, or what happens if the fixture isn't parked. The return type is mentioned but not the content of the message.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one-line purpose, then clearly labeled Args and Returns sections. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and an output schema, the description covers the main usage. However, it lacks some behavioral context that could be added without much verbosity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates well by explaining the parameter's purpose, providing an example, and indicating the default behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (unpark) and resource (DMX output), which directly distinguishes it from the sibling 'park_fixture'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on what the target parameter does and that omitting it affects the current selection. However, no explicit when-not-to-use or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the steps: select target, set colors, store, label, set appearance. However, it does not clarify whether non-merge calls overwrite existing presets or cause other side effects, nor does it mention permissions or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with headings (Args, Returns, Examples) and front-loaded with purpose. It is not overly verbose, though some sentences could be tighter. Every major element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, no annotations, output schema exists), the description covers purpose, parameters, return type, and examples. It lacks error handling and edge cases, but overall provides sufficient context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must add value. The Args section explains each parameter beyond schema: e.g., target is a selection command, colors have r/g/b/w in 0-100, merge is non-destructive, scope defaults to global. This adds substantial meaning, though not exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool builds or extends a color preset palette for fixture selections. It provides a specific verb ('Build (or extend)') and resource ('color preset palette') and differentiates from siblings like store_preset or build_preset_palette by detailing the multi-color, single-call behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly guides when to use merge for extending palettes without overwriting, and the examples show both fresh build and extension. However, it does not explicitly mention when not to use this tool or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description discloses mode options (default/overwrite/merge) and that it returns a result message, but doesn't fully detail side effects of overwriting or potential destructive actions beyond mode parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear purpose, Args section, Returns, and Examples. Each sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all parameters, return type, and expression syntax. Could add more detail about behavior of 'overwrite' and 'merge' modes, but overall comprehensive for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description fully compensates by explaining selection expressions, providing examples, and clarifying the meaning and usage of each parameter beyond the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Copy an object (or range) to a new location.' with specific verb and resource. Differentiates from sibling 'move_object' which moves rather than copies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage via examples, but lacks explicit guidance on when to use this tool versus alternatives like 'move_object' or 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the creation process and return value. Without annotations, it carries the full burden and covers basic behavior. However, it lacks disclosure about idempotency or handling of duplicate tc_ids.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a purpose statement, context, parameter list, return type, and example. Every sentence is necessary and adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is fairly complete for a creation tool, covering purpose, parameters, and return. Minor omission: not addressing conflict when tc_id already exists. Still, adequate given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining all three parameters (tc_id, name, slot) and providing an example. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a timecode show' with optional naming and slot assignment. It distinguishes from sibling tools like control_timecode and assign_timecode_slot by focusing on creation, and provides additional context about SMPTE setup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that timecode events are recorded via control_timecode, implying when to use this tool vs that one. However, it does not explicitly state when not to use this tool or provide alternatives for specific scenarios like reassigning slots.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states that it labels a cue and can label a range with an optional end_cue, but does not disclose whether it overwrites existing labels, requires permissions, or other side effects. The behavioral impact is inadequately covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with an intro, Args, Returns, and Examples. Every sentence is informative, and examples are provided without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no annotations, and an output schema, the description covers the main functionality and parameter details well. However, it lacks information about error cases, prerequisites (e.g., sequence existence), and result message specifics, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It provides clear parameter descriptions in the Args section with examples, including the optional end_cue and acceptable formats for sequence. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool labels a cue within a specific sequence, using a specific verb and resource. It distinguishes from sibling tools like 'label_cue_across_sequences' by emphasizing sequence context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the tool is for labeling cues inside named sequences via sequence context, but does not explicitly mention when not to use it or provide alternatives. It implies the correct use case but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 states the return type as 'raw console response' and implies a read-only listing. However, it lacks disclosure of potential side effects, authentication needs, or behavior on invalid input, leaving some gaps for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a general statement, valid type list, and Args/Returns sections. It is concise with no unnecessary words, though the docstring format adds some length. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of a listing tool and the presence of an output schema (though not shown), the description covers the main behavior: listing presets by type with optional ID filter. It mentions the return value as a string. Minor improvements could include more detail on output format or error handling, but it is largely complete for the task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains preset_type with examples ('color', 'position') and preset_id as optional, adding meaning beyond the schema types. The list of valid preset types in the description is crucial since the schema has no enums.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'list presets of a given type' with specific verb 'list' and resource 'presets'. It distinguishes from siblings like store_preset, delete_preset, apply_preset by focusing on reading rather than modifying. The enumeration of valid preset types adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides valid preset types and indicates that preset_id is optional, guiding usage. However, it does not explicitly contrast with sibling tools or specify when not to use this tool (e.g., when modification is needed), though the context makes it clear it's for reading only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions that it retrieves and parses lines and returns a dict with parsed lines and raw response, but it does not state idempotency, side effects, permissions, or error handling. The description adds some context beyond annotations (none present) but lacks full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a brief intro, structured Args section, and clear return type. Every sentence adds value without redundancy. It is appropriately front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers purpose, parameters, and return structure. It is fairly complete for a simple read tool, though it could mention error handling or behavior when macro does not exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the schema has no descriptions. The description compensates by explaining both parameters in the Args section: 'macro_id: Macro ID to read' and 'pool: Macro pool number (default 1)'. This adds full semantic meaning beyond the schema's minimal type/title info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read macro line content for a given macro' with a specific verb (read) and resource (macro line content). It distinguishes from sibling tools like 'list_macros' (lists macro names) and 'set_macro_line' (writes lines), as it retrieves and parses all lines.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading macro content but does not explicitly state when to use versus alternatives like 'run_macro' or 'set_macro_line'. No when-not-to-use guidance or context for choosing this tool over siblings is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides some behavioral context ('assertive playback, overrides lower priorities') but lacks details on side effects, permissions, or whether it interrupts other executors. The return type is mentioned as 'str' but no specifics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a clear header, parameter list, and return statement. Every sentence adds value, and there is no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 parameters, no annotations, output schema mentioned), the description covers the basic function. However, it lacks context about when to choose stomp over similar tools like flash or swop, and could detail the return message format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description's parameter documentation adds essential meaning. 'Executor number' and 'page-qualified addressing' clarify the parameters beyond the bare schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Stomp an executor' and provides the specific behavior 'assertive playback, overrides lower priorities'. This immediately distinguishes it from sibling tools like flash_executor (temporary) or release_executor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a use case with 'overrides lower priorities', suggesting it's for assertive control. However, it does not explicitly state when not to use it or compare to alternatives like swop_executor or top_executor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that merge keeps existing values and overwrite replaces entirely, but it is unclear what happens if both flags are false (default). No mention of permissions, side effects, or error conditions. Adequate but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise and well-structured: starts with core purpose, then highlights a key use case, lists parameters with brief explanations, and includes examples. No unnecessary words, though the parameter list could be more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters and an output schema, the description covers the essential behavior (store, merge, overwrite). It explains the critical distinction between merge and overwrite. However, it does not elaborate on the meaning of each scope value (global vs selective vs universal), which would require domain knowledge. Overall sufficiently complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description adds meaningful context: explains that 'merge' adds without disturbing, 'overwrite' replaces entirely, and 'scope' has options 'global', 'selective', or 'universal'. The parameter names alone are insufficient, but the description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it stores programmer values as a preset. Distinguishes between merge (additive) and overwrite (replace), and provides a concrete use case for merging to extend a global palette. The verb 'store' and resource 'preset' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use merge (to add values to an existing preset without disturbing other fixtures) and implies overwrite for full replacement. However, it does not explicitly state scenarios where this tool is inappropriate or compare to siblings like 'store_cue'. The guidance on merge vs overwrite is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses merging behavior, scope usage, and return type, but omits destructive effects, authorization needs, or rate limits. Adequate but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with summary, explanation, Args, Returns, and Examples. It is somewhat lengthy but each part earns its place. Minor opportunity to tighten.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 params, nested structures), the description covers behavior, parameters, and an example. Output schema exists, so return value explanation is sufficient. Lacks comparison to sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It thoroughly explains each parameter, including the complex nested structure of 'presets', with examples. Adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb-resource statement 'Build a preset palette of any type from per-fixture-type value sets.' It distinguishes itself from sibling tools like build_color_palette by generalizing across types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the structure and behavior of presets, including how targets and merge work. It implies use for general palette building but lacks explicit when-not or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that the tool stores a sequence, creates cues for each song, and assigns macro triggers to cue CMD fields. It also notes the return type (a result message). No annotations are provided, so the description carries the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a one-line purpose, a paragraph explaining the process and required song structure, and an example. Every sentence is useful and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 required parameters and an output schema (though not shown), the description covers the core functionality, input format, and return type. It lacks error handling or edge case details, but for a typical usage scenario it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameter descriptions (0% coverage), so the description must compensate. It clarifies that 'songs' is a list of dicts with required keys (cue_id, macro_id, name), but for 'sequence_id' and 'sequence_name' it only provides minimal labels ('Sequence number', 'Label'). This adds some value but not enough for full clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'set-list sequence' with 'cue-to-macro links'. This distinguishes it from sibling tools like 'create_song_objects' or 'set_cue_cmd', which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description outlines when to use the tool (to build a set list with cue-macro links) and provides the required structure of the songs parameter, but it does not explicitly mention alternatives or 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that it first stores an empty macro then assigns commands to sequential lines, optionally labels, and uses a default pool. It also states the return type. No annotations are present, so the description carries the full burden and does well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct: a one-line intro, followed by structured Args and Returns sections, then two examples. Every sentence adds value; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the creation process, parameter details, and return type. With an output schema present, the return value is sufficiently described. Missing are error conditions and behavior if macro_id already exists, but overall it is fairly complete for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description lists all four parameters (macro_id, commands, name, pool) with brief explanations and examples. This adds meaning beyond the raw schema, though some constraints (e.g., valid macro_id range) are missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a macro with command lines' and explains the process of storing an empty macro and assigning commands sequentially. This distinguishes it from sibling tools like set_macro_line or run_macro.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the purpose is clear, there is no explicit guidance on when to use this tool versus alternatives (e.g., set_macro_line for modifying existing macros, label_macro_tool for labeling). The description does not provide 'when to use' or 'when not to use' context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must convey behavior. It indicates a destructive reset action, but does not mention side effects, prerequisites, or output. Adequate for a simple parameterless action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, zero waste, perfectly front-loaded and appropriately sized for a simple reset operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and simple reset action, description is complete enough. Output schema exists but not described; however, for a reset tool this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100%. Baseline 4 is appropriate since description adds no parameter info beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Reset' and resource 'all MAtricks settings to defaults', with specific scope that differentiates from sibling tools like set_matricks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly clear that tool resets MAtricks to defaults; no explicit when-not or alternatives, but simplicity of tool makes guidance adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 describes the operation as setting timing values, which implies modification, but does not disclose potential side effects, permissions, or error handling. It is adequate but 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (under 100 words), front-loaded with the purpose, and structured with a parameter list and return type. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (setting timing on cues) and the presence of an output schema, the description covers the main functionality, parameters, and return type. It could mention error handling or constraints on values, but it is sufficient for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by listing each parameter with a brief explanation (e.g., 'Fade time (seconds)'). It clarifies that at least one parameter is required and that 'target' is optional. However, it could provide more details like units for all parameters or typical value ranges.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Set' and the resource 'cue or the current selection', with a specific scope (fade/delay timing). It distinguishes itself from sibling tools like set_step_timing by explicitly mentioning cues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that at least one parameter is required and clarifies how the 'target' parameter works (omit for current selection). It does not explicitly mention when not to use the tool or compare with alternatives like set_cue_cmd, but the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It explains that parameters are sent together and returns a result message, but doesn't detail side effects or state changes. It 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear purpose, usage note, and parameter list. No redundant sentences; every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description adequately covers purpose, parameter constraints, and requirements. It could provide more detail on parameter effects but is sufficiently complete for a configure tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description compensates with brief explanations for each parameter (e.g., 'blocks: Block size grouping'). These add meaning beyond the property names, meeting the baseline for low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool configures MAtricks for fan effects/selection-pattern manipulation, with a specific verb and resource. It distinguishes itself from the sibling tool 'reset_matricks' which likely resets settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says it applies to the current fixture selection and requires at least one parameter, but no explicit when-not-to-use or alternatives beyond the sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It discloses that the tool toggles a mode for editing without affecting output and explains the edit_mode parameter behavior. It covers the key behavioral aspects but could mention state toggling more explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear first sentence, structured Args and Returns. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the main functionality, it lacks details on the interaction between executor_id and edit_mode, state toggling behavior, and result message content. For a toggle tool with optional parameters, more completeness on mode semantics would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It explains all three parameters: executor_id for specific executor, page for addressing, and edit_mode for global toggle. This fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool toggles blind editing mode and explains that it allows editing cues without affecting stage output. This distinguishes it from siblings like toggle_blackout and toggle_highlight.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the parameters but does not explicitly state when to use this tool versus alternatives or provide exclusions. Usage is implied by the tool's purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses type-dependent behavior, variable naming hint ($ prefix), and return type. However, it omits side effects (e.g., whether variable must exist), error conditions, and permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise: a one-line operation summary, behavioral rule, then clear Args section. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-param tool, the description covers purpose, parameter semantics, and return type. It lacks context on variable existence, creation, or global vs user scope, but overall is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must fully compensate. It provides clear semantics: var_name should start with $, value is either numeric (added) or text (appended). This adds significant value beyond the raw schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation 'Add to / extend a global show variable' and specifies type-dependent behavior (sum numeric, concatenate text). The verb 'add' distinguishes it from sibling tools like set_variable (overwrite) and add_user_variable (user-level).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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 like add_user_variable or set_variable. The name implies addition, but the description does not clarify scope or prerequisites, leaving inference up to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the destructive nature of the operation ('permanently removes the macro') and mentions the return type (result message with warnings). No annotations exist, so the description carries the full burden and does so adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with a clear structure: action statement, warning, parameter descriptions, and return type. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate coverage for a simple delete tool: describes operation, parameters, and return. With no annotations and an output schema, the description provides sufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond the input schema by describing macro_id as 'Macro number to delete' and pool as 'Macro pool number (default: 1)'. With 0% schema coverage, this compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('Delete a macro') and the resource ('macro pool'). Distinguishes from sibling tools like create_macro, run_macro, and list_macros by specifying deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for usage: deleting a macro permanently. The warning about destructiveness implies caution, but no explicit alternatives or when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations exist, description carries full burden. It clearly states it returns raw console output (a string). This is adequate for a simple read operation, though it could mention if there are any side effects (likely none). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences plus a Returns line that adds clarity. Every element is purposeful with no wasted words. Front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and an existing output schema, the description is fully adequate. It states the action and the return format, which is all an agent needs to invoke and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters in schema with 100% coverage. Description adds no param info because there are no params, which is appropriate. Baseline 4 for zero-param tools is justified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states it lists macros in the macro pool, a specific verb+resource. Clearly distinguishes from sibling tools like create_macro, run_macro, delete_macro_tool, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives. While context implies it's for listing macros, the description lacks 'when-to-use' or 'when-not-to-use' directives common in well-documented tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the overwrite suppression behavior via /noconfirm, which is important. However, it does not mention any other behavioral traits such as error handling, permissions, or what happens if the save fails. The description is adequate but lacks deeper behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with clear sections: main action, condition for no name, suppression detail, and Args/Returns. Every sentence adds value without redundancy, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter, the description fully covers the behavior (saving with/without name, overwrite handling) and specifies the return type as a string confirmation message. No gaps remain given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It explains that show_name is optional and if omitted, saves under the current name. This provides meaningful context beyond the schema's type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool saves the current show file on the grandMA2 console, distinguishing it from sibling tools like load or create shows. It specifies the action (save) and resource (show file), and the optional behavior when no name is provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that saving without a name uses the current show name, and mentions the /noconfirm flag to suppress confirmation popups, which is crucial for Telnet use. However, it does not explicitly state when not to use this tool or compare to alternatives like load or create new show tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description states it is low-level and sends raw commands, but does not disclose potential risks, side effects, or error behavior. Returns 'Operation result message' gives minimal insight. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with a main sentence, usage note, and structured Args/Returns sections. Examples add value. Some redundancy with schema but acceptable. Efficient use of space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, the description covers purpose, usage, parameter, and return value (textual output schema). Could mention validity or error handling, but given low complexity, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (no param description in schema). The description adds 'Raw MA command to send' for the 'command' parameter, providing essential meaning. Could include format or constraints, but compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Send a raw MA command to grandMA2', specifying the verb and resource. Examples like 'blackout', 'go+ executor 1.1', and 'store sequence 1 cue 1' further clarify its purpose. It distinguishes itself from high-level sibling tools by being a low-level command tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'It is recommended to use other high-level tools first; use this tool only when special commands are needed.' This tells the agent when to use and when not to use, implicitly referencing alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains the iterative behavior, optional naming, and return structure (commands_sent, count, summary). No contradictions present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with clear sections (Args, Returns, Examples). Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and 4 parameters, the description fully explains purpose, parameters, behavior, and return value. Complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description compensates by explaining each parameter's role (cue_id, sequence_start/end, cue_name optional) and providing realistic examples. Adds meaning beyond raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Store a cue across a range of sequences' with specific verb-resource combination. It distinguishes from sibling tools like 'store_cue' by explicitly mentioning iteration over a range of sequences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for batch storage over a sequence range but does not explicitly state when to use versus alternatives like 'store_cue'. No exclusions or alternative tool mentions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool is destructive ('removes from source'), supports range moves via selection expressions, and returns a result message. It adds value beyond the schema by explaining these behaviors. Could mention reversibility or failure modes, but adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a warning, explanation, and Args/Returns section. It is front-loaded with critical info. Slightly verbose but each sentence serves a purpose. Could be tightened but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 required parameters, no annotations, and existence of output schema (though not detailed), the description covers core behavior, parameter meanings, selection expressions, and return type. It lacks examples or edge-case handling, but for an AI agent it provides sufficient context to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides clear meanings for all three parameters: object_type with examples, source and target as selection expressions. Additionally, it explains selection expressions in the main text, adding significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool moves an object (or range) to a new location, using the verb 'Move' and specifying the resource 'object (or range)'. The warning 'removes from source' distinguishes it from a copy operation, and the sibling list includes 'copy_object', enhancing differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the tool is for moving, not copying, via the warning 'removes from source'. It also describes selection expressions for ranges. However, it does not explicitly say when not to use it or mention alternatives like 'copy_object' by name, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It explicitly states the tool is pure metadata, does not open a console connection, and lacks error handling, providing clear behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding value: purpose, context (startup self-check), and behavioral caveat plus return format. No redundancy, efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple metadata tool with no output schema, the description fully covers what it returns (dict with fields). No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema covers them completely (empty). The description adds no parameter info, which is appropriate; baseline for zero-parameter tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports server version, registered tools, and profile schema version. It uses a specific verb ('report') and resource ('server metadata'), distinguishing it from sibling tools that manipulate show data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates use for startup self-check and notes it does not open a console connection, implying safe, side-effect-free usage. While it doesn't explicitly contrast with other tools, the context is sufficient for an agent to decide when to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explains that command executes automatically when cue fires, which is key behavioral info. No annotations provided, so description carries burden; could mention side effects or error handling, but adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with summary, then structured Args, Returns, Examples. No redundant information, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 simple parameters and clear behavior, description is complete. Includes return type and examples. Output schema exists but is not needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds meaning with 'Args' section explaining each parameter (cue number, sequence number, command example). Covers all 3 parameters clearly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb ('assign'), resource ('cue's CMD field'), and purpose ('execute command on cue fire'). Distinguishes from siblings like run_macro.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States common use case and provides examples, but lacks explicit when-not-to-use or comparison to alternative tools like set_macro_line.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully carries the burden. It explicitly states the operation is destructive, warns about unsaved changes, and describes the return value. This provides excellent transparency for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient, with a clear warning first, then parameter and return documentation. It could be slightly more concise, but it is well-structured and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only two parameters and an output schema, the description covers key aspects: destructive nature, parameter behaviors, and return type. It does not mention file format or path, but that is minor for this context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description provides full parameter documentation: show_name and save_first are described, including the purpose of save_first. This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'load' and resource 'show file on the grandMA2 console'. It distinguishes itself from siblings like 'new_show_tool' and 'save_show_tool' by focusing on loading an existing show.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description warns that the operation is destructive and recommends setting save_first=True to save before loading. It implies when to use (loading a different show) but does not explicitly compare with alternatives or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden of behavioral disclosure. It clearly states that parking 'locks a value regardless of playback,' indicating persistent override behavior. It also notes the return type (string message). While not exhaustive, it gives enough transparency for a relatively simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single-sentence summary followed by structured Args and Returns. Every sentence adds value without redundancy. It is front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only two optional parameters, an output schema, and no nested objects, the description covers all necessary aspects: parameter usage, return type, and behavioral note. It is complete for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the schema. It explains the 'target' parameter with concrete examples ('fixture 1', 'channel 5') and clarifies that omission parks current selection. For 'at_value,' it defines the range (0-100) and the default behavior (omit = park current value). This compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Park DMX output') and explains it as 'lock a value regardless of playback.' This directly conveys the tool's purpose and distinguishes it from sibling tools like 'unpark_fixture' or 'set_fixture_value.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on parameter usage: omitting 'target' parks current selection, and omitting 'at_value' parks current value. However, it lacks explicit when-to-use or when-not-to-use advice, such as contrasting with 'set_fixture_value' for temporary overrides.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It is transparent about the read operation, empty response, and clarification that it does not return cue properties. It could mention any permission requirements, but for a simple read tool this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two paragraphs, front-loaded with the core purpose, and includes a clear note and Args section. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, read operation), the description is complete. It explains the input, output, and provides a distinguishing note. The return type is described, and there is an output schema present, but the description adds clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the tool description includes an Args section that explains both parameters: cue_id and sequence_id, adding meaning by specifying what each represents. This compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads user-added annotation text on a cue, using specific verbs and resource. It distinguishes itself from sibling tools like list_cues by explicitly stating what it does NOT return (cue properties), making its purpose unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool (to read annotations) and when not to (to get cue properties, for which it recommends list_cues). It also notes the empty response when no annotation is set, setting clear expectations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses read-only behavior, empty response if no annotation, and contextual background about grandMA2 Info keyword. Could mention error cases like non-existent group, but overall transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise: two short paragraphs plus a clear Args/Returns section. Every sentence adds value, well-structured and front-loaded with core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter and no annotations, the description is complete. It explains output (string or empty), addresses potential confusion with sibling tool list_groups, and provides sufficient context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It adds a brief description for group_id: 'group ID to read annotation from', which adds meaning beyond schema's title and type. However, it lacks constraints like valid range or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads annotation text on a group, specifies it does not return group composition or fixture details, and distinguishes from list_groups, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool (read annotation) and when not to (for group details, use list_groups instead), providing clear guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses the destructive operation, the effect on unsaved changes, the recommended parameter behavior, and the return type (confirmation message), ensuring the agent understands the tool's impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a clear one-line purpose, followed by a warning, then parameter explanations, and return type. There is no redundant text, and the most critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (destructive, 2 params, output schema), the description fully covers all necessary aspects: purpose, behavior, parameters, and return value. It also addresses an edge case (omitting show_name) and references the manual, making it complete for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains both parameters in detail: show_name is recommended per manual, save_first saves before creating. This adds significant meaning beyond the schema's property definitions and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'create a new empty show on the grandMA2 console,' with a specific verb and resource, and distinguishes itself from sibling tools like load_show_tool and save_show_tool. It also provides necessary caveats about the show name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly warns about the destructive nature and advises setting save_first=True to save the current show, giving clear context for when to use the tool. It could also explicitly mention alternatives, but the warning is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes behavior: querying object type with optional ID, list/annotation modes. Clarifies 'annotation' mode reads user-added text, not properties. No annotations provided, so description carries full burden and does so well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections but could be slightly more concise. Front-loaded with purpose, followed by guidelines and parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description provides comprehensive coverage: purpose, usage, parameters, return type. Complete for a generic query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description explains all three parameters: object_type with examples, object_id as optional, and mode with default and note. Adds meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a generic query tool for any grandMA2 object type, distinguishes from dedicated tools, and lists example object types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use this tool (object types without dedicated tool) and when to prefer specific tools (groups, cues, presets). Also explains mode usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![gma2-mcp MCP server](https://glama.ai/mcp/servers/chienchuanw/gma2-mcp/badges/card.svg)](https://glama.ai/mcp/servers/chienchuanw/gma2-mcp)

Score Badge

Copy to your README.md:

[![gma2-mcp MCP server](https://glama.ai/mcp/servers/chienchuanw/gma2-mcp/badges/score.svg)](https://glama.ai/mcp/servers/chienchuanw/gma2-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/chienchuanw/gma2-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server