openfda-mcp-server

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

Annotations already provide readOnlyHint=true, so no safety contradiction. The description adds valuable behavioral detail: returns ranked term-count pairs sorted by count descending. It doesn't mention rate limits or edge cases, but the annotation lowers the bar.

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, front-loaded with purpose, and no wasted words. The pairing guidance is placed effectively without diluting the primary 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 schema covers all parameters and an output schema exists, the description is complete. It explains the return format, general scope, and complementary tools, making it fully contextual for an agent.

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 parameters are fully documented. The description adds no extra parameter semantics beyond what the schema already provides, 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 clearly states the verb 'Aggregate and tally unique values' and the resource 'any field across any openFDA endpoint'. It distinguishes this tool from siblings like openfda_describe_fields or search tools by focusing on aggregation and ranked counting.

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 usage context by suggesting pairing with specific search tools when sample records help interpret aggregates. However, it does not explicitly state when not to use this tool or compare it with dataframe_query/describe fields.

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 and idempotentHint, so safety is covered. The description goes further by explaining key behaviors: row_count reflects the full staged result set (not preview count), and JSON columns require DuckDB json functions. This adds actionable 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 three sentences with the primary purpose front-loaded. Subsequent sentences provide essential usage context and data behavior notes. No redundant or filler content; 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 an output schema present and strong annotations, the description covers all needed context: purpose, usage relationship to query tool, row_count semantics, and JSON query tips. This is complete for a metadata-discovery tool.

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

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

Schema description coverage is 100% because the single canvas_id parameter is fully described with its source and condition. The description reinforces that canvas_id comes from a staged search, but adds no new semantic detail 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 states a specific verb and resource: 'List the tables and column schemas on a DataCanvas.' It clearly distinguishes from siblings by focusing on schema discovery for a staged openFDA search, and explicitly names openfda_dataframe_query as the follow-up tool.

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 explicit when-to-use guidance: 'Call before openfda_dataframe_query to discover the exact table name, column names, and DuckDB types needed for valid SQL.' This also implies not to use it for querying data itself, and it names the alternative 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 indicate read-only and idempotent behavior, but the description adds valuable context: row limit with truncation/pagination, scalar fields stored as text requiring CAST, nested objects as JSON columns using DuckDB functions, and explicit blocking of DDL/DML/file-reading. 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?

The description is longer than average but each sentence contributes essential information: purpose, usage flow, truncation behavior, data type handling, and restrictions. It is front-loaded with the core purpose and remains 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?

For a complex SQL query tool, the description covers prerequisites (describe), row limit behavior, data type specifics, example usage, and security restrictions. An output schema exists, so return values are not needed in the description. This is comprehensive.

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 both parameters fully, but the description adds practical usage details: query should use the table name from describe, canvas_id comes from an openFDA search tool response when stage=true. An SQL example further clarifies the query parameter.

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 runs a read-only SQL SELECT against a DataCanvas table staged by an openFDA search tool. It distinguishes itself from sibling tools by focusing on querying staged data, while siblings like openfda_count_values and openfda_dataframe_describe serve different purposes.

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 instructs to call openfda_dataframe_describe first for exact table and column names, and notes that the tool enables grouping and aggregation without re-paging the API. It also states restrictions (only SELECT, DDL/DML blocked), which implies when not to use.

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 only declare readOnlyHint=true. The description adds useful context by explaining that the tool groups results by category with type and description, and that field paths are not discoverable from the schema alone. This goes beyond the annotation without contradicting 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?

Two concise sentences with the main purpose front-loaded and no filler. Every clause adds value, making it highly scannable and effective.

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 single-parameter metadata tool with a detailed schema and an output schema present, the description sufficiently covers purpose, usage timing, and output composition. It is complete for what the agent needs to select and invoke 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?

The single parameter endpoint is fully covered by the schema's enum and description (100% coverage). The description reinforces that field paths vary by endpoint but does not add new parameter-level detail beyond what the schema already provides, 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 clearly that it returns the searchable field paths for an openFDA endpoint, grouped by category with type and description. This is a specific metadata/discovery purpose that distinguishes it from sibling query/search tools.

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

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

The description explicitly instructs 'Use before constructing a search query to find the correct dotted field path' and notes that field names differ per endpoint. It provides clear context for when to use, though it does not explicitly mention when not to use or name 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?

