China NMPA Medical Device Data

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

Annotations already cover readOnly, idempotent, non-destructive, so the safety profile is clear. The description adds meaningful behavioral context beyond those annotations: 'Catalog matches only; does not determine certification or legal applicability,' 'No match returns an empty data array,' 'Missing required or invalid input produces an argument error,' and pagination/limits behavior. This gives the agent a good model of what happens at runtime. It doesn't state whether repeated calls with the same arguments return identical results aside from the idempotent hint, but the annotations cover that. The description is honest and consistent with the readOnlyHint.

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 a compact paragraph of seven sentences, which is appropriate for the complexity (4 params, pagination, error behavior, applicability caveat). It front-loads the purpose and required input, then covers return shape, scope limitation, no-match behavior, and error behavior in order. Each sentence adds value — no filler or repetition of the schema's parameter types. It's slightly dense and could be broken into bullets, but it is efficient and well-ordered.

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 paginated search tool with 100% schema coverage, detailed annotations, and no output schema, the description covers most agent needs: what it returns, edge cases (no match, errors), scope limitations, and pagination guidance. It doesn't specify the exact structure of 'pagination and limits' (e.g., what next_offset looks like) or the count of records returned, but the schema indicates pages and next_offset, and the description references the returned fields. It's nearly complete; a small gap is not explaining the relationship to snapshot for consistency across pages, though the schema covers that.

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 schema description coverage is 100% and parameters have detailed descriptions. The description adds a little beyond the schema: it calls out that 'product' can be product OR category text and notes the literal case-sensitive substring semantics is in the schema. It clarifies the structured record fields returned (source_class, provenance, snapshot, pagination, limits), which helps understand what the parameters relate to. Given high schema coverage, the baseline is 3; the description earns a 4 by semantically framing the product parameter (product/category text) and the snapshot parameter's role, adding value 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 ('Find'), resource ('CCC catalog product entries'), and search key ('product or category text'). It distinguishes itself from siblings by noting it returns structured records with provenance/snapshot/pagination, and by declaring 'Catalog matches only; does not determine certification or legal applicability' — separating it from tools like find_ccc_standard_references and find_license_catalog_items. An agent can tell exactly what this tool does without reading 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?

The description clearly implies when to use this tool: when you need CCC catalog product entries by product/category text, and gives exclusion criteria ('Catalog matches only; does not determine certification or legal applicability'), which tells agents not to use it when certification or legal applicability is needed. It does not explicitly name alternative sibling tools (e.g., find_license_catalog_items or find_ccc_standard_references), which would make routing even clearer. The context of 'catalog entries' plus the exclusion is strong but the when-not-to-use could name named alternatives.

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 meaningfully extends the readOnly/idempotent annotations by disclosing the paginated return shape, the specific fields returned (source_class, provenance, snapshot, pagination, limits), empty-data behavior on no match, and argument-error behavior on invalid input. This is substantial behavioral context beyond 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?

The description is compact and front-loads the purpose before returning to inputs, outputs, and edge cases. Minor redundancy exists in 'Inputs: standard_number' and 'Required: standard_number', but the overall structure is efficient and each major concern is addressed in a separate clause.

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?

Even without an output schema, the description conveys the essential return structure, pagination behavior, no-match behavior, required input, and error condition. Given the tool's simple parameter set and rich annotations, an agent has enough information to invoke it correctly 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?

Schema description coverage is 100%, so the schema already documents all four parameters in detail. The description only mentions standard_number and its required status, adding little beyond what the schema already states. This fits the baseline of 3 where the schema carries the semantic weight.

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?

Description opens with a specific verb and resource: 'Find occurrences of a recorded standard number in CCC reference metadata.' This clearly distinguishes it from sibling tools focused on products, standards metadata, or recalls. The added qualifier 'Reference occurrences only; does not imply equivalence or applicability' further sharpens the tool's scope.

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?

The description gives clear context on when to use the tool: to find recorded standard-number occurrences in CCC reference metadata. It also provides an implicit exclusion by warning that results do not imply equivalence or applicability. It does not name alternative sibling tools, but the boundaries are clear enough for an agent to route correctly.

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 meaningful behavior: paginated structured output with source_class, provenance, snapshot, pagination and limits; no inference/aggregation; snapshot-limited coverage; empty data array on no match; and argument errors for missing/invalid input. This is strong behavioral disclosure, especially with no output schema present.

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, front-loaded with the primary purpose, and every remaining sentence adds operational value: return shape, no-inference behavior, coverage limits, empty-result behavior, and error conditions. There is no filler or unnecessary elaboration.

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?

