openfda-mcp-server

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

Annotations already declare readOnlyHint=true, so the description need not repeat safety. It adds valuable behavioral detail: sorting order, counting semantics ('append .exact'), and special handling for identifier fields (bare counting required). It also notes validation rejections (e.g., unbalanced quotes, backslash endings), which are useful edge cases. A small gap is not describing pagination or rate limits, but for a read-only aggregate tool the coverage is strong.

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 information-dense and front-loaded with the core action and output. It earns each sentence, but it is slightly long and the final pairing sentence could be seen as extra. Still, it is well-organized and not padded.

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 a rich schema (100% parameter coverage), a clear output schema, and readOnlyHint annotation, the description fills the gaps that matter: interpretation of results (ranking), use with sibling tools, and critical .exact behavior. An agent has enough to invoke correctly without surprise.

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%, yet the description elevates parameter meaning significantly. It explains when to use .exact, warns that certain fields reject .exact, gives a concrete search example, and clarifies the default/max limit. This goes well beyond the schema's bare descriptions.

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 states a specific verb ('Aggregate and tally'), a resource ('unique values for any field across any openFDA endpoint'), and the output format ('ranked term-count pairs sorted by count descending'). It clearly differentiates from sibling search tools by emphasizing aggregation over retrieval of records.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names six sibling tools as complementary partners for interpreting aggregates ('Pair with...'). It does not spell out when NOT to use this tool, but the pairing guidance strongly implies this tool is for aggregation and those others are for sample records, which is clear directional 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 declare readOnlyHint=true and idempotentHint=true. The description adds value beyond these by explaining row_count's full-scope meaning and warning that JSON columns hold nested objects needing DuckDB json functions. These are behavioral details not covered by annotations or schema, significantly aiding correct usage.

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 with zero redundancy. The core purpose and usage timing are front-loaded, followed by two essential caveats. Every sentence earns its place, making the description both compact and information-dense.

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 an output schema present (so return values need no explanation) and annotations covering read-only/idempotent behavior, the description supplies the remaining critical context: call order, row_count semantics, and JSON column handling. Nothing essential is missing for an agent to invoke this 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 input schema fully describes canvas_id (coverage 100%), including its source and the stage=true condition. The description adds no new parameter-specific meaning beyond reinforcing that the canvas comes from an openFDA search tool, which the schema already states. Per the baseline for high coverage, a 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 clear verb ('list') and specific resource ('tables and column schemas on a DataCanvas staged by an openFDA search tool'). It differentiates itself from siblings by positioning as a discovery step for the subsequent query tool, making its 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?

Explicitly instructs to 'Call before openfda_dataframe_query' to discover exact names and types, giving direct when-to-use guidance. It also clarifies row_count semantics ('full staged result set, not inline preview count'), preventing a common misuse. This fully addresses usage context.

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, and the description is consistent with and enriches them. It discloses the security boundary ('DDL, DML, COPY, and file-reading functions are blocked'), the row-cap behavior with the truncated flag, and crucially the storage semantics ('Scalar fields are stored as text (CAST for numeric math); nested objects/arrays are JSON columns') with a concrete json_extract_string example. This is exactly the behavioral context annotations cannot express, and it contradicts nothing.

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?

A single dense paragraph that front-loads the core purpose before layering preconditions, limits, type semantics, and restrictions. Every sentence carries distinct information (sequencing, truncation paging, CAST, JSON functions, blocked statements) with no filler. Slightly long, but the density is justified for a tool with this much operational nuance.

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?

An output schema exists, so return-value documentation isn't the description's burden. Given the tool's complexity, it covers the essential operational surface: how to reach the right table, how to handle truncation, how to deal with column typing, and the safety boundary. It omits nothing needed to make a correct first call; a worked end-to-end query paired with the describe output is the only optional addition.

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% — both canvas_id and query carry full descriptions with a worked SQL example. The description adds marginal value (the table name comes from openfda_dataframe_describe; canvas_id derives from a stage=true search), which aligns with the schema but does not materially extend it. Baseline 3 is appropriate when the schema already documents both parameters thoroughly.

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: 'Run a read-only SQL SELECT against a DataCanvas table staged by an openFDA search tool'. It clearly distinguishes itself from sibling search tools by explaining it operates on already-staged results rather than paging the API, and it names its companion openfda_dataframe_describe. An agent can tell exactly what this tool does and how it relates to the other openfda_* 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?