Beyond the readOnlyHint annotation, the description discloses behavioral traits: parallel fan-out, best-effort per-section with null returns instead of failures, and identifier drift reconciliation. This is rich, accurate context that helps the agent predict failure modes and execution model without contradicting 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 three sentences: purpose and contents, differentiation from chaining, and fallback behavior with alternative guidance. Every sentence adds value, no filler, and the most important usage context 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?

Given the tool's complexity (composite of five endpoints) and the presence of an output schema (which covers return value structure), the description adequately covers execution flow, per-section best-effort behavior, and alternatives. It is complete enough for an agent to select and invoke correctly without further clarification.

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 parameter description already includes brand/generic examples and the canonical identifier resolution note. The tool description adds no new parameter-level semantics beyond what the input schema provides, 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 clearly states the tool resolves one drug name to FDA identity and merges results from multiple endpoints into a single profile, listing the exact sections (identity, label highlights, adverse events, recalls, approvals, shortages). It explicitly distinguishes itself from siblings by positioning as a replacement for chaining multiple dedicated tools.

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

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

Explicit when-to-use: 'Replaces chaining...' and when-not-to-use: 'For deep dives into any one area, use the dedicated tool.' It names the exact alternative tools, providing clear guidance for selecting this composite tool vs. focused siblings.

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 readOnlyHint annotation, the description discloses a key behavioral trait: oversized pages return a list of available sections instead of the full label, requiring a re-call with the sections parameter. It also explains the reason (labels run to tens of thousands of tokens), adding valuable context not captured in 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 two sentences, front-loaded with the primary purpose, and every sentence earns its place by adding behavioral context. No redundancy or 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?

Given the rich input schema (100% coverage) and the presence of an output schema, the description is fully complete. It covers purpose, the main usage scenario, and the critical behavioral quirk (section outline for oversized pages), leaving no ambiguity for the agent.

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 only a brief mention of re-calling with sections, which is already detailed in the schema's sections parameter description. It does not materially enhance parameter understanding 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 uses a specific verb+resource pair ('Look up FDA drug labeling') and enumerates concrete use cases (indications, warnings, dosage, etc.), which clearly distinguishes it from sibling tools like adverse events or recalls. It also explains the behavior with sections, adding unique purpose context.

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 the tool (when needing structured label sections) but does not explicitly name alternatives or exclusions. It says 'Check indications, warnings, dosage...' which establishes context, but lacks an explicit 'use this instead of X' or 'not for Y'.

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 the tool readOnlyHint=true. The description adds the pairing hint about output fields but does not disclose additional runtime behavior such as pagination limits, rate limits, or error conditions (those are covered by the input schema). 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?

The description is exactly two sentences, front-loaded with the core purpose, and every clause earns its place. No redundant repetition of schema 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?

Given the rich input schema, the existing output schema, and readOnly annotation, the description provides sufficient context: it explains the NDC domain, the capabilities, and the natural workflow to get package labels. No critical context 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 describes all 6 parameters with 100% coverage, including examples and edge cases. The description adds no additional parameter-level meaning, so it stays at the baseline 3.

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 ('Look up drugs in the NDC Directory'), lists concrete capabilities (identify by NDC code, active ingredients, packaging, manufacturer), and distinguishes the tool from sibling openfda_get_drug_label by referencing a pairing workflow.

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 a clear workflow: use this tool for NDC directory lookups, then pair with openfda_get_drug_label using brand_name or set_id for the package insert. It doesn't explicitly state exclusions or alternative selections among other siblings, but the context is clear.

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 discloses the read-only nature, and the description's 'Search' is consistent with that. But the description adds no further behavioral context beyond the schema-provided parameter details—no mention of pagination caps, response size limits, or staging behavior. Since annotations carry the safety profile and the description merely restates the verb, it does not meaningfully advance transparency.

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, front-loaded with the core purpose, and every phrase earns its place. The use-case list is compact and directly useful. No filler or repetition of schema 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?

The description covers the main purpose and clearly signals appropriate use cases. Given the rich input schema, output schema, and readOnly annotation, the overall tool context is adequately complete. It doesn't explicitly mention cross-category field differences or the staging option, but those are covered in the schema parameter descriptions, so no critical guidance 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 description coverage is 100% with rich detail on every parameter (e.g., category-specific sort fields, pagination limits, search syntax). The tool description only offers high-level use-case context ('across drugs, food, and devices') that maps to the category parameter but adds no technical meaning beyond what the schema already provides. The baseline of 3 for full schema coverage applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Search adverse event reports across drugs, food, and devices,' which names a specific verb (search), a clear resource (adverse event reports), and an explicit scope (drug, food, device). It also lists concrete use cases (investigating safety signals, product-specific reports, demographic reactions) that distinguish this tool from sibling tools like openfda_search_recalls or openfda_search_drug_approvals.

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 intended uses: 'investigate safety signals, find reports for a specific product, or explore reactions by demographics.' It does not, however, mention when NOT to use this tool or name alternatives (e.g., openfda_count_values for server-side aggregations), so it falls short of the explicit exclusion/alternative guidance needed for a 5.

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

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