Given the tool's moderate complexity and no output schema, the description covers the essential operational details: required inputs, optional filtering, paginated results, result field categories, empty results, error handling, and snapshot scoping. An agent has enough information to call the tool correctly and interpret the response shape.

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 the schema already explains every parameter, including exact-match and substring-match semantics. The description adds only a high-level mention of 'country' and 'institution' inputs and that country is required, which is redundant with the schema. Therefore 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 action ('Find'), a concrete resource ('recorded institutions and roles for a country'), and an optional filter ('institution text'). It also clarifies the tool's scope as a read-only query over recorded facts, which distinguishes it from aggregation or inference tools among the 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?

The description gives clear context: use it to retrieve recorded country-institution facts with optional institution filtering, and it notes that no new inference or aggregation is performed. It does not explicitly name alternatives or state when not to use it, but the usage context is unambiguous enough for an agent to select it appropriately.

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, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral details: it performs no inference or aggregation, coverage is limited to the available snapshot, no match returns an empty array, and invalid input causes an argument error. These go beyond the annotations and inform the agent of expected behavior, including error handling. No contradiction.

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 concise, front-loads the purpose, and uses several short sentences to cover purpose, returns, behavior, and errors. Every sentence adds information without fluff.

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 read-only query tool with fully documented parameters and annotations, the description is complete. It covers purpose, return structure (paginated records with source_class, provenance, snapshot, pagination, limits), behavioral guarantees (no inference, snapshot-limited, empty array on no match), and error handling. No critical information is missing for an agent to call it 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 covers all 4 parameters with detailed descriptions (product, limit, offset, snapshot). The description only restates that product is required and mentions error on invalid input, which adds minimal semantic value beyond the schema. Since schema coverage is 100%, the baseline is 3, and the description does not significantly enhance parameter understanding.

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 (Find), resource (licence catalog entries), and method (by recorded product or commodity text). Distinguishes from siblings like find_ccc_products by specifying the domain (licence catalog) and the search mechanism. Clear and specific.

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 context that it searches recorded text and returns structured records, but does not explicitly state when to use this over sibling find tools like find_ccc_products or find_country_institutions. No exclusions or alternatives are mentioned, so an agent must infer usage from the domain name. The description does mention limitations (snapshot coverage) but no comparative 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 mark this as read-only and idempotent, and the description adds valuable behavior: paginated structured records, no-match returns an empty array, invalid input returns an argument error, and no legal inference is made. This goes well beyond 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?

The description is front-loaded with the main purpose and stays compact while covering outputs, limitations, and edge cases. There is minor redundancy between 'Inputs: rule_number' and 'Required: rule_number', but overall the structure is efficient.

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 read-only, parameter-light lookup tool with no output schema, the description is complete: it names the return fields, states pagination behavior, explains empty results, and documents error behavior. An agent has enough to call and interpret the result 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 description coverage is 100%, so the parameters are already well documented. The description mentions rule_number and pagination/limits but adds little semantic detail beyond what the schema provides, so the baseline score of 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 opens with a specific verb and resource: 'Find recorded versions and dates for a CCC rule number.' This clearly differentiates it from sibling tools by focusing on rule version history rather than products, standards, or trade statistics.

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?

