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

Annotations already mark it as a non-read-only, non-destructive, closed-world write. The description adds substantial context beyond annotations: writes data/devices/<id>.yaml, requires ODB_REPO, creates a stub for unknown devices, and instructs the agent to open a PR using commands in the 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?

Three front-loaded sentences cover the action, stub behavior, and write/PR workflow. Parentheticals are dense but every clause contributes operational 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?

It covers the critical write target, ODB_REPO dependency, stub creation path, PR follow-up, and expiry behavior. It leaves unstated what happens when an active claim already exists or how conflicts and force_new are handled, which is a meaningful omission for a claim operation.

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 parameter meanings are fully documented in the schema; the description repeats key fields like scope/contact/expiry and unknown-device vendor/model/category. It adds some workflow context but no semantic detail beyond the schema, so 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?

The description states a specific verb and resource: recording a claim on a device for reverse engineering, including scope, contact, and expiry. It is clearly distinct from lookup/search/publish in practice, but it does not explicitly name or contrast sibling tools.

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 context: use it when about to reverse engineer a device and to avoid duplicate work, and it explains stub creation for unknown devices. It stops short of explicit when-not guidance or naming alternatives such as lookup_device/search_devices/request_device.

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 establish read-only, non-destructive, closed-world behavior. The description adds meaningful behavioral context beyond that: it covers only imported sources and warns that absence from this list does not imply absence from all possible sources.

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, both front-loaded and purposeful: the first lists the returned fields, the second states usage and the key coverage caveat. There is no redundant restatement of the title or annotations.

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 input parameters and no output schema, the description carries the burden of explaining the return shape, and it does so by enumerating the source fields and curated-record count. It also supplies the main interpretive caveat an agent needs to use the output correctly.

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?

The tool has zero parameters, so parameter semantics are not a source of ambiguity. The schema is empty and the description does not need to explain input values.

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 identifies the resource as imported source databases and enumerates the metadata returned (name, url, license, snapshot date, record count, curated count). It distinguishes this source-catalog listing from the device-centric sibling tools, though it does not explicitly contrast with a named alternative.

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 explicitly says to use the tool to judge coverage and freshness, and adds a useful caveat that a missing device may still be covered by a non-imported source. No competing sibling performs the same listing function, so omitting named alternatives is acceptable.

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 establish read-only, non-destructive, closed-world behavior, and the description adds real substance on top: the meaning of a `found: false` result, what `install` routes contain (guide, installer, difficulty, safety flags), and that live claims have an expiry. It stops short of describing pagination, rate limits, or matching ambiguity between conflicting identifiers.

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 imperative and the payoff, then the identifier-priority tip and the fallback branch. Dense but every sentence carries actionable information; the parenthetical device list and example recommendations add a little bulk without much cost.

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?

No output schema exists, so the description correctly takes on the burden of explaining what comes back (existence answer, live claims, recommendation string, install routes) and what to do on a negative result. For a zero-required-param, read-only lookup tool this is sufficient to call correctly.

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 baseline is 3, but the description adds non-obvious semantics the schema does not: identifiers (FCC id, USB vid:pid, BLE name, Zigbee model) match better than names, which tells the agent how to prioritize among the seven optional inputs. It doesn't explain precedence when multiple identifiers are supplied.

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 ('look up a device') and enumerates exactly what the lookup returns: protocol/free-firmware existence, live claims, and a one-line recommendation with example values. It also implicitly separates itself from search_devices (identifier lookup, not browsing) and claim_device (the follow-up when nothing is found).

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?

Explicitly says 'CALL THIS FIRST' before reverse engineering, scoping the when-to-use condition. It also names the alternative path: 'If it answers found: false, nothing is known: call claim_device before starting,' giving a clear when-not/next-step rule.

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 past the annotations: it spells out the exact merge rules per field (status forward-only, interfaces by transport+name, projects by url, install routes by method+guide, union of identifiers/aliases, verification appended), guarantees atomicity ('nothing is written on error'), and states content-policy limits and provenance honesty requirements. This is exactly the behavioral context annotations cannot 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?

Front-loaded with the call trigger, then merge semantics, then policy and next step — a rational order with no filler. It is dense and long-ish, but nearly every clause carries operational 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 complex nested-patch mutation with no output schema, the description covers the merge model, error atomicity, policy constraints, provenance obligations, and the post-call workflow. Nothing an agent needs to call it correctly 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 coverage is 100%, so the baseline is 3; the description earns above that by explaining the merge/replace semantics that the schema only partially documents (which fields union vs. replace vs. append), which is the key thing an agent must reason about when composing a patch.

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 — merge published findings into the device record — and immediately frames the trigger condition ('when you finish or stop a reverse-engineering job'). The per-field merge semantics make it unmistakably distinct from lookup_device, search_devices, claim_device, and request_device.

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?

Explicitly says when to invoke it, including the edge case of stopping with partial results, and describes the follow-up step (open a pull request; the result gives the commands). It does not name sibling tools or state when NOT to use it, which keeps it 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 name and title suggest a write/submission operation, but the description explicitly corrects this: it "never posts anything," only returns a link the user reviews and submits, which reinforces the readOnlyHint annotation with concrete detail. It also discloses the two possible return shapes (existing request vs. pre-filled link), which no annotation or schema conveys.

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 sentences: trigger condition first, then return behavior, then safety qualifier. Every sentence adds distinct information, with no repetition of the title or schema.

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 seven parameters, a 100% described schema, and no output schema, the description supplies exactly what's missing: the result shape (upvote target vs. new-issue link) and who submits it. Nothing an agent needs in order to call this correctly is absent.

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 seven parameters, including vendor, model, usb, fcc_id, and goal, are already documented well enough in the schema. The description adds no parameter-specific guidance, such as what to do when the USB ID is unknown; a baseline 3 is appropriate when the schema does all the work.

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?

Conveys a specific action (file a request for a device to be supported) and explains the mechanism clearly: it returns an existing GitHub request to upvote or a pre-filled link to a new one. It differentiates itself from lookup_device by naming it, but does not distinguish itself from claim_device or publish_findings, which an agent could plausibly confuse with this one.

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 when your user wants a device to become usable with open code but will not reverse engineer it themselves (lookup_device found nothing usable)" states both the selecting condition and the precondition tied to a sibling tool. It effectively defines the when-not case (if lookup_device found something, this tool isn't appropriate).

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=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds real behavioral context the annotations lack: what fields are matched, that results are ranked, which datasets are included, and that each result carries an id for chaining into lookup_device. Pagination/limits are left to the schema.

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 tight sentences: what it searches, when to use it, and what you do with the output. No filler, and the most decision-relevant information (scope plus sibling alternative) is front-loaded.

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 4-parameter read-only search with 100% schema coverage and no output schema, the description covers purpose, sourcing, and the key output affordance (id → lookup_device). Only minor gaps remain, such as mentioning the limit default or that an empty query lists everything, both of which the schema already carries.

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 baseline would be 3, but the description adds interpretive value by showing how query strings can combine vendor/category language across the indexed fields, which the per-parameter text does not illustrate. It does not, however, touch the status/category filters that constrain result shape.

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 opens with a specific verb and resource ("Ranked full-text search over vendor, model, aliases and identifiers") and names the corpus it searches (curated records plus imported OpenWrt/Zigbee2MQTT/Tasmota databases). It is clearly separable from the sibling lookup_device, which it names directly.

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 explicit use cases with example queries ("all DJI drones", "open-firmware cameras") and a concrete fallback rule: use this when lookup_device finds nothing and another name is suspected. The boundary against the alternative tool is stated, not inferred.

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