The readOnlyHint annotation already communicates the safe read-only nature, so the bar is lower. The description adds useful context about record contents (species, breed, drug name, VeDDRA terminology, outcome), but it does not disclose behavior like pagination limits or return shape beyond what annotations and the rich schema already provide.

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 three sentences and front-loaded: purpose, record contents, and usage guidance. Every sentence earns its place, with no redundancy or filler.

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 a fully documented 6-parameter schema, a readOnly annotation, and an output schema, the description supplies the essential scope and search intent. It is complete for a search tool and does not need to restate return values already covered by the 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?

All 6 parameters are fully documented in the schema with detailed descriptions, examples, and constraints (e.g., the 25000-record pagination cap and 24000-byte serialized budget). The tool description itself adds no parameter-specific semantics, but at 100% schema coverage 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 uses a specific verb ('Search') plus a resource ('adverse event reports for veterinary drugs and devices') and identifies the FDA CVM as the submitting body. It clearly distinguishes this tool from the sibling openfda_search_adverse_events by emphasizing the veterinary/CVM 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 explicit use cases: 'investigate safety signals for veterinary products, find reports by animal species or drug, or explore reaction patterns.' It does not name alternatives or exclusions, but the context makes appropriate use clear.

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 safety profile is already known. The description adds the domain scope (510(k) and PMA) which is useful, but it does not mention key behavioral traits such as the pagination cap at 25000 records, the serialized size budget, staging behavior, or query validation rules. These appear in the parameter descriptions, not in the tool description itself, so the top-level description offers modest added transparency.

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 one compact sentence, front-loaded with the verb and resource, and contains no filler. It efficiently conveys purpose without redundancy, earning a top score for conciseness.

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 comprehensive schema descriptions and the presence of an output schema, the overall tool definition is complete enough for an agent to select and invoke it correctly. The main description is brief but sufficient for purpose identification; all complex behavioral details are delegated to the parameter descriptions, leaving no critical gaps. A slightly richer top-level description could have helped, but the structured fields fill the need.

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%, meaning every parameter has its own description, so the baseline is 3. The top-level description adds no parameter-specific guidance beyond what the schema already provides. While the parameter descriptions are rich and include examples, edge cases, and alternatives, that richness is part of the schema, not the tool description, so no extra credit is warrantable.

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 the specific verb 'Search' with the resource 'FDA device premarket notifications' and explicitly names the two subtypes '510(k) clearances and PMA approvals'. This unambiguously identifies the tool's domain and distinguishes it from sibling search tools for adverse events, drug approvals, and recalls.

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 top-level description pins down the exact use case (device clearance searches), making when-to-use obvious. It lacks an explicit contrast with sibling search tools, but the schema's stage parameter provides a clear alternative ('for a distribution over everything that matched, openfda_count_values aggregates server-side in one request'), giving at least one explicit usage guideline. No exclusions are stated but the context is clear.

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 no side-effect disclosure is needed. The description adds that the tool returns full submission history, which is a useful behavioral detail, but it does not mention pagination or size constraints (those live in parameter descriptions). With the read-only annotation covering safety, this is adequate but not rich.

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 three sentences, each with a distinct role: purpose, results, and companion tools. 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?

Given an output schema and a detailed input schema, the description does not need to explain return values. It provides a clear overview and points to related tools for next steps, though it could briefly contrast with other openFDA search endpoints for full contextual 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?

All 6 parameters have thorough descriptions in the schema, including default values, bounds, and error conditions, so schema description coverage is 100%. The tool description itself does not add parameter semantics beyond the schema, making the baseline 3 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 'Search the Drugs@FDA database for drug application approvals (NDAs and ANDAs)', giving a specific verb, resource, and target. It also distinguishes itself from siblings by naming complementary tools, making the scope clear.

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 tells the agent to pair this with openfda_get_drug_label for labels and openfda_count_values for aggregation, providing clear alternatives for follow-up tasks. However, it does not state when to avoid this tool versus other search tools like openfda_search_adverse_events, falling short of full exclusion 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 readOnlyHint annotation already communicates that the tool is read-only. The description adds a bit of context about the returned data and chaining possibilities, but it does not disclose any behavioral traits beyond that—no mention of pagination limits, staging side effects, or error conditions. It is not misleading, but it does not enrich the annotation with deeper behavioral context.

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 three sentences long and front-loaded with the core action and resource. Every sentence adds value: the first states what it does, the second lists return fields, and the third gives concrete use cases and chaining hints. It is concise, well-structured, and contains no filler or repetition.

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

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