Explicit sequencing is given: call a search tool with stage=true to obtain canvas_id/canvas_table, and 'Call openfda_dataframe_describe first to get the exact table and column names'. Truncation handling is prescribed ('page the rest with ORDER BY plus LIMIT/OFFSET'). It does not enumerate which sibling tools NOT to use (e.g., openfda_count_values for simple aggregations), so it stops just short of fully routing alternatives, but the preconditions are clear and actionable.

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 readOnlyHint annotation already signals this is a safe read operation. The description adds behavioral context beyond that: it returns grouped categories with type and description, and emphasizes that field paths differ across endpoints. This is useful but does not describe the exact output structure; however, an output schema exists, so the return format is already documented. The description supplements annotations adequately.

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 two sentences with no filler. The core purpose is front-loaded, followed immediately by the usage context and the rationale for why this tool exists. Every sentence earns its place, and the structure makes it easy for an agent to quickly grasp the tool's role.

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 simple one-parameter discovery tool with an output schema already present, the description is fully complete. It explains what the tool does, when to use it, and why it's necessary, leaving no missing information that an agent would need to make a correct call. The presence of the output schema covers return values, so no further explanation is required.

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 input schema provides 100% coverage for the single 'endpoint' parameter, including an enum of valid values and a description. The tool description adds a rationale for why the endpoint parameter is needed (to identify the correct field paths), but does not provide additional syntax or format details beyond the schema. Given full schema coverage, 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 clearly states the tool's purpose: 'Return the searchable field paths for an openFDA endpoint, grouped by category with type and description.' It identifies a specific verb (return), resource (field paths), and the grouping/type/description outcome. This distinguishes it from sibling search/count tools, which operate on data rather than 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 explicit when-to-use guidance: 'Use before constructing a search query to find the correct dotted field path.' It also explains why (field paths differ per endpoint and are not discoverable from the schema). It does not explicitly name an alternative tool, but the context of 'before constructing a search query' implies the correct timing and alternative search tools. This is clear usage guidance but lacks an explicit exclusion statement.

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 annotation already declares readOnlyHint=true, so the safety profile is known. The description adds valuable behavioral context beyond that: fan-out in parallel, merging, best-effort sections that return null on misses, and reconciliation of identifier drift between endpoints. This goes well beyond the annotation, though it does not discuss rate limits or failure modes per sub-query, so not a 5.

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, each earning its place: the core action, the alternatives it replaces, the best-effort note, and routing guidance. The most important content (what it does) is front-loaded. No fluff or repetition of schema or annotation 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 complex tool that subsumes five siblings, the description covers purpose, selection criteria, alternative routing, and behavioral expectations. It respects that an output schema exists to document return structure. Nothing an agent needs to decide whether to call it and what to expect is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the parameter's description already explains accepted values (brand or generic) and the resolution behavior. The tool description does not add extra parameter syntax or format details, but the schema carries the load. Baseline 3 is appropriate; there is no gap to penalize or extra value to reward.

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 ('Resolve... then fan out... and merge') and resource (drug profile), and enumerates the concrete sections (identity, label highlights, adverse-event summary, recall history, approval, shortage). It explicitly names the sibling tools it replaces, making it distinct from openfda_get_drug_label, openfda_search_adverse_events, etc. without needing to inspect their schemas.

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 says explicitly when to use this tool (for a combined profile) and when not ('For deep dives into any one area, use the dedicated tool'), and names the exact alternatives. It also flags the rationale (identifier drift) and the best-effort behavior, leaving no ambiguity about selection.

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 readOnlyHint annotation already covers the read-only nature, so the description appropriately focuses on extra behavioral details: the token-size budget, the fallback to a section outline, and the need to re-call with specific sections. This adds genuine value beyond the annotation and does not contradict it.

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, then explains the important behavioral nuance in a single follow-up sentence. There is no filler or redundancy; every clause 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?

