KinToolkit: Medicine Dosage Calculator Label References for Children and Infants

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

Annotations declare readOnlyHint=false while the description reads like a pure lookup ('resolve', 'lists'), and it never discloses what, if anything, the non-read-only behavior mutates — tail risk left unexplained. It does add useful behavior beyond annotations: clarification guidance on ambiguous matches, source attribution, and telemetry exclusion.

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 core purpose and packed with dense, relevant rules; there is no filler. Slightly run-on with several distinct constraints concatenated, but every sentence carries a usable 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?

An output schema exists, so return-value shape needn't be re-explained, and the description still notes sources and clarification guidance. The main residual gap is the unexplained non-read-only annotation, but for a 3-optional-filter lookup this is largely complete.

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 and descriptions, so baseline is 3; the description adds value by mapping colloquial product names to specific filter combinations (brand+audience, ingredient) that the schema alone doesn't convey. It also reinforces 'combined filters must all match,' though some schema text is repeated.

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 (resolve) and resource (ordinary public product names / medicine labels), and clarifies it returns matching calculator bottles plus separately marked reference-only formulations. Distinct from siblings like get_label_directions and list_calculator_bottles, which the name alone might confuse.

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?

Provides concrete mapping examples (Children's Motrin → brand motrin + audience children; Walmart → brand equate), states 'omit filters only when unspecified,' and warns that unlisted brands are unsupported rather than substituted. Strong when-to-use guidance, though it never names which sibling to use for adjacent tasks (directions, question guides).

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 mark this as not read-only and not idempotent, which would otherwise be confusing for a lookup, and the description supplies the missing context: minimal operational telemetry records no arguments or results. It also discloses the return shape and the boundary that suitability for a child is out of scope. It does not state error behavior for mismatched product/label_band pairs, keeping it below 5.

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

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

Front-loaded with the core action, then the identifier-sourcing rule, then the return summary. Sentences are dense but every one carries information; the telemetry sentence is slightly awkwardly worded but earns its place as a privacy disclosure.

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

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

An output schema exists, so return values need not be exhaustively explained, yet the description still summarizes them usefully. The main remaining gap is failure behavior for incompatible product_id/label_band combinations, which an agent may hit with 12 bands across 5 products.

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 baseline is 3; the description adds real value on top by requiring all three identifiers to be copied from the same bottle and one of its label_bands, which is a cross-parameter consistency constraint the schema cannot express. It does not explain what happens when a band is valid for the enum but not for the chosen product.

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?

"Read one printed public label row" is a specific verb plus resource, and the following sentences spell out exactly what a row yields (amount or ask_doctor, age/weight restrictions, directions, source URL). It is clearly distinguishable from the list_/find_ siblings, which it names as identifier sources.

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 states where identifiers must come from (list_calculator_bottles or find_label_references), gives the condition for skipping discovery ("if already known, call directly without repeating discovery"), and adds a scope exclusion ("Does not determine suitability for a child"). When-to-use, how-to-prepare, and when-not are all present.

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 discloses a lot that annotations do not: output is full website-identical Markdown including tables, formulation distinctions, sources and safety limits; 'updated' is a content date, not a clinical review date. However, it declares a pure read operation while the annotations set readOnlyHint=false, an inconsistency the agent must reconcile (the mismatch is conservative rather than dangerous, but it is still a contradiction).

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?

Purpose and identifier source are front-loaded in the first sentence, with caveats after. The closing line about telemetry and 'no patient inputs' is meta-information about operations rather than about invoking the tool, so it dilutes an otherwise tight definition.

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, the description needn't describe return values, yet it usefully characterizes them as complete Markdown and qualifies the 'updated' field. What's missing is error behavior for an invalid or unknown guide_id, which matters for an exact-match lookup.

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 0%, so the description must carry the parameter, and it does partially: 'exact public guide_id' plus the requirement to source it from list_question_guides tells the agent the value is a canonical key, not free text. It adds nothing about how to choose among the 33 enum values or what happens on a mismatched ID, so it only partly compensates.

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 ('Read the full published educational guide') and pins the lookup key ('by exact public guide_id from list_question_guides'), which cleanly separates it from the listing tool and from get_label_directions. An agent can tell what this returns versus its siblings 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?

Explicitly routes the agent to list_question_guides to obtain the ID and adds a real exclusion: chewable and Claritin guides are reference-only and 'cannot be used with get_label_directions'. It stops short of stating the positive trigger ('use this when the user asks about a covered topic') but the retrieval path and one boundary are 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 are present but unusual (readOnlyHint=false on a listing tool), and the description supplies the missing context: 'No patient inputs' and 'Minimal operational telemetry records no tool arguments or results,' which explains why the call is not a pure no-side-effect read. That is genuine behavioral disclosure beyond the structured fields. It stops short of stating whether results are cached or whether the five-item set can change, which is why it is not a 5.

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

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

Three tight sentences plus one telemetry note, front-loaded with the scope and ending with the invocation contract. Every sentence carries either scope, routing, or behavioral information — none is 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?

A zero-argument, closed-world listing tool with an output schema, so return shape need not be explained. The description covers scope (five items, US), the alternative tool, the follow-up tool, and the privacy/telemetry posture — everything needed to call 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?

Zero parameters, so the baseline is 4; nothing is required to invoke it. The description does mention product_id, concentration and label_band, but only as arguments for the sibling get_label_directions, not as its own inputs, which is still useful chaining information.

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 (List) and a precisely bounded resource: the five supported US liquid medicine bottles, with exact concentrations and label-band identifiers. The scope is narrow and explicit, and the sibling find_label_references is named as the different entry point, so an agent can tell these apart 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?

Explicitly routes two alternatives: use find_label_references for a named brand or ingredient, and pass product_id/concentration/label_band to get_label_directions to read a listed row. This gives both the exclusion condition and the natural follow-up step, leaving nothing to inference.

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 are present but oddly set (readOnlyHint=false and idempotentHint=false for a parameterless list operation), and the description never reconciles that. It does add useful context beyond the annotations: what fields come back, that no inputs are accepted, and that telemetry excludes arguments/results. No contradiction is stated outright, but the gap between 'list' semantics and the annotations is left unexplained.

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 action and scope, then returns, then the sibling redirect. Slightly padded by the topical example list ('symptoms, timing, food, bottle comparisons, label charts, Zyrtec chewables and Claritin'), which conveys coverage but reads as promotional rather than functional.

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 parameterless list tool with an output schema, the description covers purpose, return fields, the sibling alternative, and the absence of inputs. An agent has everything needed to select and call 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?

Zero parameters, so the baseline is 4. The description reinforces this by explicitly saying 'No search text or patient inputs', preempting an agent from trying to pass a query argument despite additionalProperties=false.

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+resource ('Discover every published educational question guide') with the returned fields named (guide_id, descriptions, update dates, HTML/Markdown links). It distinguishes itself from the sibling get_question_guide by scope: this lists, the sibling returns complete content.

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

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

Explicitly routes the agent to get_question_guide for full content and states 'No search text or patient inputs', telling the caller this cannot be used for filtering/search. It stops short of describing the situational trigger (e.g., browse to pick an ID before fetching), so it is clear context rather than full when/when-not guidance.

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