Investigate device evidence

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

Annotations already declare read-only, idempotent, open-world and non-destructive, so the safety bar is low; the description still adds real behavior: a bounded execution deadline, separation of target evidence from portfolio context, identity-conflict reporting, preservation of failures/provenance/bounds, and a dual report/JSON response. It doesn't state rate limits or auth needs, but the added context is genuinely beyond the annotations.

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?

It is compact and front-loaded with the scoping phrase 'Bounded device investigation', but the body is a telegraphic pile of clauses ('decode fields', 'preserves failures, provenance and bounds') that reads as internal shorthand rather than guidance. Every clause is relevant, yet the noun-pile style hurts immediate comprehension.

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 11 parameters, zero required fields, 9% schema coverage and no output schema, the description needs to explain invocation preconditions. It does mention the return shape (concise report plus detailed JSON), which covers the missing output schema, but it never states that at least one identifier or manufacturer must be supplied, nor how the search paths combine — a material gap for a zero-required-parameter tool.

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 9% (only deadlineMs is documented), so the description must carry the load. It implicitly maps identifier params (basicUdi/primaryDi/reference) versus name params (tradeName/deviceName) via 'search identifiers first and names separately', and gestures at maxDevices/maxManufacturers/maxRepresentatives via portfolios and representatives, but it never explains the budget parameters, ranges, defaults, or how manufacturerSrn interacts with identifiers. Partial compensation only.

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 a specific composite operation (verify manufacturer, search identifiers then names, discover manufacturers, inspect portfolios/representatives, decode fields, list unverified documents) on the device resource. It excludes conformity decisions and certificate/IFU retrieval, but never positions itself against eudamed_devices, eudamed_actors or eudamed_discover_actors, so an agent must infer why it should pick this composite tool over the narrower 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 intra-tool ordering guidance ('search identifiers first and names separately') and two explicit out-of-scope exclusions ('No certificate/IFU retrieval or conformity decision'). However, it never says when to call this instead of eudamed_devices or eudamed_discover_actors, so the alternative-selection decision is left implied.

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