The description gives practical usage context by noting it returns 'recorded version facts only' and clarifying it 'does not infer legal applicability.' This is a useful boundary, though it does not explicitly name alternative tools for other use cases.

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 and idempotentHint=true, but the description adds substantial behavioral context: return fields, pagination and limits, snapshot semantics ('not a historical-version selector'), empty-array behavior on no match, and argument-error on invalid input. This goes well beyond the structured annotations and is not contradicted.

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 moderately long but well-structured, front-loading the core purpose and then covering inputs, returns, limitations, required fields, and errors in logical order. Each sentence adds information; there is little redundancy, though it could be tightened by merging the required-fields sentence into the input sentence.

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 7 parameters, no output schema, and no annotations for return structure, the description does a good job of covering return fields, pagination, snapshot behavior, edge cases, and required inputs. It lacks explicit guidance on when to use sibling tools, which is a minor gap given the complexity, but the tool's scope is clearly bounded.

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 the baseline is 3. The description repeats required fields and briefly mentions aliases, but it does not add significant parameter-level meaning beyond what the schema already documents (e.g., commodity matching behavior is described in the schema as 'Recorded major-commodity name or a selected exact Chinese alias'). The limitation on fuzzy translation is more behavioral than parameter-semantic.

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 ('Query') and resource ('China import or export observations'), scoped by 'recorded major-commodity label.' It clearly distinguishes itself from translation/HS-code tools and implicitly differentiates from siblings focused on country trade, investment, or MOFCOM stats.

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?

The description states when to use the tool (for exact commodity labels with optional metric) and explicitly what it does NOT do ('not general translation or HS-code classification', 'No category merging or conversion'). However, it does not name any sibling tools or provide explicit conditions for choosing between them, relying on implicit differentiation from the resource type.

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 mark it read-only/idempotent, and the description adds useful behavioral detail beyond that: the returned fields (units, scope, source_class, provenance, snapshot, pagination, limits), empty data array on no match, and argument errors on invalid input. This gives an agent a clear model of what happens when the tool is called.

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 every sentence earns its place: purpose, input orientation, semantics, return contents, exclusions, edge cases, and error behavior. The main action and scope are front-loaded before the parameter details.

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 tool with six parameters, annotations, and no output schema, the description covers the essential operational contract: required inputs, optional flow, return fields, no-match behavior, invalid-input behavior, and limitations. Combined with the schema's detailed parameter documentation, nothing critical is missing for correct invocation.

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 adds meaning beyond the schema by explaining the flow enum in plain terms (IMPORT/EXPORT/BOTH), clarifying that TOTAL means all partners, and noting that units are currently 1000USD. This is modest but real added 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?

The description states a specific verb and resource: 'Query China merchandise trade by partner country/region', and immediately clarifies the special 'TOTAL' aggregate. It also draws a clear boundary from the commodity-level sibling by saying 'No commodity filter', so an agent can tell this tool apart from get_customs_commodity_trade.

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?

The description gives clear context for use (period + country + optional flow), names the required inputs, and states exclusions ('No commodity filter or currency conversion'). However, it does not explicitly name an alternative tool for commodity-level queries or otherwise say 'use X instead', so it stops just short of full when/when-not/alternative 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 and idempotent annotations, the description discloses several behavioral traits: no inference or aggregation, snapshot-limited coverage, empty data array on no match, and argument errors on missing/invalid input. These are substantive and not present in 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?

The description is compact and front-loaded with purpose, then inputs, return format, and behavioral notes. Each sentence is informative, though the final sentences covering required input and errors could be merged for slightly better economy.

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?

Since there is no output schema, the description compensates by naming return record fields (source_class, provenance, snapshot, pagination, limits) and the empty-array behavior. Combined with the detailed schema, an agent has enough to invoke the tool correctly, though the meaning of each return field is only summarized.

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 the baseline is 3. The description adds a high-level mention of year, country, and metric and notes that year is required, but it omits limit, offset, and snapshot from its summary. The schema already fully documents each parameter, so the description contributes little beyond the baseline.

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 uses a specific verb ('Find') and a clear resource ('foreign-investment observations') plus filter dimensions (statistical year, country, measure). It states the core action unambiguously, but it does not explicitly differentiate this tool from sibling tools by name.

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?

The description implies usage context by stating 'Recorded facts only; this query performs no new inference or aggregation' and 'Coverage is limited to the available snapshot', which suggests when raw recorded facts are needed. However, it never names an alternative tool or gives explicit when-to-use / when-not-to-use 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 and idempotent annotations, the description adds valuable behavioral details: it performs no inference or aggregation, returns only recorded facts, is limited to the available snapshot, returns an empty data array on no match, and raises argument errors on invalid inputs. This goes well beyond what annotations alone 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?

