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

Goes well past the annotations: it discloses that the submission is validated (parses, lints, passes tests) before a merge job folds it into the public catalogue as its own file with source 'agent-contributed'. That is exactly the kind of post-call consequence (public exposure, gated acceptance) the annotations do not convey.

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 plus a short provenance instruction, with the purpose front-loaded before the validation and schema details. The parenthetical field enumeration is long but each element is load-bearing for building a valid payload.

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?

Covers the nested `driver` object via an external schema reference and describes the submission lifecycle, which is substantial for a tool with no output schema. It still does not say what the call returns (acceptance status, lint errors, a contribution id), which an agent would want to know.

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 already 80%, yet the description still adds real meaning for the required `driver` parameter: it must be the full file as a JSON object in the osc-bridge schema, with the expected top-level fields and a URL to the spec. It also reinforces provenance for `source`, though `firmware`, `note` and `user_id` are left to 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 driver') and immediately scopes it to 'a device the catalogue lacks (or a better one)', which distinguishes it from sibling write tools like submit_fix and report_mapping. An agent can tell what it produces without opening any 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?

Gives a clear trigger (a device with no driver, or a superior one) and implicitly excludes the report/submit-fix path since those exist for correcting existing mappings. It does not name an alternative sibling explicitly nor state prerequisites such as needing an account id, so it falls just 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.