osc-bridge

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value by defining what each status means — notably that 'pending' is waiting on a merge job and 'held' means the account is under review — which an agent could not infer from the structured fields.

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

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

A single sentence that front-loads the outcome space and uses the four enumerations as its structure. Every clause carries information; nothing is padding.

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

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

With no output schema, the description usefully serves as a return-value sketch by enumerating the status states and what accompanies merged and rejected. What's missing is the shape of the response beyond status (e.g. whether the PR URL or reason is a separate field), and it says nothing about the required id.

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 only 50%: only user_id is documented, while the required `id` parameter has no schema description. The description supplies nothing about either parameter — not what an id refers to, nor the anonymous-id fallback — so it does not compensate for the gap on a required parameter.

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

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

The description names the resource (a contribution's status) and enumerates the four possible states with a parenthetical gloss for each, which lets an agent immediately recognize the tool's job. It lacks an explicit verb ('retrieve/get'), but the meaning is unambiguous and no sibling overlaps this purpose.

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?

There is no statement of when to call this versus alternatives, no prerequisites, and no mention of when the result is not yet meaningful. Usage is only inferable from the sibling names (submit_*), not from the description itself.

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

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

Annotations already cover readOnly/idempotent/closed-world, so the bar is lower. The description adds real context beyond them: the return is markdown, and 'if present' signals the docs may not exist for a given device — a meaningful behavioral trait. It stops short of saying whether absence yields an error or empty result.

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

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

Two tight sentences, no waste, with the core action and the conditional-presence caveat front-loaded and the slug convention immediately following.

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?

An output schema exists, so return-shape explanation is unnecessary, and the description plus schema fully cover both parameters. The only gap is not stating the failure/no-docs behavior, though 'if present' gestures at it.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a derivation rule not in the schema: the slug is the device's OSC prefix minus the leading slash (e.g. '/ableton' → 'ableton'), which tells the agent how to construct or verify the value.

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?

States a specific verb ('Fetch') and a precise resource ('markdown companion documentation for one device'), and the 'if present' qualifier and slug explanation make it distinguishable from list_devices and other siblings without opening the schema.

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?

Usage is implied (fetch docs for a device you already know the slug of), but the description never says when to use it versus list_devices (to discover slugs) or whether it should be called before submit_fix/report_mapping. No explicit when-not guidance.

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

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

Beyond the read-only/idempotent annotations, the description discloses the status taxonomy, what counts are returned, the per-firmware and per-OSC-address structure, and the special meaning of needs_firmware=true when reports disagree. That is substantive behavioral context the annotations do not carry.

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

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

The description is dense but front-loaded with the core definition and then moves to caveats and usage. It earns most of its length through the status list and the needs_firmware explanation, though the first sentence is quite packed and could be easier to parse.

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

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

With an output schema already defining return values and annotations covering safety and idempotency, the description supplies the remaining operational context: what trust means, the status categories, firmware-level variance, and the needs_firmware edge case. Nothing essential for correct invocation appears 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 coverage is 100%, so the device and user_id parameters are already documented in the schema. The description adds related operational context around identifying the device before reporting, but it does not add parameter-specific syntax or selection guidance beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific resource and scope: a driver's confirmation/trust status per firmware, including report counts, per-firmware statuses, device identities, and per-OSC-address breakdowns. That is far more precise than a restatement of the name and lets an agent distinguish this from reporting or contribution siblings.

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

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

It gives clear usage context: check trust before relying on a driver, together with source_tier. It also explains the needs_firmware caveat and points to 'learn' for device identification. It does not explicitly name when not to use it or name an alternative sibling, so it stops short of a 5.

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

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

The annotations already establish read-only, idempotent, closed-world behavior, so the bar is lower. The description adds useful behavioral context: catalogue size, no-argument list-all behavior, query matching across vendor/name/slug, and returned fields including firmware version when stated.

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 compact and front-loaded, starting with the primary action and scope before covering no-argument behavior, filtering, return fields, and the recommended next tool. Every sentence contributes useful information.

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

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

With annotations and an output schema already present, the description provides enough context to call the tool correctly, including default listing behavior, query semantics, and return fields. Minor gaps remain around how `kind` and `vendor` interact with `query` and what the default limit is.

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 high at 80%, so the schema already documents most parameters. The description adds a useful `query` example and explains slug usage, but it does not clarify the `kind`, `vendor`, or `user_id` filters beyond what the schema provides.

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

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

The description states a specific verb and resource: find/list device drivers in the catalogue, with concrete scope (about 980 synths, drum machines, controllers and DAWs). It also distinguishes this tool from list_routes by explaining that a returned slug should be passed to list_routes for the full CC/NRPN/SysEx map.

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

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

It clearly explains the default behavior with no arguments and how `query` narrows results, plus it names the follow-up alternative `list_routes`. It does not explicitly cover when to prefer `vendor` or `kind` filtering over `query`, or state exclusions, so it falls short of a full when/when-not guide.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description still adds value by disclosing the breadth of content returned (five distinct route categories), which tells the agent this is a broad discovery read, not a narrow lookup. No pagination or size caveats are mentioned, which is the only gap.

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

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

Two sentences, front-loaded with the return payload and followed by the invocation cue. The route-type enumeration is information-dense rather than padded, though it could arguably be trimmed without much loss.

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

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

With an output schema present, the description need not explain return structure, and the annotations cover safety and idempotency. What remains thin is the relationship to siblings with overlapping discovery scope (list_devices, get_device_docs), which is not addressed.

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%: slug and user_id are both documented in-schema, including an example for slug. The description adds no semantics beyond the schema (e.g., no note that slug must be one returned by list_devices), so the baseline 3 applies.

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

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

States a specific verb+resource ('Return the OSC routes a device exposes') and then enumerates exactly which route categories come back (commands, cc/nrpn, sysex, note triggers, reply patterns). It is clearly device-scoped, which separates it from get_device_docs or list_devices, though no sibling is named explicitly.

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?

'Use this to discover what a device can do' gives a clear positive trigger for invocation. It stops short of stating exclusions or pointing to alternatives such as get_device_docs for documentation versus routes for capability, so an agent must infer the boundary itself.

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

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

Goes well beyond the readOnly/idempotent/openWorld annotations: it shows the exact non-mutating SysEx payload, states 'changes nothing on the device', explains matching against a catalogue, and discloses the failure mode ('devices that do not answer are only listed by port name'). That is exactly the behavioral context an agent needs before calling.

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

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

Two dense sentences, front-loaded with the core action and followed by the return contract. No wasted phrasing despite covering mechanism, side-effect status, matching logic, and failure behavior.

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?

There is no output schema, so the description carries the return contract — it names driver ids and identity_hex, and explains the non-responding-device case. Combined with annotations covering safety, an agent has everything needed to call and interpret results.

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?

With 100% schema description coverage, the schema already documents code, user_id, and timeout_ms. The description adds downstream semantics (identity_hex/driver ids feed report_result) but little on the input parameters themselves, so the baseline 3 applies.

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

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

States a specific verb and resource ('Find which devices are connected to the user's machine through a relay') and names the exact mechanism (MIDI Identity Request SysEx) and what is returned. It is clearly distinguishable from relay_send, relay_listen, and relay_status, which do not perform discovery.

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?

Implies use when you need to discover devices behind a relay and explicitly tells the agent what to do with the result ('best driver ids and identity_hex to pass to report_result'). It does not explicitly contrast against siblings like relay_listen or relay_status, so it stops short of full when/when-not guidance.

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

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

Annotations already cover read-only and open-world behavior; the description adds the important traits: the capture is time-bounded, it depends on the user physically moving a control, and the device parameter enables OSC address matching. It leaves unstated what is returned when no messages arrive or when the pairing code is invalid.

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 core action is front-loaded in the first sentence, with the workflow in the second. The second sentence is dense with nested clauses (parenthetical aside about report_mapping) but every element carries actionable information.

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

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

For a live-capture tool with no output schema, the description conveys what the agent will observe (decoded notes/CC/NRPN/SysEx plus address matching) and the prerequisite of user interaction. Missing only edge-case behavior such as empty captures or bad pairing codes.

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

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

Schema coverage is 100%, so every parameter including the pairing code example and the seconds range is already documented. The description only reinforces the conditional meaning of device ('with a device, each CC or NRPN that moved is matched'), which is a small addition over the schema's own wording — baseline 3 applies.

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

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

States a specific verb and resource — listening to MIDI traffic through a relay — and scopes it precisely (notes, CC, NRPN, SysEx, decoded, for a few seconds). The mention of matching to the driver's OSC addresses separates it from a raw dump and from the relay_send/relay_detect siblings.

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?

Gives two concrete scenarios (learn which OSC address a control maps to by asking the user to move it; verify the driver's map is correct) and names the follow-up tool report_mapping. It does not state when NOT to use it or contrast it with relay_detect, so it stops short of full routing guidance.

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

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

The description is genuinely rich about behavior — the 2-minute blocking wait for user acceptance, the clamping to parameter range, gap_ms defaults — but it says plainly that SysEx 'may overwrite the device's memory,' which sits uneasily against destructiveHint=false. An agent trusting the annotations alone would not anticipate that a send can rewrite patch/preset state, so the discrepancy is worth flagging even though the consent gate mitigates it.

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

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

One dense paragraph with the primary action front-loaded and the safety warning placed at the end where it applies. A few sentences are long and pack multiple ideas (e.g. the SysEx clause), but nothing is padding.

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

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

For an 8-parameter, open-world, non-idempotent send tool with no output schema, the description covers the two call modes and the confirmation flow well. It never mentions the sole required parameter, the pairing `code`, nor what the call returns on success or refusal — gaps the schema alone only partially fills.

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

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

Schema coverage is 100%, so the schema already documents all eight fields; the description still adds real value by showing the shape of device (id or slug) and address ('/filter/cutoff', args [64]), explaining the server transcode into CC/NRPN/note/SysEx, and stating that values are clamped to the parameter's range.

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?

States a specific verb and resource — 'Play or set something on the user's hardware through a relay' — and immediately disambiguates the two invocation modes (driver + OSC address vs. raw MIDI hex). It also implicitly separates itself from relay_listen/relay_status, which are the read-side siblings in the same family.

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?

Gives concrete conditions: use device+address when you have a driver, use hex for raw bytes, and explicitly routes the agent to list_routes to discover valid addresses. It also warns that SysEx other than Identity Request triggers a user-confirmation prompt. It stops short of stating when to prefer relay_listen or relay_status instead, but the send-vs-receive split is clear from the wording.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered; the description adds real value beyond them by stating 'Nothing is sent to the hardware', which reassures the agent this is a pure inspection step. It also discloses the return payload despite there being no output schema. It doesn't cover failure modes for an invalid or expired code.

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?

Three short sentences: action, precondition, return value and a safety note. Nothing is redundant and the purpose is front-loaded before the setup context.

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

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

With no output schema, the description carries the return-value burden and does so ('MIDI output and input ports of their machine'). For a simple two-parameter read-only check, that is nearly complete; only error/expiry behavior for a stale pairing code is left unstated.

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 both parameters are already documented, including the example code format and the optional user_id. The description only adds provenance context ('the user ... gave you its pairing code'), which is marginal beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Check a relay') and explicitly names what it returns — the MIDI output and input ports of the user's machine. That distinguishes it functionally from relay_send and relay_listen, though it never names those siblings explicitly, so the differentiation is inferred rather than stated.

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?

Gives a concrete usage precondition: the user has opened the relay page or run `osc-bridge connect` and handed over a pairing code. That is a clear trigger condition. It stops short of exclusions or pointing to alternatives such as relay_detect when the precondition is not met.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description adds the key behavioral model that is not in annotations: mappings are only learned when several accounts observe the same signal on one firmware. It doesn't cover conflict handling or what a submission returns, which keeps it from a 5.

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?

Purpose is front-loaded and every clause carries information (prerequisite, input sourcing, fallback, learning model). The single em-dash-chained sentence is dense and slightly hard to parse, which is the only deduction.

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

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

For an 11-parameter write tool with no output schema, the description supplies the workflow, the input provenance, and the learning semantics that an agent needs to call it correctly. It omits what happens on conflicting or rejected mappings and what success looks like, but annotations cover the safety profile.

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

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

Schema coverage is only 45%, so the description must compensate — and it does for the important ones: address (driver OSC address from list_routes), label (fallback when no address exists), cc/nrpn/note as the observed message, firmware, identity_hex, and user_id as optional. It leaves channel and device semantics to the schema, so not a full 5.

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?

States a specific verb and resource — 'teach the catalogue which MIDI message a control really sends' — which is far more informative than the tool name report_mapping. It also names the required prior steps (relay_listen, list_routes), so an agent can distinguish it from get_trust and relay_listen without inspecting schemas.

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?

Gives an explicit triggering condition ('after the user moved one control on the device (see relay_listen)') and the required inputs sourced from siblings (address from list_routes, or panel label when the driver lacks one). It also points to get_trust for reading learned mappings, routing the read/alternative case away from this tool.

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

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

Well beyond the annotations, it discloses consequences: trust is counted per firmware, several agreeing accounts mark the driver usage-verified, and contradicted reports are rolled back and put the account under review. That is exactly the kind of mutation side-effect disclosure annotations cannot convey. What it doesn't cover is whether a re-report by the same account overwrites the earlier one (despite idempotentHint=true) or any rate limiting.

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?

Front-loaded with the action, outcome vocabulary and scope before the trust mechanics, and every clause carries information. It is a single dense, run-on paragraph where the trust/review consequences could be tightened into shorter sentences.

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?

A mutation tool whose annotations are safety-only, but the description supplies the missing incentive and moderation context, and an output schema exists so return values need no explanation. Minor gaps remain around correcting or superseding a prior report and whether repeated submissions are rate-limited.

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?

With 86% schema coverage the schema already documents most fields, yet the description adds real semantics: firmware is the unit of trust accounting so a report without it 'cannot be placed', and identity_hex is framed as proof of connection that also carries firmware. Outcome values are restated but that is already an enum; note and user_id are not discussed.

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

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

The description states a specific verb and resource ('Tell the catalogue how a driver behaved on a real device') plus the exact outcome vocabulary and the scope choice (whole driver vs. a single OSC address). It does not explicitly differentiate itself from the similarly-named sibling report_mapping or submit_fix, so an agent must infer the boundary.

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

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

It clearly conditions use on having actually tested on hardware ('after testing it', 'Report only what was actually tested') and points to list_routes/list_devices for the identifier values. It states no explicit when-not or naming an alternative tool, so the boundary against report_mapping is left implicit.

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

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

Beyond the annotations, the description discloses that the driver is checked, linted, tested, and merged into the public catalogue by a merge job as an 'agent-contributed' file. This explains the downstream effect and validation path, which is important for a non-read-only, open-world tool.

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

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

The description is front-loaded with the action and scope, then supplies schema and validation details in a compact order. Every sentence contributes either invocation guidance or behavioral expectation.

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

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

For a complex contribution tool with a nested required object and no output schema, the description covers the expected driver format, validation path, and public merge outcome well. It stops short of describing the immediate response or failure feedback, and leaves the note parameter undocumented.

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

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

Schema coverage is 80%, so the schema already carries most parameter meaning, but the description adds useful detail for the required driver object by naming the osc-bridge schema fields and linking to the full schema. It also reinforces the source parameter by asking where the data comes from, though it does not explain the note parameter.

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

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

The description clearly states a specific verb and resource: contribute a full driver file for a device missing from the catalogue, or a better one. It defines the expected schema and downstream merge behavior, though it does not explicitly differentiate this tool from nearby siblings such as submit_fix or report_mapping.

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

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

It gives a clear condition for use: when the catalogue lacks a driver or the agent has a better one. It does not explicitly state when to use submit_fix, report_mapping, or other siblings instead, so the alternative routing is implied rather than spelled out.

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

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

Annotations declare the mutations (readOnly=false, idempotent=false, destructive=false), and the description adds real context beyond them: a new file is created for that firmware rather than editing in place, and it is queued for the merge job. It does not cover permissions, whether repeats duplicate files (relevant given idempotent=false), or what the response looks like.

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

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

A single run-on sentence with the purpose front-loaded, but padded with jargon and pseudo-syntax ('get_trust → mappings, differs: true') that is harder to parse than plain prose. It could be split into a purpose sentence and a behavior sentence without losing content.

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

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

For a mutating, non-idempotent tool with no output schema, the description explains the core effect (new file created, queued for merge) but omits what the caller gets back, whether the contributed file replaces or coexists with existing fixes, and how to obtain the required device id. Adequate but with clear gaps.

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%, with all three parameters documented in the schema, so the baseline is 3. The description only touches firmware indirectly via 'as a new file for that firmware' and never mentions device or user_id, adding no meaning beyond the schema.

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

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

States a specific verb and resource (contribute a corrected variant of a driver) and describes the mechanism: builds a copy of the driver with learned CC/NRPN numbers and queues it for merge. It differentiates itself partly from submit_driver by grounding the action in learned mappings, but the relationship to that sibling is left implicit.

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 a clear triggering condition: use this where learned mappings (get_trust → mappings, differs: true) disagree with the driver on one firmware. It does not say when NOT to use it or name submit_driver/report_mapping as alternatives, so the agent must infer the boundary itself.

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