Every sentence earns its place: purpose, inputs, return shape, behavioral guarantees, error behavior, and coverage limits are all stated without fluff. The primary action is front-loaded before secondary details.

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 read-only query with five well-documented parameters and no output schema, the description covers what is returned, pagination-relevant fields, empty-result behavior, error behavior, and snapshot limitations. An agent has enough information to call this tool correctly without needing additional context.

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%, and each parameter already has detailed descriptions covering exact matching, bounds, defaults, and snapshot semantics. The description only names issue and document_number, adding no new meaning 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 opens with a clear verb and resource: 'Find entries in a gazette issue', and adds an optional filter by document number. This clearly differentiates it from sibling tools, none of which target gazette items.

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?

The description gives a clear use context: querying a gazette issue by label, optionally filtered by document number. It does not explicitly name alternatives or when-not-to-use conditions, but the resource-specific phrasing makes the intended usage unambiguous.

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 non-destructive behavior, so the safety profile is covered. The description adds useful context by stating that the tool takes no arguments and returns only the standard document, not records or facts, but it does not describe the document's structure or any pagination/format details.

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 with no wasted words. The core purpose is front-loaded, and the clarifying exclusions ('not business records or an assessment of facts') are valuable for agent decision-making.

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 zero-parameter, read-only, idempotent tool, the description is complete enough. It tells an agent what the tool returns, what it does not return, and that no arguments are needed. The lack of an output schema is offset by the clear high-level description of the document.

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?

There are zero parameters, and the description explicitly confirms 'Takes no arguments,' so there is no ambiguity about invocation. Baseline for zero-parameter tools is 4, and the description removes any doubt about whether arguments are needed.

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 ('Retrieve') and a clear resource ('definitions of information formation classes, provenance fields and snapshot/version metadata'), and further clarifies that it returns the information-standard document rather than business records or factual assessments. It is clear on its own, though it does not explicitly differentiate itself from likely-related siblings such as get_standard_metadata.

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?

The description implies its use case: call this tool when you need the standard definitions/metadata document, and it explicitly says it does not return business records or factual assessments. However, it does not name alternatives or explain when to prefer this over sibling tools like get_standard_metadata or search_standard_metadata.

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 goes beyond the annotations by detailing the return payload (units, scope, source_class, provenance, snapshot, pagination, limits), stating that no conversion/aggregation/cross-period calculation occurs, and describing behavior on no match (empty array) and errors. This adds significant behavioral context beyond the readOnly and idempotent hints.

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 concise and front-loaded with the primary purpose, followed by inputs, exclusions, return behavior, and error handling. Each sentence serves a clear function, and there is no redundancy or filler. It is appropriately sized for a query tool with several parameters.

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?

Given there is no output schema, the description compensates by specifying return fields and pagination limits, and clarifies error and no-match behavior. It also explains the required period and the distinction between periods and snapshots. The description is largely complete for an agent to use the tool correctly, though it could benefit from a brief mention of how it differs from the sibling trade tools.

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 all parameters are already described in the schema. The description only mentions 'period and optional country, flow and metric' without adding new semantic detail; it does note that periods are not interchangeable, which is also present in the schema. The description adds little beyond the schema for parameter understanding.

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 the tool queries trade observations from two distinct collections (country-workbook and China–Portuguese-speaking-country bilateral), and explicitly notes it is not China national all-partner monthly totals. It names the verb 'Query' and the resource 'trade observations', but does not explicitly differentiate from sibling tools like get_customs_country_trade, which also handle trade data.

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?

The description provides context on what data is included (country-workbook and bilateral observations) and excludes China national monthly totals, but it does not offer explicit guidance on when to use this tool versus the sibling tools. The exclusion hints at scope but no alternatives are named or conditions given for switching.

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 destructiveHint, but the description adds crucial behavioral details: it performs no new inference or aggregation, coverage is limited to the available snapshot, returns an empty data array on no match, and produces an argument error on invalid input. These go beyond the annotations and fully disclose behavior.

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 a compact paragraph that front-loads the purpose, then covers return format, safety, and error conditions. It is not overly verbose, but the line 'Inputs: record_id' is somewhat redundant given the schema and the later mention of required. Still, it is well-structured and readable.

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 adequately explains the return payload (paginated structured records with specific fields), pagination behavior, snapshot handling, and error cases. It covers all essential aspects an agent needs to call the tool correctly, making it complete for a retrieval 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 coverage is 100% with detailed descriptions for all parameters. The description only repeats that record_id is required, adding no new meaning to limit, offset, or snapshot beyond what the schema already provides. This meets the baseline but adds little 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?