For a tool with 5 parameters and an output schema, the description covers the critical behavioral aspect—how large pages are handled and the sections mechanism—and mentions metadata inclusion indirectly via 'any structured label section.' The schema fills in parameter details, so the description is sufficient for an agent to understand what to expect, though it could briefly note the response structure beyond what the schema provides.

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 has a detailed description (e.g., search examples, sort pattern, limit scaling). The description adds only a minor hint about the 'sections' parameter through the re-call guidance, but nothing that substantially enhances understanding beyond the schema. 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 clearly states the tool's purpose: 'Look up FDA drug labeling' with specific examples of label sections (indications, warnings, dosage, etc.). It is immediately distinct from sibling tools that search for adverse events, recalls, or approvals, and the verb 'look up' matches the read-only intent.

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 when to use it (any time label content is needed) and provides a clear usage pattern for oversized pages: 're-call with sections to pull the ones you need.' It does not explicitly name alternatives or exclusions, but the domain is well defined and the fallback behavior is explained, giving an agent enough context to decide when this tool applies.

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, so the safety profile is covered. The description adds a useful integration hint (pairing with get_drug_label) and mentions output fields, but does not disclose additional behavioral traits beyond what annotations and the schema (pagination, limits) already describe. A 3 is the appropriate baseline.

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 with no wasted words: first states the core purpose, second lists searchable attributes, third gives a practical integration hint. The key 'look up drugs in NDC Directory' is front-loaded, making it instantly scannable.

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 rich schema (all parameters documented) and an output schema, the description provides all necessary high-level context, including a pointer to a related tool for further steps. Pagination, sort, and other details are covered schematically, so nothing essential is omitted.

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%, and all six parameters have detailed descriptions. The description adds no extra parameter-level meaning; only mentions output fields (brand_name, set_id) which is fine. Baseline 3 applies because the schema does the heavy lifting.

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 looks up drugs in the NDC Directory and enumerates the specific identifiers it can find (NDC code, active ingredients, packaging, manufacturer). This differentiates it from siblings like openfda_search_adverse_events or openfda_get_drug_label without needing to inspect schemas.

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 a concrete use case (identify drug products) and explicitly suggests pairing with openfda_get_drug_label using returned fields, which is actionable. However, it does not explicitly mention when not to use this tool or contrast with similar options like openfda_drug_profile, so it misses the full 'when-not/alternatives' 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 declare readOnlyHint=true, so the description does not need to state that this is a read operation. The description adds no behavioral detail beyond purpose; however, the input schema carries extensive behavioral notes (pagination limits, category-specific sort fields, staging behavior, byte budgets). Since annotations reduce the burden and the schema covers operational caveats, a score of 3 is appropriate rather than lower.

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 filler: the first clearly states the verb and resource, the second enumerates three concrete use cases. Every word earns its place, and the core purpose is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 7 parameters and a rich output schema, the description gives enough context for an agent to understand what the tool does and when to use it. It does not reference the operational complexities (pagination limits, category-specific sorting, staging), but those are fully documented in the schema. The description is complete for decision-making, though not exhaustive.

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%, and the schema provides thorough explanations for every parameter (skip pagination cap, sort field limitations, limit byte budget, search syntax constraints, category enum, staging semantics). The description itself adds no parameter-level meaning beyond what the schema already provides, matching the baseline for high coverage.

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 ('Search') and a precise resource ('adverse event reports across drugs, food, and devices'), and gives concrete use cases (investigate safety signals, find reports for a product, explore demographics). This clearly distinguishes it from sibling search tools for recalls, approvals, and animal events, even though no sibling is named.

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 explicit use cases ('investigate safety signals, find reports for a specific product, or explore reactions by demographics'), which implicitly tells the agent when to reach for this tool. It does not name alternatives or state exclusions, but given the domain-specific nature of the tool and the sibling set, the context is sufficient to guide selection.

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 declare readOnlyHint=true, so the read-only nature is already covered. The description adds context about the data fields (species, breed, age, reactions, outcome) but does not disclose pagination limits, staging behavior, or response format—these are handled in the schema. It neither contradicts annotations nor adds significant behavioral nuance beyond the safety hint, so baseline 3 is appropriate.

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 two sentences with no filler. The first sentence states purpose and data content, the second gives use cases. Everything earns its place and is front-loaded, making it easy for an agent to quickly grasp the tool's function.

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 detailed input schema (100% coverage) and an output schema, the description is sufficiently complete for correct invocation. It covers domain, data elements, and typical use cases. It doesn't repeat schema details, which is appropriate, though it omits nuanced behaviors like staging or pagination limits that are already documented in the 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%, and each parameter has a detailed description covering syntax, defaults, and edge cases (e.g., pagination limit, serialized size budget, staging semantics). The tool description adds minimal parameter-specific meaning, only implying the searchable fields. Baseline 3 is suitable because the schema already carries the full semantic load.

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 (search) and resource (adverse event reports for veterinary drugs and devices) and explicitly scopes to the FDA Center for Veterinary Medicine. It lists the record contents and distinguishes from the sibling openfda_search_adverse_events by specifying the veterinary focus, so an agent can tell them apart without opening schemas.

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 clear usage context: 'investigate safety signals for veterinary products, find reports by animal species or drug, or explore reaction patterns.' It does not explicitly mention when not to use it or name alternative tools, but the purpose and data scope make the intended use obvious. Lacks explicit exclusions but gives appropriate situational 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 declare readOnlyHint=true, so the description need not repeat that. The description adds no additional behavioral context (e.g., pagination limits, large-record implications, or error behavior). However, it does not contradict the annotation, and given the readOnlyHint coverage, a baseline score is appropriate.

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?

