Pillwise

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is fully covered by structured fields. The description adds the return content (served snapshot and build time), which is useful context, but says nothing about caching, refresh cadence, or format beyond that.

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 with no filler; every clause adds information (what is reported and the two data points).

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

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

With no output schema, the description is the sole source of return-value information, and it only vaguely indicates the payload (a snapshot identifier and a build timestamp). It doesn't specify format or fields, so an agent knows the gist but not what it will actually receive.

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 takes zero parameters, so there is no parameter semantics to document. Baseline 4 applies for a parameterless tool.

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 the specific resource and content reported: the served snapshot and its build time. It clearly distinguishes this status/metadata tool from the lookup siblings (get_drug, list_recalls, etc.). However, it is a noun phrase rather than a verb+resource, so the 'what it does' framing 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?

There is no guidance on when to call this tool versus the other catalog/status queries, nor any stated prerequisites or exclusions. The agent must infer that this is a freshness/version check, which is reasonable but not stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so safety and idempotency are covered. The description adds that the record includes recalls, which hints at composite content, but says nothing about the point-in-time behavior (as_of snapshots) or what happens with unknown/expired ids. With annotations doing the safety work, a 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?

A single sentence that front-loads the verb+resource and then lists the returned fields. No wasted words, and the most important scoping information ('full record') comes first.

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 two-parameter read tool with rich annotations and a full schema, the description covers what it returns. However, without an output schema, it gives no sense of return shape or size (how deep the nested record is), and it omits the as_of snapshot semantics that the schema only briefly hints at. Adequate but with clear gaps for an agent deciding coverage.

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 both parameters (id, as_of) are documented in the schema, including format hints. The description restates the id as 'Pillwise drug id' but adds no new meaning beyond the schema, so the baseline 3 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?

States a specific verb and resource ('full record for a Pillwise drug id') and enumerates the contents returned (names, ingredients, form, strength, packages, recalls). This clearly distinguishes it from siblings like get_packages, get_form_options, or list_recalls, which return subsets.

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?

No explicit guidance on when to use this tool versus alternatives. The sibling tools get_packages, get_form_options, and list_recalls cover overlapping data, but the description doesn't say to prefer get_drug for a complete record or when to use the narrower siblings instead. Usage is only implied by the word 'full'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and closed-world, so the safety profile is covered. The description adds one behavioral detail (that output carries human-facing labels plus values to send back), but says nothing about snapshot/retention behavior tied to as_of, which the schema merely documents factually.

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 compact sentences, front-loaded with what the tool returns and followed by the single precondition. No wasted text.

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 two-parameter read with full schema coverage and no output schema, the description conveys the content of the response (forms, strengths, labels, values) adequately. Minor gap: no mention of snapshot/retention limits around as_of, but the tool's complexity is low enough that this is not crippling.

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 both id and as_of are already documented in the schema. The description's 'use the id from a search hit' reinforces the id semantics but adds no format or range detail for as_of beyond what the schema provides; baseline 3 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?

States a clear verb+resource: it returns the forms (tablet, liquid, patch) and strengths a medication comes in. The added note about 'labels for people and values to send back' clarifies the shape of the payload, distinguishing it from sibling lookups like get_packages or lookup_ndc, though it never names an alternative 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?

'Use the id from a search hit' gives a concrete precondition, routing the agent to search_medications first. However, there is no statement of when to prefer this over get_drug, get_packages, or other sibling tools, so usage is implied rather than delimited.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds nothing behavioral beyond that: no note on how snapshots work with as_of, no hint about result size or ordering, and no indication of what a 'package' record contains.

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

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

It is a single short clause with no waste, but it is a sentence fragment without a verb and no front-loaded imperative like 'List the...'. Brevity here shades into under-specification rather than 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?

There is no output schema, so the description carries the burden of explaining what comes back, yet it only names 'NDCs' without describing fields, cardinality, or formatting. Combined with no usage guidance and no behavioral detail, an agent is left guessing about the return payload for a 2-parameter tool.

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

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

Schema description coverage is 100%, so the schema already documents both id (Pillwise drug id format) and as_of (day or RFC 3339 instant within retained snapshots). The description merely echoes the schema's id concept and adds no syntax or constraint detail, so the baseline of 3 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 states exactly what is returned (the package NDCs) and the keying concept (a Pillwise drug id), so the verb+resource is inferable even though the verb itself only appears in the title. It does not explicitly contrast with siblings like lookup_ndc or get_drug, which also deal with drug/NDC data.

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

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

There is no statement of when to call this versus alternatives – notably lookup_ndc, which operates on NDCs directly, or get_drug, which may also return drug-level data. The requirement of a Pillwise drug id faintly implies the precondition, but nothing is stated about exclusions or preferred order of calls.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety and repeatability are covered. The description adds the 'at least one filter' constraint, but says nothing about result size, ordering, pagination, or what happens with no filters at all.

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 terse sentence with the resource front-loaded and no filler. It is efficient, though slightly cryptic as a sentence fragment and it carries no verb ('List').

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

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

With no output schema and no required parameters, the description should clarify what a zero-filter call returns and what a recall record looks like; it does neither. The 'at least one of' requirement also appears to conflict with required=[], leaving the agent unsure whether an unfiltered call is legal or useful.

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 each parameter's meaning is already documented. The description contributes one genuine extra: the at-least-one-of relationship among ndc, drug_id and since, which the schema does not express. It omits the optional 'status' filter, so it does not exceed the schema baseline.

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

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

