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 readOnly, idempotent and closed-world behavior, so the safety profile needs no restating. The description adds useful scope information by naming the record's components, including recalls, but omits behavioral details such as what happens for an unknown id and that a point-in-time view up to a year back is possible.

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 tight sentence with the resource and the key upfront and the returned fields listed after the colon, so nothing is wasted. It is a sentence fragment rather than a complete explanatory statement, which slightly limits readability for an autonomous agent.

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?

Two simple parameters and no output schema mean the enumerated return fields do real work here. Still, an agent gets no information about not-found behavior or the historical as_of dimension, and there is no output schema to fall back on for the response shape beyond the field list.

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 id parameter's format (pw_d_…) is fully documented in the schema, so the baseline applies. The description earns a small amount of extra credit by framing the id as the lookup key and hinting at the breadth of the returned record, though it adds nothing about the optional as_of parameter beyond the schema.

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

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

States a specific resource retrieved by a specific identifier ('the full record for a Pillwise drug id') and enumerates the contents (names, ingredients, form, strength, packages, recalls). It is clearly distinct from list/search siblings, though it does not explicitly contrast itself with the other identifier-based lookups (lookup_ndc, lookup_rxcui).

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 prerequisite is implied by 'for a Pillwise drug id', so an agent can infer this is the follow-up call once it holds a pw_d_ id. However, there is no explicit when-to-use statement, no mention of when to prefer lookup_ndc/lookup_rxcui/search_medications, and no guidance on using the historical as_of variant.

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, so safety is covered. The description still adds real value beyond them by disclosing the shape of what comes back — human-readable labels paired with values to send back — which matters because there is no output schema.

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 short sentences with no filler; the content description comes first and the id prerequisite second. The telegraphic phrasing ("…patch…", "values to send back") is efficient but borders on informal.

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 covers purpose, input provenance and the label/value return structure. Only the as_of temporal option and the exact return container shape are left unstated, both minor for this tool.

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

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

Schema coverage is 100%, so both parameters are fully documented in the schema, including the id prefix conventions and the as_of date-range rule. The description's "use the id from a search hit" largely restates the schema's own wording, and it never mentions as_of.

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 concretely — the forms (tablet, liquid, patch) and strengths a medication comes in — with parenthetical examples that remove ambiguity. It is clearly distinct from siblings like get_packages (packaging) or lookup_ndc, though it does not name those siblings 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 the key prerequisite and implies the call happens after a search_medications lookup. There is no statement of when not to use it, nor any pointer to the sibling tools (get_drug, get_packages) that cover adjacent data.

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 is covered. The description adds nothing on top: it does not say whether multiple packages come back, how the as_of historical lookup behaves, or what an empty result means. For a read tool with full annotation coverage this is thin but not contradictory.

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 clause with zero padding, and the key concept (package NDCs) is front-loaded. It reads as a sentence fragment rather than a complete statement of action, which costs a point.

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 read tool with no output schema, the description covers the core intent and the schema covers the parameters. It leaves open what a 'package NDC' contains and whether the result is a list of strings or objects, which an agent calling it cold would want to know.

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 with format examples. The description only echoes the id parameter in prose and says nothing about as_of, so it neither compensates nor detracts; 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?

The description states a specific resource and relationship: package NDCs belonging to a Pillwise drug id. An agent can tell it returns a collection of package-level NDC identifiers, though the verb is implicit and it never contrasts itself with siblings like get_form_options or 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?

No when-to-use guidance, no prerequisites, and no alternatives named. The agent must infer from the name and the required id parameter that this is the tool to reach for when it already holds a pw_d_ identifier.

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 readOnly, idempotent and closed-world, so the safety profile is covered. The description still adds genuine behavioral value with the matching rule: 'A bare 10-digit code is matched only as listed; no padding is guessed', which tells the agent that no normalization is performed and malformed-length inputs will not silently resolve.

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 format contract front-loaded and the caveat second; nothing is filler. The opening sentence is a verbless fragment, which slightly reduces readability but not information density.

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 return-value burden and only vaguely indicates the response contains 'the package and drug' — no shape, no not-found behavior, and no mention of how as_of changes the answer. Adequate for a simple two-parameter read, but incomplete.

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 would be 3, but the description goes beyond the schema's two examples by listing the full set of accepted layouts (4-4-2, 5-3-2, 5-4-1, product NDC) and the strictness of bare 10-digit matching. The optional as_of parameter is left entirely 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 precisely ('the package and drug for an NDC') and enumerates the accepted NDC forms, so an agent knows exactly what it gets back. It does not explicitly distinguish itself from siblings like get_packages, get_drug or lookup_rxcui, leaving the agent to infer the split from the input type.

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 only implied: the format enumeration signals 'call this when you hold an NDC', but there is no statement of when to prefer get_drug, get_packages, or lookup_rxcui instead. No exclusions or preconditions 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 declare readOnly, idempotent, and closed-world, so the safety profile is covered. The description adds nothing further — it does not explain the historical as_of capability, whether a single result or a set is returned, or what happens on an unknown RxCUI.

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 six-word fragment with zero waste and the key concept front-loaded, but the terseness comes at the cost of substance rather than being genuinely efficient. Not padded, but under-written.

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 should say what a lookup yields (a name, a structured drug object, an error for unmapped codes). It says none of this, and given the time-travel parameter it also omits that historical answers are possible.

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 format, as_of semantics) are already documented in the schema. The description adds no parameter meaning beyond that, 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 clinical drug for an RxCUI" conveys the direction of the mapping (RxCUI in, drug out), which lightly distinguishes it from lookup_ndc. But it is a noun fragment with no verb and leaves "clinical drug" as unexplained domain jargon, so the purpose is only vaguely specified.

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 when-to-use guidance at all. With siblings like get_drug, lookup_ndc, and search_medications in the list, the description never states that this is the reverse index (identifier → drug) nor when to prefer it over a name-based search.

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 cover the safety profile (readOnly, idempotent, closed-world), and the description goes beyond them by disclosing the shape and ranking of results: results come back as brand and ingredient groups ordered the way a person would pick, not as packages. It doesn't cover default result count or how the as_of lookback behaves, but that is secondary here.

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 search modality and match semantics lead, and the result-ordering caveat follows. Every clause carries information the agent needs.

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 return-value burden and does explain grouping and ordering. It is slightly thin on what a hit contains (identifiers, whether it is directly passable to get_drug or get_packages) for a discovery tool feeding a large sibling set.

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 adds meaning by telling the agent that the query may be a brand, an ingredient, or an everyday name — a semantic dimension the schema's 'what the person typed' does not convey. The explicit note that results are not packages further clarifies what the query matches against.

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 modality ('typeahead search') and a clear resource ('medication'), plus the three name forms it accepts (brand, ingredient, everyday name). The closing 'not packages' implicitly separates it from package-oriented siblings like get_packages, so an agent can route without opening a 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 word 'typeahead' plus 'what a person calls a medication' implies the autocomplete-when-the-user-types-free-text scenario, and 'not packages' hints at where get_packages belongs. But no sibling (lookup_rxcui, lookup_ndc, get_drug) is named and there is no explicit when-not statement, so the routing 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.