A single, front-loaded sentence that states exactly what the tool does with no filler. Every word earns its place; it is appropriately sized for a search tool.

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 7-parameter tool with an output schema and rich schema descriptions, the description is minimal but the schema covers parameter semantics and the output schema covers return structure. The main gap is the lack of usage guidance and behavioral context (e.g., mention that 510(k) records are larger than PMA records, which the schema does note). Overall, the description is adequate but not complete on its own.

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 all seven parameters documented in the schema (including detailed notes on each). The description itself contributes zero parameter-level meaning. Baseline 3 is fair because the schema fully carries the parameter 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 states a specific verb ('Search') and a resource ('FDA device premarket notifications') with explicit subtypes ('510(k) clearances and PMA approvals'). It clearly distinguishes from drug-related search tools like openfda_search_drug_approvals, but does not reference any sibling by name, so the differentiation is implicit rather than explicit.

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 no guidance on when to use this tool versus alternatives. It does not mention categories like 'use for device clearance documents' or contrast with drug-related searches. The sibling names exist (e.g., openfda_search_drug_approvals) but are not referenced, leaving selection entirely to the agent's inference from the resource name.

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 annotation readOnlyHint=true already conveys the read-only nature, lowering the burden on the description. The description adds that it returns 'application details, sponsor info, and full submission history', which is marginally beyond the annotation but not deeply behavioral (e.g., pagination, errors are left to the schema). No contradictions with annotations found.

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 exactly two sentences: the first front-loads the core purpose, and the second provides concise pairing guidance. Every phrase adds value; no redundancy or filler exists.

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 an output schema exists and the parameter schema fully documents all 6 optional parameters, the description covers the essential usage context. It explains where the data comes from, what it returns, and how to extend the workflow with complementary tools. Nothing critical for an agent to call the tool 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?

The input schema has 100% coverage with detailed descriptions for each of the 6 parameters, including pagination limits, sort syntax, staging behavior, and search examples. The description does not need to add parameter-level detail, so a baseline score of 3 is appropriate. It even hints at aggregatable fields (sponsor_name, product_type, route) which complements 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 states a specific verb ('Search'), resource ('Drugs@FDA database'), and scope ('drug application approvals (NDAs and ANDAs)'), making the tool's purpose unambiguous. It also distinguishes from siblings like openfda_search_adverse_events by focusing on approvals, and mentions the return content (application details, sponsor info, submission history).

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 explicitly recommends pairing with openfda_get_drug_label to read approved labels and openfda_count_values for aggregation, providing clear workflow guidance. It implies when to use this tool versus alternatives by naming the database and approval focus, though it does not explicitly exclude other search tools. The purpose is distinct enough that an agent can infer when to choose 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 carry readOnlyHint=true, lowering the safety burden. The description goes beyond this by disclosing exactly what is returned and the chaining behavior for the openfda block. Parameter descriptions add further behavioral context (pagination caps, staged_row cutoffs, sort rejection). No contradiction with 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?

