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

Annotations already cover read-only, idempotent and open-world behavior, so the description's value is in disclosing the shape of the result: identity, role, country, status, and importantly the exclusion of personal names, addresses and contact details. That exclusion is real context an agent cannot get from the annotations. Not found / empty-result behavior is left unstated.

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, no filler. The lookup scope comes first and the return/exclusion clause second, which is the right order for an agent scanning for eligibility.

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 summarizes return fields and privacy exclusions, which is the main gap it needed to fill for a single-parameter read tool. Missing only edge-case behavior such as an unknown or malformed identifier.

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 0%, so the description carries the burden and does so reasonably: it explains that actorId is either an SRN or a four-digit notified body ID, which gives meaning to the regex pattern in the schema. It stops short of giving an example SRN or clarifying where to obtain one.

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 ('look up') and resource ('actor'), and calls out the two accepted identifier types (SRN, four-digit notified body ID). The word 'exact' implicitly separates it from eudamed_discover_actors, but the sibling is never named, so 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?

'Exact' lookup implies this tool is for when you already hold a known identifier, and by contrast search-like intent belongs elsewhere. However, no alternative (e.g., eudamed_discover_actors) is named and there is 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?

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely non-obvious traits: upstream name matching may not be partial, exact=true performs local equality matching, and results carry no exhaustive-coverage or conformity guarantee. That caveat set is exactly the kind of context annotations cannot express.

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?

Four dense sentences, front-loaded with the precondition and then the exact/raw/return semantics in priority order. No filler, though the wording is compressed enough that terms like "normalized evidence and source provenance" require a second read.

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 steps in to describe the return shape (normalized evidence, provenance, optional raw device fields) and adds coverage/conformity disclaimers. Combined with annotations, an agent has enough to invoke it correctly; only the per-filter semantics remain thin.

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 20% across 10 parameters, so the description must compensate. It does explain the two behavior-changing toggles (exact does local equality, raw adds original device fields) that the schema leaves undocumented, but the seven identifier filters (basicUdi, primaryDi, reference, tradeName, deviceName, manufacturerSrn, language) remain unexplained and the phrase "restrictive filter" is never tied to specific fields.

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 ("Search public UDI records") plus the hard precondition of at least one restrictive filter. It clearly reads as a device search distinct from the actor/reference/investigate siblings, though it never names those siblings to sharpen 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?

"By at least one restrictive filter" gives a real precondition for use, and the exact/raw notes hint at when to escalate to stricter or richer results. But there is no explicit guidance on when to choose this over eudamed_actors or eudamed_investigate, and no statement of which parameters actually count as restrictive filters.

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, idempotent, open-world, non-destructive behavior. The description adds meaningful context beyond that: matching is exact rather than substring, results are deduplicated, source observations and a public-portal link are returned, and ambiguous SRNs must be resolved carefully. It does not mention rate limits or auth, but the annotation bar is lower here.

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, front-loaded with the core action and followed by return contents and a critical safety caution. Every sentence carries useful information, and there is no filler or repetition.

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 explains that results include deduplicated candidates, source observations, and a portal link. It also clarifies exact matching and the need to verify entity, country, and role before using an SRN. It remains incomplete around the limit parameter and role/country filtering, which are left to a mostly undescribed schema.

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 25%, so the description needs to compensate. It reinforces the name parameter's exact-match semantics and mentions country/role confirmation, but it does not explain the role filter, the country format or filter behavior, or the limit parameter. It adds some semantic value but leaves clear parameter gaps.

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: resolving a company name into organizational candidates. It also explains the output types (deduplicated candidates, source observations, portal link), making the tool's purpose clear. It does not explicitly distinguish this discovery tool from the sibling eudamed_actors retrieval tool, so it falls short of a 5.

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: use exact legal or abbreviated name searches and confirm legal entity, country, and role before using an SRN. The warning against inventing or silently picking an ambiguous SRN is useful workflow guidance. However, it does not name alternatives such as eudamed_actors or eudamed_investigate, nor state when not to use 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?

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.

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

The annotations already declare this a safe, idempotent, read-only, open-world operation, so that bar is lower. The description adds behavior that the annotations do not cover: the limit is applied locally rather than server-side, and ID is only meaningful when joined with CODE. Both are non-obvious operational facts.

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 two sentences with no filler, and the core action comes first, followed by the join-key warning. The trade-off is that the compression goes slightly too far, because 'Local limit only' is terse to the point of ambiguity.

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 ought to say what comes back: for example, a list of code/ID/label reference pairs. Instead it explains only how to filter, not what the reference values look like or how they relate to the codes found in the sibling tools. Adequate but incomplete for a 4-parameter decode 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 0%, so the description has to carry the burden. It names all four parameters (language, code, id, limit), which is better than nothing, but it does not say that language is a two-letter lowercase code, that code is a string up to 200 characters, or what 'local limit' actually bounds. It covers the parameters without explaining them.

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: it fetches reference values, scoped by language, with optional CODE/ID filtering. That is enough to identify it as the decode/reference lookup. It does not, however, contrast itself with siblings such as eudamed_devices or eudamed_actors, so the agent must infer which tool resolves codes.

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 real usage guidance on how to combine parameters: filter CODE and ID together, never ID alone. That is a genuine constraint on invocation. However it never says when a caller should reach for this tool instead of a sibling, such as 'use this to resolve codes returned by eudamed_devices,' so the usage context is only implied.

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