Server Quality Checklist

Tool Scores

• midi_queryD
  1.6/5.0
  Behavior1/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 for behavioral disclosure. 'Query' implies a read operation, but there is no explicit mention of safety, side effects, permissions, or output behavior, making the tool behaviorally opaque.

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

  Conciseness2/5

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

  The description is a single short sentence, which is concise, but it is under-specified rather than efficiently informative. It lacks essential details and does not earn its brevity, similar to the 'Process' example where minimalism harms usability.

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

  Completeness1/5

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

  Given the lack of annotations, an opaque parameter, no output schema, and no usage context, the description is grossly incomplete. The agent has no information about query syntax, return values, or operational constraints, making the tool nearly unusable for reliable invocation.

  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 only defines a required string 'q' with 0% description coverage. The description adds no meaning for the parameter—it does not explain what 'q' should contain, the query syntax, or expected format. The parameter is completely underdocumented.

  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 'Query midi state' provides a verb and a resource, but 'midi state' is vague and does not specify what aspect of MIDI state is being queried. It does not distinguish itself from sibling tools like 'midi' or 'midi_session', and the purpose remains ambiguous.

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

  Usage Guidelines1/5

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

  No guidance is given for when to use this tool versus alternatives. The description does not mention any context, prerequisites, or comparisons to sibling tools, leaving the agent without direction for tool selection.

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

• midi_sessionC
  2.6/5.0
  Behavior2/5

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

  With no annotations, the description carries full responsibility for behavioral disclosure. It lists commands like 'undo' and 'redo' which imply state changes, but it does not explain side effects, persistence semantics, error behavior, or any side effects beyond naming the actions. The behavior is largely opaque.

  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 to the point, listing commands in a compact format. It is front-loaded with 'Session:' which sets the context. The structure is somewhat unstructured as a free-form string, but it contains no fluff and every word contributes to the set of examples.

  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?

  Despite having only one parameter and no output schema, the description is still too minimal. It does not explain what the tool returns, whether commands are executed sequentially, what 'checkpoint' does, or what constitutes valid input. For a session management tool, the description lacks essential operational 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 single 'action' parameter has no schema description and no enum, but the description partially compensates by providing concrete example values (e.g., 'new "Title"', 'open ./file'). This gives the agent some sense of expected syntax, though the format is ambiguous (mixing quotes, spaces, and version strings) and not all actions are equally explained.

  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 implies session management through a list of example commands ('new', 'open', 'save', etc.), but it never explicitly states the tool's purpose as a verb+resource (e.g., 'Manage MIDI sessions'). It is more of a usage hint than a clear functional definition, and it does not explicitly distinguish itself from sibling tools like 'midi' or 'midi_query'.

  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 sibling tools are not mentioned, and there is no description of scenarios suitable for session operations. The examples imply actions, but no context or exclusion criteria are given.

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

• midi_helpA
  3.8/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral transparency. It only states that a reference card is returned, without detailing the format, whether it is read-only, or any other operational aspects. For a help tool this is minimal but lacks depth.

  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 8-word sentence with no extraneous detail, front-loading the key action and outcome.

  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 zero-parameter help tool with no output schema, the description sufficiently explains the return value (the reference card) and its scope (all syntax). It lacks some specifics about the card's content, but overall is complete for its 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 tool has zero parameters and the schema covers 100% of the interface, so description-level parameter semantics are unnecessary. Baseline score of 4 applies.

  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 returns a reference card for MIDI syntax, using the specific verb 'Returns' and a concrete resource. This differentiates it from siblings like midi_query or midi_session.

  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 this tool is used to obtain reference information, but it does not explicitly state when to use it or provide alternatives. There is no mention of situations where other sibling tools would be more appropriate.

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

• midiA
  4.2/5.0
  Behavior4/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 does well by documenting response prefixes, 1-based positions, 1-indexed channels, and GM conventions. It stops short of explaining failure modes, transactionality of batched ops, or persistence behavior, which are relevant for an execution 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 long but meticulously organized into labeled sections (MUSIC, STATE, META, EDITING, SELECTORS, etc.) with a monospaced format for readability. The front-loaded instruction 'Each op string follows: VERB TARGET [key:value ...]' and the pointer to midi_help ensure efficiency. Every section provides essential syntax for a complex DSL, so no space is wasted.

  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, the absence of an output schema, and zero annotations, this description is remarkably complete. It covers all major operation types, selectors, notational conventions, and response prefixes. It also references midi_help for deeper coverage, making it sufficient for correct tool invocation.

  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 a single undocumented parameter 'ops' (an array of strings), and the description fully compensates by defining the exact op syntax, selectors, positions, durations, pitches, chords, velocities, and more. This is a comprehensive semantic specification that makes parameter usage unambiguous.

  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 opens with 'Execute midi operations,' a clear verb+resource statement that identifies the tool's core purpose. It also differentiates from midi_help by instructing users to call it for the full reference card. However, it does not explicitly contrast with midi_query or midi_session, so it doesn't fully distinguish among all sibling tools.

  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 offers some usage guidance, such as batching multiple ops for efficiency and calling midi_help when context is truncated. However, it does not explicitly state when to use this tool instead of midi_query or midi_session, and the guidance is mostly implied through the operation list.

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