Drug Shortage List MCP

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

Annotations already cover readOnly, idempotent, openWorld and non-destructive, so the safety profile is handled. The description adds real behavior: the default scope (Current) and default grouping (therapeutic_category), plus the rule that status is ignored when grouping by status. The return shape is only implied by 'How many ... grouped by'.

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?

One dense sentence with the core action and grouping options front-loaded, followed by defaults. Every clause carries information; nothing is redundant padding.

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 two-parameter, no-required-argument aggregation tool with annotations and full schema coverage, this is nearly complete. The only real gap is that, with no output schema, the exact result shape (group key plus count pairs) is left to inference.

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 enums, so the schema carries most parameter meaning. The description goes beyond it by clarifying that grouping by 'drug' counts distinct products, which defines the counting unit, and by restating the defaults an agent needs to predict output.

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 aggregation verb and resource: counts FDA drug shortage listings, grouped by one of four dimensions. The aggregation framing distinguishes it from the sibling list/search tools, though it never names them explicitly.

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

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

Usage is implied rather than stated: an agent can infer this is for totals/breakdowns instead of browsing individual listings. There is no explicit when-to-use versus search_drug_shortages or list_recent_drug_shortages, and no exclusions.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds real behavioral context beyond that: it accepts two NDC granularities and returns the exact listing plus related packages of the same product, which tells the agent the response can be broader than the single code queried. It does not say what happens on a non-matching NDC.

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, zero filler, front-loaded with the resource and scope before the format detail. Every clause carries information about either input form or return scope.

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 one parameter, full schema coverage and an output schema absent, the description does the necessary work by sketching the return (exact listing plus related packages). It is adequately complete, missing only no-match behavior and any hint of the status values returned.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: that either a package NDC or a product NDC is valid and that the dashed form is required "as printed on the label." The label convention is a useful usage constraint beyond the min/max length bounds in the schema.

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

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

States a specific verb+resource ("FDA shortage status for one National Drug Code") and the singular scope ("one") that separates it from count/list/search siblings. An agent can tell this is a single-record exact lookup without opening the schema.

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

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

The phrase "for one National Drug Code" implies this is the single-record path versus the sibling search/list tools, but no alternative is named and no when-not-to-use condition is given. Guidance is implied only; an agent must infer that a partial name or unknown NDC belongs to search_drug_shortages.

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

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

The annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds real behavioral context beyond that: result ordering is 'most recently updated listings first' and results are scoped to status Current by default, both of which affect what the agent receives.

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 tight sentences with the resource and ordering front-loaded, and the filtering hint placed second. The opening is a noun phrase without a verb, which is slightly clipped, but nothing is wasted.

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, no-required-parameter read tool with a fully documented schema and a rich annotation set, the description covers ordering, default status, and filtering well. It does not mention return volume or whether limit truncates silently, but nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description earns an extra point by enumerating realistic therapeutic category values (Anesthesia, Oncology, Pediatric, Psychiatry, Cardiovascular, Infectious Disease), which meaningfully expands on the schema's single 'Oncology' example for a free-text field.

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 identifies a specific resource (the FDA drug shortage list) and its ordering (most recently updated first), which is enough to tell it apart from count_drug_shortages. It never states the verb 'list' nor explicitly distinguishes itself from search_drug_shortages, so the agent must infer that this is the unfiltered browse path.

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?

Useful defaults are stated (status defaults to Current) and a filtering path is implied via therapeutic category. However, there is no guidance on when to prefer this over search_drug_shortages or get_drug_shortage_by_ndc, and no exclusion conditions are given.

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

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

Annotations already establish read-only, idempotent, open-world behavior, so the description's real contribution is the provenance and freshness metadata: openFDA as source, updated daily, and a warning that training data cannot hold today's list. It also sketches the return structure (grouped by product, counts by status and availability, reasons, companies, presentations, dates), which the agent would otherwise not know without an output schema. It stops short of noting rate limits or pagination behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the user-facing question, then source, then lookup keys, then return shape — a sensible information hierarchy in four sentences. The example drug list partially duplicates the examples already in the schema, which is slight redundancy but not bloat.

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

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

For a read-only search tool with no output schema, the description supplies what the agent actually needs: data source, update cadence, accepted identifier types, and the shape of the results. What remains uncovered is alternative-tool routing and the effect of the status/max_presentations filters, but neither blocks correct invocation.

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

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

Schema description coverage is 100%, so all three parameters including the enum values and the 1-100 range are already documented. The description's parameter content largely repeats the schema (name types and example drugs) and does not explain the status or max_presentations semantics or how status filtering interacts with the grouped counts. Baseline 3 is appropriate when the schema carries this weight.

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

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

Specific verb (searches) plus named resource (FDA Drug Shortages database via openFDA) plus the exact lookup keys (generic name, brand name, active ingredient), with concrete example queries. It implicitly separates itself from get_drug_shortage_by_ndc and list_recent_drug_shortages by being the name-based search, but it never names those siblings to make the distinction 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 opening question "Is a drug in shortage now?" implies the use case well, and "Your training data cannot know today's shortage list" tells the agent when this data is required. However, there is no guidance on when to prefer count_drug_shortages, list_recent_drug_shortages, or get_drug_shortage_by_ndc instead, so the routing decision is left to inference.

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