The description clearly states the verb 'Retrieve' and the resource 'recall notice or detail record' using an existing search-result identifier. It distinguishes itself from search tools by emphasizing it operates on an existing identifier, and clarifies it returns recorded facts without inference or aggregation, making it unambiguous.

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 states the tool retrieves using an existing search-result identifier, which implies prior use of a search tool like search_recalls. It does not explicitly name alternatives or say when not to use, but the context is clear enough for an agent to infer the appropriate usage scenario.

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 readOnly and idempotent, but the description adds substantial behavioral context: it discloses the return format (source_class, provenance, snapshot, pagination), the empty data array on no match, and the argument error on missing/invalid input. These are not implied by the annotations and give the agent precise expectations.

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, front-loading the core purpose and then detailing behavior and requirements. It avoids fluff but includes some redundancy (e.g., 'Inputs: standard_number' and 'Required: standard_number') that could be trimmed. Overall it is well-structured and not overly verbose.

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 read-only metadata retrieval tool with a well-documented schema, the description covers the essential aspects: what it returns, what it does not return, empty result behavior, and error handling. Pagination mechanics are implied by 'paginated' and the schema's offset/limit/snapshot details, which is sufficient given the schema's richness. Minor gaps like the meaning of source_class/provenance are acceptable without an output 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 100%, so every parameter is fully documented in the schema. The description adds minimal parameter-specific value beyond restating that standard_number is required and that invalid input yields an error, which is more about error behavior than parameter meaning. Baseline 3 is appropriate given the schema's thoroughness.

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 the tool retrieves standard metadata given a known standard number, and explicitly distinguishes it from returning full text. It also names the primary input (standard_number) and the output type (paginated structured records), making its purpose unambiguous and differentiating it from search tools like search_standard_metadata.

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?

The description provides a clear usage condition: use when the recorded standard number is known. It also clarifies what the tool does not do ('no standard full text'), implicitly steering users to other tools for full text. However, it does not explicitly name alternative tools or state when not to use it beyond that condition, so it stops short of full 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 goes well beyond the readOnlyHint and idempotentHint annotations by disclosing that the query performs no inference or aggregation, is limited to the available snapshot, returns an empty data array on no matches, and raises argument errors for missing or invalid input. These are concrete behavioral traits 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?

The description is compact and front-loaded: purpose first, then return shape, then behavioral caveats, then errors. Every sentence contributes useful information, and there is no redundant or filler 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?

Even without an output schema, the description provides the important return characteristics: paginated structured records, specific fields, empty behavior, snapshot limitation, and error behavior. Combined with the comprehensive input schema, an agent has everything needed to invoke the tool 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 description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds no parameter-level detail beyond stating that company is required cancels; it does not improve on the schema's literal-match, pagination, and snapshot semantics.

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: 'Find recorded medical-device products associated with a company or registrant name.' This clearly states what the tool returns and the key lookup dimension, making it easy for an agent to distinguish it from device-specific or category-based search 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?

The description gives clear context for when to use this tool: when querying by company/registrant name and when only recorded snapshot facts are needed. It explicitly excludes inference and aggregation behavior, which helps an agent choose this over more analytical alternatives, though it does not name specific sibling tools or provide explicit when-not-to-use conditions.

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 (read-only, idempotent, non-destructive), the description discloses that the query performs no inference or aggregation, is limited to the available snapshot, returns an empty array on no match, and raises argument errors on invalid input. These are substantive behavioral details not present in 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?

The description is compact and front-loaded with the primary purpose, followed by inputs, returns, and behavior. A small amount of redundancy ('Inputs: udi' and 'Required: udi') and the error sentence could be trimmed, but overall every sentence earns its place.

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 appropriately summarizes the return shape (paginated records, source_class, provenance, snapshot, pagination, limits) and covers no-match and error behavior. It relies on the thorough input schema for pagination defaults and next_offset semantics, which is acceptable.

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 the baseline applies. The description only restates that udi is required and does not add parameter-level details about limit, offset, or snapshot; it does clarify error behavior for missing required input, which is mild added 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 and resource: 'Look up medical-device records when a UDI identifier is known.' This clearly identifies the exact-match lookup purpose, and the mention of a known UDI implies a distinction from search-based siblings, 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?