The tool has six parameters and an output schema, and the description plus schema together cover the essential usage scenarios. The description provides clear use cases and chaining options, while the schema covers parameter nuances like pagination and staging. It does not explicitly mention aggregation alternatives, but the stage parameter description points to openfda_count_values, and the output schema presumably documents return fields. Overall, the description is sufficiently complete for an agent 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% and every parameter has a detailed description (e.g., skip's pagination cap, limit's serialized budget, stage's canvas behavior, search's syntax and examples). The tool description itself adds no parameter-level detail beyond mentioning the returned fields and the openfda block for chaining, which is redundant with schema examples. Since the schema handles parameters thoroughly, a 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 opens with a specific verb and resource ('Search FDA drug shortage records'), identifies the endpoint's distinct domain ('drug shortage records'), and enumerates the returned fields ('status, availability, therapeutic category...'). It also differentiates from sibling search tools by naming the resource type and giving concrete use cases, making the tool's purpose unmistakable.

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 explicit use cases: 'check whether a drug is currently in shortage, find all oncology drugs with supply issues, or retrieve the openfda block... to chain into openfda_get_drug_label or openfda_lookup_ndc.' This clearly states when to use the tool, though it does not explicitly say when not to use it or mention alternatives like openfda_count_values for aggregations. The stage parameter description fills some of this gap, but the main description lacks direct exclusion 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 merely states 'Search' with no disclosure of pagination limits, possible errors, or the staging behavior described in the schema. The readOnlyHint annotation covers the safety profile, but the description adds no behavioral context beyond a trivial read-operation implication. It does not contradict the annotation, but it is silent on any side effects or limitations.

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, focused sentence with no filler or redundancy. It delivers the essential purpose without wasting tokens, which is ideal for an agent scanning tool definitions.

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 an 8-parameter tool with an output schema and a readOnly annotation, a one-sentence description is thin. However, the schema descriptions are exceptionally rich, covering pagination bounds, endpoint availability, and staging semantics. The description is sufficient for a high-level orienting, but it relies heavily on structured fields to provide the full context needed 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?

The input schema has 100% description coverage for all eight parameters, including detailed semantics for skip, limit, search, and stage. The tool description itself adds no parameter-level information, so it neither helps nor hurts. Baseline 3 is appropriate because the schema already documents every parameter.

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 ('Search') and names the resource ('enforcement reports and recall actions') and scope ('drugs, food, and devices'). This distinguishes it from sibling tools like openfda_search_adverse_events, which target a different dataset. It clearly conveys the tool's core function in a single sentence.

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 does not mention when to use this tool over alternatives or when not to use it. There are no exclusions or alternative tool references; usage is only implied by the resource scope. The parameter schema does include some endpoint guidance (e.g., recall only for devices), but that is not part of the tool description itself.

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 include readOnlyHint: true, and the description does not contradict this. However, the description adds no behavioral context beyond the read-only hint, such as pagination limits or error conditions (though the schema covers these). Given the annotation, a mid-range 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?

The description is three concise sentences: the first states the core action, the second enumerates report contents, and the third lists use cases. Every sentence adds value with no redundancy or 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?

With a rich schema and output schema present, the description appropriately focuses on domain purpose and typical use cases rather than repeating technical details. It is complete enough for an agent to understand when and why to invoke it, though it does not mention how it relates to sibling aggregation 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 description coverage is 100%, so the schema already fully documents all parameters. The description adds domain context (e.g., report fields like product type and health problems) but does not directly elaborate on parameter usage beyond the schema, aligning with the baseline of 3.

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 ('Search') and resource ('problem reports submitted to the FDA for tobacco products'), further specifying product categories. This clearly distinguishes it from sibling tools like openfda_search_adverse_events or openfda_count_values.

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 clear use cases: 'investigate safety signals, find reports by product type, or analyze health effects.' It provides context for when to use the tool but does not explicitly mention alternatives or exclusions, which would merit a 5.

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