Three front-loaded sentences with zero waste: purpose and returned fields first, then use cases, then chaining targets. Every sentence earns its place and the most decision-relevant info (what it does, what it returns) leads.

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 an output schema present, return values need no explanation in the description. Zero required parameters, all 6 params fully documented in the schema, and the description covers purpose, use cases, and cross-tool chaining. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed descriptions on all 6 parameters (pagination bounds, sort syntax, stage budget, search field examples, canvas_id semantics). Baseline 3 applies; the description itself adds no parameter details beyond what the schema already provides.

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+resource ("Search FDA drug shortage records") and enumerates the returned fields (status, availability, therapeutic category, dosage form, manufacturer, dates). It clearly differentiates from sibling search tools by scoping to the drug/shortages endpoint and names the two chaining targets (openfda_get_drug_label, openfda_lookup_ndc).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly lists concrete use cases: checking current shortage status, finding oncology drugs with supply issues, and retrieving the openfda block for chaining. The stage parameter additionally routes to openfda_count_values and openfda_dataframe_query as alternatives. It lacks an explicit when-NOT-to-use statement, but given the sibling set is all distinct endpoints, the guidance is sufficient.

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 only annotation is readOnlyHint=true, which is consistent with the 'Search' action, but the description adds no behavioral context beyond that. It does not mention pagination limits, result size budgets, staging behavior, or any other operational traits. The schema descriptions cover some behaviors (e.g., pagination cap, size budget), but the tool description itself is silent, so the agent must read the schema to learn these 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?

The description is a single, compact sentence that front-loads the purpose and includes the key categories. It is concise with no filler. However, it is so brief that it omits contextual guidance that would be useful for an 8-parameter tool, which slightly reduces its structural value despite its efficiency.

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 complexity (8 parameters, two endpoints, three categories, an output schema), a single-sentence description is insufficient. It does not explain the difference between the 'enforcement' and 'recall' endpoints, when to use one over the other, or any high-level usage nuances. The schema carries this weight, but the description fails to summarize key decisions or point the agent to relevant alternatives, leaving the agent to dive into the schema without guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool description contains no parameter information, but the schema provides 100% coverage with detailed descriptions for all 8 parameters, including defaults, constraints, examples, and behavioral notes (e.g., pagination cap, size budget for limit, staging behavior for stage/canvas_id). The description adds no meaning beyond what the schema already provides, so it meets the baseline for high schema coverage.

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 clear verb ('Search') and a specific resource ('enforcement reports and recall actions') across three categories (drugs, food, devices). It is unambiguous about the subject matter, though it does not explicitly differentiate from sibling search tools like openfda_search_adverse_events or openfda_search_device_clearances. The name itself is specific enough that an agent can infer its 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 provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, alternative tools, or any decision criteria. The parameter schema includes a note about staging vs. openfda_count_values, but that is buried in parameter descriptions and not surfaced in the tool description itself. An agent cannot tell from the description when to choose this over another search 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 readOnlyHint=true, and the description does not contradict that. The description adds minimal behavioral context beyond what annotations provide – it mentions the types of data captured but does not disclose pagination limits, error behaviors, or any side effects. Since annotations cover the safety profile, the description's extra information is useful but not extensive.

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, reasonably concise paragraph of three sentences that front-loads the core purpose and follows with examples of report content and use cases. It contains no filler or repetition, though it could be slightly tightened by moving some detail into the schema, but it remains efficient 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 description is complete enough for an agent to select and call the tool: it covers what the tool does, what data it returns, and common use cases. Output schema is present, so return details are covered there. It does not explicitly mention error conditions or rate limits, but those are documented in parameter descriptions. For a search tool with no required parameters and clear annotations, the contextual information is sufficient.

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 all six parameters (skip, sort, limit, stage, search, canvas_id) having detailed descriptions including examples and constraints. The tool description repeats some example search fields (e.g., reported_health_problems) that also appear in the schema, adding minimal new meaning. It does not compensate for any parameter gaps because there are none, so a 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 verb ('Search') and resource ('problem reports submitted to the FDA for tobacco products'), and enumerates the content of those reports (product type, health problems, product problems, etc.). It clearly differentiates from sibling search tools like openfda_search_adverse_events by explicitly scoping to tobacco products, making it unambiguous what this tool is for.

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 use cases ('investigate safety signals, find reports by product type, or analyze health effects') that indicate when the tool is appropriate. It does not explicitly name alternatives or state when not to use it, but the domain-specific language implicitly distinguishes it from other product-type search tools. This is clear context without explicit exclusions.

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