Provides a clear usage condition ('when a UDI identifier is known'), and notes that no match or invalid input yields specific results. It does not name alternative tools or state when-not-to-use in relation to siblings, so it stops short of explicit routing.

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, idempotentHint=true, and destructiveHint=false. The description adds meaningful context beyond that: it states 'performs no new inference or aggregation', notes 'Coverage is limited to the available snapshot', and explains empty results and error behavior. These details enrich the agent's understanding of call outcomes without contradicting 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?

The description is front-loaded with the core purpose, then flows into inputs, return behavior, and error conditions. It is succinct with no filler, though it repeats 'registration_no' twice (in 'Inputs' and 'Required'), which is a minor redundancy. Still, every sentence contributes critical information, earning a 4.

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 tool with four parameters and no output schema, the description is remarkably complete: it explains pagination, snapshot behavior, empty results, and error handling. It references 'source_class, provenance, snapshot, pagination and limits' as return elements, but does not detail the structure of each record, which would push it to a 5. Given the constraints, it is well-rounded and sufficient for correct invocation.

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 each parameter already fully documented in the input schema. The description adds only marginal value on parameters, mentioning registration_no as required and hinting at pagination via 'paginated structured records'. It does not go beyond the schema's detailed parameter descriptions, so the baseline of 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 clearly states the tool's purpose: 'Find medical-device records associated with a registration or filing number.' It specifies a precise verb and resource, and the input registration_no makes the scope distinct from sibling tools that search by company or device. However, it does not explicitly name or differentiate from siblings, so it stops 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?

Usage is implied rather than explicit: the tool is for when you have a registration or filing number, and 'Required: registration_no' reinforces that. But the description provides no guidance on when not to use it or how it compares to alternatives like get_udi_company_products or search_udi_products. This matches the 'implied usage' level.

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 destructiveHint=false, and the description adds meaningful behavioral detail beyond them: no new inference or aggregation, snapshot-limited coverage, empty data array on no match, and argument errors on invalid input. This gives the agent a clear picture of what will and will not happen.

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 appropriately sized and front-loads the core purpose in the first sentence. The behavioral notes and return format are dense but useful. There is minor redundancy ('Inputs: query' and 'Required: query') but it does not significantly detract.

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?

Given there is no output schema, the description compensates well by naming the return structure (source_class, provenance, snapshot, pagination, limits) and edge behaviors (empty array, argument error). Combined with fully documented parameters, an agent has enough context to invoke and interpret results 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 description coverage is 100%, so the schema fully documents all four parameters, including query matching semantics, pagination limits, and snapshot behavior. The description only restates that query is required and mentions 'Inputs: query', adding no substantive parameter 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?

The description clearly states a specific verb ('Find') and resource ('policy and document facts'), with a precise lookup method ('by title or document-number text'). It distinguishes this from analytical or inference tools by emphasizing 'Recorded facts only', but it does not explicitly contrast itself with sibling search tools like search_recalls or search_standard_metadata.

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?

The description gives clear context for when this tool is appropriate: only for recorded policy/document facts, not for inference or aggregation. It also sets expectations about snapshot coverage. However, it does not name alternative tools or state explicit exclusion conditions, leaving some routing to inference.

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 says 'an empty result does not establish absence of recalls,' which is an open-world claim. The annotations declare openWorldHint=false, meaning closed-world semantics. This directly contradicts the annotation, so the score is 1.

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 and front-loaded with the purpose. Some redundancy exists ('Inputs: query' and 'Required: query') and the error sentence is slightly redundant with the schema, but overall it is efficient and well-organized.

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 explains the return envelope (source_class, provenance, snapshot, pagination, limits), explicitly describes no-match and error behavior, and relies on the rich parameter schema for invocation details. This is sufficient for an agent to call the tool 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 schema covers 100% of parameters with detailed descriptions, including literal case-sensitive substring matching, limit/offset constraints, and snapshot semantics. The description adds little beyond redundant mentions of 'query' and 'Required', 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 action ('Find') on a clear resource ('recall notices and detail records') with search dimensions (product, manufacturer, title text). This distinguishes it from sibling get_recall_record, which implies single-record retrieval, without needing to inspect 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?