Names a specific resource (drug recalls) and states the filtering basis, so the resource is unambiguous versus sibling 'list_shortages' or 'get_drug'. It is not a full verb+resource sentence, but the name, title and filter clause together make the purpose clear 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 'filtered by at least one of ndc, drug_id or since' implies the intended call pattern, which is real usage guidance. However, it names no alternatives and gives no explicit when-not-to-use, so the agent must infer that 'list_shortages' covers a different resource.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds only the filter expectation and says nothing about result shape, ordering, or pagination; with annotations carrying the load, 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?

A single short sentence with the scoping constraint front-loaded and no filler. It is efficient, though the missing verb makes it read as a fragment rather than a crisp instruction.

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 three-parameter, no-output-schema read tool this covers the essentials, but it omits any note on what an unfiltered or status-only call does, which is a real gap given the schema declares zero required parameters.

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, and the description earns extra credit by stating that at least one of ndc or drug_id must be supplied — a constraint the schema contradicts with its empty required list. The status parameter's semantics (values like Current or Resolved) are left to 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 names the resource (drug shortages) and the filter keys, so an agent knows exactly what comes back. It lacks a verb and never differentiates itself from the similarly named sibling list_recalls, so it falls short of a 5.

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

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

"filtered by at least one of ndc or drug_id" conveys a usage constraint (a filter is expected), which is more than most siblings offer. However, there is no guidance on when to choose this over list_recalls or lookup_ndc, and no statement about what happens with status alone.

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

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

Annotations already declare readOnlyHint, idempotentHint and a closed-world non-destructive profile, so the safety burden is covered. The description adds a genuine behavioral rule — bare 10-digit codes are matched only as listed and never zero-padded — which affects results in a way the schema does not reveal. It stops short of describing not-found/error behavior or result shape.

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 zero filler; the accepted-input formats are front-loaded and the edge-case matching rule follows immediately. Every clause carries information an agent can act on.

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

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

With no output schema, the description carries the burden of explaining what comes back and does so only in the brief phrase 'the package and drug'. For a lookup tool that returns a nested package/drug payload, an agent would benefit from knowing the returned structure or the not-found case.

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 earns credit by enumerating the accepted hyphenation patterns (4-4-2, 5-3-2, 5-4-1) and stating the no-padding match rule, which is more precise than the schema's single 'Like 50580-488-10' example. The as_of parameter is not addressed in the description, keeping this below 5.

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 precisely what is returned ('the package and drug for an NDC'), so the agent knows the resource and payload shape. It does not, however, distinguish itself from close siblings like get_drug, get_packages, or lookup_rxcui that could plausibly serve overlapping needs.

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?

There is no when-to-use guidance at all — nothing says when to pick lookup_ndc over lookup_rxcui (the obvious alternative for code-system lookups) or get_drug/get_packages. All the prose is spent on input formatting rather than tool 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 already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so safety is covered. The description adds no behavioral context beyond that — it says nothing about snapshot retention semantics, error behavior for unknown RxCUIs, or what 'clinical drug' resolves to.

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 short fragment with zero filler and the key input front-loaded. It is efficient, though being a sentence fragment rather than a complete statement slightly undercuts clarity.

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?

This is a simple two-parameter read tool with full schema coverage, so little is required. But with no output schema, the description should explain the return value more precisely than the vague 'clinical drug', and it omits the snapshot behavior of as_of entirely.

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 both parameters (rxcui, as_of) are documented in the schema, which sets the baseline at 3. The description adds no extra meaning about format or the snapshot semantics of as_of, so it neither compensates nor detracts.

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 phrase names the resource being returned ('the clinical drug') and its key input ('an RxCUI'), so an agent can infer a mapping lookup. However, it is a bare noun phrase with no verb and it does not distinguish itself from near-identical siblings like get_drug or lookup_ndc, leaving the exact operation ambiguous.

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?

There is no statement of when to use this tool versus get_drug, lookup_ndc, or search_medications, and no mention of prerequisites or the snapshot behavior implied by as_of. The agent must guess which of the several lookup tools is correct.

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, and closed-world behavior. The description adds genuine behavioral context beyond them: results are grouped by brand/ingredient and ranked 'in the order a person would pick, not packages', which tells the agent about result shape and ordering.

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, front-loaded with the search behavior and then the result-ordering nuance. Every clause carries information; nothing is 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?

With no output schema, the description compensates by explaining the return grouping and ordering, and annotations cover the safety profile. It lacks only minor operational details such as what happens on no matches or how limit interacts with grouping, which is acceptable for a search 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%, so query, limit, and as_of are already documented in the schema. The description's gloss on query (brand, ingredient or everyday name) is broadly consistent with the schema's example but adds little new syntax or constraint detail, so the baseline of 3 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?

States a specific verb (typeahead search) and resource (medications via brand/ingredient/everyday names), and explicitly scopes it against package-level results, which differentiates it from siblings like get_packages and 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?

The 'typeahead' framing and 'what a person typed, at least 3 characters' semantics clearly convey the prefix-search use case, and 'not packages' steers the agent away from get_packages. However, no explicit when-not-relevant or named alternative (e.g. get_drug for a known exact drug) is given.

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