crosspad_midi

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

Annotations only declare readOnlyHint=false and destructiveHint=false, but the description goes beyond: it discloses that extras are ignored, that channel defaults to 0 for all types, and critically warns that cc and program_change will call fail fast due to missing handlers, and that only note_on/note_off reach the sim today. This is exemplary behavioral disclosure.

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

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

The description is efficiently organized with a per-type bulleted breakdown and warning flags. The '⚠️ NOT YET SUPPORTED' markers are highly informative. Slightly dense but every line earns its place, and front-loading the consolidated context is effective.

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

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

Given the complexity of a multi-type consolidated tool with a 7-param schema and output schema present, the description is remarkably complete: it covers type-specific requirements, defaults, unsupported types, and the fact that only note_on/note_off actually work today. The output schema handles return-value documentation. Nothing meaningful is missing.

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

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

Schema description coverage is 100%, so all 7 parameters are fully documented in the schema. The description adds value by consolidating the per-type required-field mapping (note_on→note, cc→cc_num+value, etc.) which is genuinely useful. However, much of this is also reflected in the 'type' param description, so added value is moderate.

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

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

Description clearly states 'Send one MIDI event to the running PC simulator', a specific verb+destination. It explicitly notes this is a consolidated tool replacing 4 v5 tools, distinguishing its purpose and scope. The per-type breakdown reinforces clarity.

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

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

Provides explicit guidance on when to use each type, which fields are required per type, and which types are NOT supported by the PC sim (cc, program_change) and fail fast. This is strong 'when/when-not' guidance that prevents wasted calls.

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