The context is clear: this tool is for text-based searching of recall notices by product, manufacturer, or title. It does not explicitly name alternatives or exclusions, but the use case is evident and no misleading guidance is present.

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 provide read-only, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond those: it returns only metadata (no full text), returns an empty data array on no match, and describes the paginated record fields and error behavior for missing/invalid input. This gives the agent a richer picture of what to expect.

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 leads with the core purpose in the first sentence. Some slight redundancy exists ('Inputs: query, status' and later 'Required: query'), but each clause does add a distinct piece of information: result fields, no-full-text limitation, no-match behavior, and error handling. It is efficient without being terse.

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?

Given the 5-parameter schema with full coverage and the presence of read-only annotations, the description supplies enough operational context: required input, optional filter, paginated response shape, no-match outcome, and error semantics. It does not explicitly explain how to use next_offset for continued pagination, but the schema already covers that. The main missing piece is alternative-tool guidance, which is more of a usage-guideline issue than a completeness gap.

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 the schema already fully documents all five parameters with detailed semantics (literal case-sensitive match, exact status match, pagination offsets, and snapshot behavior). The description only restates 'query, status' and 'Required: query,' which adds no new meaning beyond the schema. Baseline 3 is therefore 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 verb ('Find'), resource ('standard metadata'), and search criteria ('by title text, optionally filtered by its recorded status'). It is clear about what the tool does, but it does not explicitly contrast with sibling get_standard_metadata, so the differentiation is implied 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?

The description conveys how to use the tool (query is required, status is optional) and touches on return behavior, but it offers no explicit when-to-use-versus-alternatives guidance. The sibling list includes get_standard_metadata, yet the description never says 'use this for title search; use get_standard_metadata for exact identifier lookup.' Usage context is implied but not explicit.

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?

Adds meaningful behavior beyond the read-only/idempotent annotations: no inference or aggregation, snapshot-limited coverage, paginated structured records, empty array on no match, and argument error on invalid input. This is exactly the context 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?

Four sentences with the purpose and return shape front-loaded, followed by edge cases and requirements. Minor redundancy ('Inputs: category' vs 'Required: category') but no wasted 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?

For a read-only paginated search tool with rich schema and annotations, the description covers return structure, pagination fields, no-match behavior, snapshot limitation, and errors on missing/invalid input. Nothing an agent needs to invoke 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 covers all four parameters at 100%, so the description only needs to add marginal semantics. It reiterates that category is required and notes validation error behavior, but does not add details 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 ('Find') and resource ('medical devices by a recorded category name or classification code'). Clear and distinct from sibling tools by naming the category-based scope, though it does not explicitly contrast with search_udi_products.

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?

Implied usage is when searching devices by recorded category or code, but there is no explicit when-to-use guidance or mention of alternatives. No exclusions or conditions compared to sibling tools are provided.

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 and destructiveHint=false, so the safe, read-only nature is covered. The description adds valuable behavioral details: it performs no inference/aggregation, is limited to the available snapshot, and returns empty data array on no match. This goes beyond the annotations, justifying a 4.

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 a single paragraph with no filler, front-loading the primary purpose and then covering key behaviors. Every sentence adds value—purpose, behavior, coverage, and error handling—without redundancy. It is concise and well-structured.

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?

The tool is moderately complex with four parameters, but the schema covers all parameter semantics. The description explains pagination and snapshot behavior, and the annotations cover safety. It lacks explicit details on return value structure, but output schema is absent, so the description does not need to over-explain returns. A 4 is appropriate for completeness.

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 four parameters in detail. The description reinforces the required nature of 'query' and notes the empty-array behavior on no match, which complements the schema. Since coverage is high, the baseline is 3, but the description adds useful context about the query behavior, moving it to 4.

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 the verb 'Find' and the resource 'medical devices by product or trade-name text'. It distinguishes this tool from siblings like get_udi_device (which likely fetches a single device) and search_udi_category (which searches by category), making the purpose unambiguous.

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 provides clear context on how to use it (search by product/trade-name text, returns paginated records, requires query). It does not explicitly name alternatives or conditions for when not to use it, but the sibling names (e.g., search_udi_category) imply alternatives exist, so a 4 is appropriate.

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