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

Annotations cover the safety profile (destructive, idempotent, non-read-only), so the bar is lower, yet the description still adds real behavior: it will refuse panels with unconvertible units and hides them from trends. It does not spell out post-approval effects on downstream data, keeping it short of 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 dense sentences, front-loaded with the action and state change, then the critical gating rule, then the parameter caveat. No filler, though the parenthetical aside slightly interrupts flow.

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?

Output schema exists so return values need no explanation, and the description covers the confirmation requirement, the refusal condition, and the one non-obvious parameter. Complete enough to call safely; only minor downstream-effect detail is absent.

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 0%, so the description carries the burden. It explains allow_missing_canonical's consequence ('only if the user accepts that' the values are invisible to trends), which is meaningful beyond the bare boolean. source_id is left implicit but is self-evident from the tool's subject.

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 plus the state transition (pending→approved), which an agent cannot get from the name alone. It also implicitly differentiates from the staging sibling by naming stage_lab_panel in the guidance.

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?

Gives an explicit precondition ('ONLY on an explicit instruction from the user in the current message') and an explicit exclusion ('do not call right after stage_lab_panel'). This is exactly the when/when-not guidance the dimension rewards.

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 and openWorldHint. The description goes well beyond by disclosing the actual return behavior: a standard refusal to assess interactions (a doctor/pharmacist must check) plus deterministic checks for total daily paracetamol across products and biotin interference with lab tests. The fallback behavior when paracetamol_products is omitted is also disclosed, which is exactly the kind of context annotations cannot carry.

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 trigger condition is front-loaded in the first clause, followed by return behavior and parameter notes. It is dense but every sentence carries information; the parameter-level detail in the same paragraph slightly muddies the structure 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 3-parameter, no-required-arg tool with an output schema, the description covers the trigger, the return semantics, the refusal caveat, and defaults for omitted parameters. It is nearly complete; minor omissions are the purpose of taking_biotin being stated only implicitly and behavior when no medication data exists.

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 compensate, and it largely does: it gives the paracetamol_products shape ({name, mg_per_dose, doses_per_day}), warns to include combination cold/flu remedies (a non-obvious edge case), and gives planned_tests format plus an example (['tsh','ferritin']). taking_biotin is only indirectly implied by the biotin-interference mention, leaving a small gap.

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+resource and an explicit trigger scope ('Call for ANY question about medications: can I take X, combining drugs, doses'), then states what it returns: a standard refusal to assess interactions plus deterministic checks. This clearly differentiates it from siblings like get_medications and record_medication, which merely read or write medication data rather than answer safety questions.

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 strong usage context ('ANY question about medications') and explains a conditional behavior — if paracetamol_products is omitted, current medications are used instead. It also implicitly tells the agent this is not a substitute for medical advice via the refusal note. It lacks an explicit 'do not use for X, use sibling Y' exclusion, so it falls just short of 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior the annotations cannot convey: the response is fixed and pre-authored, and the agent must reply with it verbatim with 'no analytics' — an important constraint on how the result is handled.

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 short sentences, urgency front-loaded in the first clause, with each sentence carrying distinct information: when to call, what comes back, and how to handle it. No 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?

An output schema exists, yet the description still usefully characterizes the return value, and it covers the trigger and the required handling behavior. The only real gap is the unexplained 'message' input, which is a minor omission for an optional parameter.

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% and the single optional 'message' parameter has no title-level explanation. The description never mentions the parameter or what the agent should pass in it (e.g., the user's triggering message), so it does not compensate for the coverage gap.

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 the tool produces — a fixed response containing hotlines and the user's trusted contact — which is unambiguous and clearly distinct from every sibling health-data tool. An agent can tell at a glance that this is not a data-retrieval or analytics 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 gives an explicit, unmissable trigger: 'Call IMMEDIATELY on any sign of crisis, suicidal thoughts or self-harm.' The when-not condition is only implied (i.e., do not call otherwise), and no alternative tool is named — though none exists among the siblings — so this falls just short of the full 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?

Annotations already declare readOnlyHint and openWorldHint=false, so safety of the operation is covered. The description adds genuinely non-obvious behavioral context — the fail-safe rule that unverified allergies must be treated as real and never dismissed as 'unverified' — which materially changes how an agent should act on results. It does not cover pagination or ordering, hence 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?

Front-loaded with what it returns, then the safety-critical constraint, then usage and the sibling route. Three sentences, each carrying distinct and necessary information with no 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?

Return values are enumerated in the output schema, so the description doesn't need to restate them in depth. With annotations covering the read-only nature and the description covering usage, routing, and the fail-safe semantic, an agent has everything needed to call and interpret this 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?

There are zero parameters, so the baseline is 4. The description's field list refers to returned data (documented by the output schema), not inputs, so no parameter meaning is needed or provided.

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 (all recorded allergies) and enumerates the fields returned (allergen, reaction, severity, verified). It also names the sibling record_allergy as the write counterpart, so an agent can distinguish read from write without opening either 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?

Gives an explicit trigger ('Use before any discussion of foods or medications') and an explicit alternative with its own use case ('to add one use record_allergy'). Both when-to-use and the routing to the sibling are stated outright.

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 read-only safety, but the description adds important interpretive behavior: the two status axes and the instruction to base advice only on confirmed diagnoses, present suspected/provisional as open questions, and ignore refuted ones. It does not discuss operational details such as pagination, auth, or data freshness, but output schema likely covers return fields.

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 tight sentences: purpose and data model first, interpretation guidance second, sibling differentiation last. Every sentence adds distinct value, and the status lists are useful without being bloated.

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 zero-parameter read-only tool with an output schema and annotations, the description covers the domain semantics, status handling rules, and alternative sibling. An agent has everything needed to select and correctly use the tool without further 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?

There are zero input parameters, so parameter semantics are not applicable. The schema is fully empty and no description compensation is needed, matching the baseline of 4 for a 0-parameter 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 exactly what is returned: all recorded diagnoses with clinical_status, verification_status, date, and ICD-10 code. It also explicitly distinguishes this tool from get_health_summary, which only briefly includes active diagnoses.

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 gives a direct when-to-use rule: 'Use this for "what am I diagnosed with"' and names get_health_summary as the alternative for a brief active-only view. It also provides clear handling guidance for confirmed, suspected/provisional, and refuted diagnoses.

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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the output is 'deterministic' (stable for a given state) and deliberately includes unverified allergies, which tells the agent how to interpret data quality. It doesn't mention freshness/pagination, but for a parameterless read that is minor.

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 waste. The content enumeration is front-loaded and the routing hint to query_observations comes last as the qualifier it is.

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 is not obliged to explain return values, and it does list the sections an agent should expect. The only gap is the absence of any statement about how this aggregate relates to the single-domain siblings (get_allergies, get_diagnoses, get_medications), which an agent choosing between them would benefit from.

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 the schema imposes no documentation burden and the baseline is 4. The description correctly spends no words on parameter syntax and instead describes the content of the result.

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 a specific verb+resource and enumerates exactly what the summary contains: profile, allergies (including unverified), active diagnoses, current medications, and exam recency. It also distinguishes itself from query_observations by labeling itself 'a guide' rather than a source of exact values, so an agent can separate it from siblings 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?

It gives clear context (overview/guide use) and names the alternative for exact values: 'exact values via query_observations.' That is an explicit alternative with a selection condition, though it never states when NOT to use this tool or how it relates to the narrower get_allergies/get_diagnoses/get_medications 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?

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is partly covered. The description adds real behavioral context beyond them: only "taking"-status records are returned, and a downstream safety-check workflow plus a no-dose-change constraint are disclosed, though no permission or rate-limit detail is given.

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 value-dense sentences, front-loaded with the resource and scope, then routing, then the edge case. The field list mildly duplicates what the output schema already carries, but it costs little.

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 zero-parameter read tool with annotations covering safety and an output schema covering returns, the description supplies everything else: scope, sibling routing, and the safety-handoff workflow. Nothing needed to call it correctly 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?

Zero parameters, which sets the baseline at 4. The field enumeration in the description describes result content rather than inputs, and with a 100%-coverage empty schema there is nothing further an agent needs about arguments.

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 (get medications) plus the exact scope filter (status "taking") and the fields returned, so an agent can distinguish this from get_allergies, get_diagnoses, or query_observations at a glance.

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 says when to use it (before any medication question), what to chain into (check_medication_safety), a hard exclusion (never suggest dose changes), and routes the write case to record_medication. This is the strongest pattern of when/when-not/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?

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context on top: the age-gate behavior ('you don't need this yet'), the enumerated status values, and a hard precondition that the profile must be filled in.

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 statement front-loaded and the prerequisite trailing. The parenthetical age-gate phrase is slightly idiomatic but conveys real information, so little 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?

With zero parameters and an output schema present, the description need only frame the tool and its precondition, which it does. It is complete enough to invoke correctly, though it omits any guidance on what to do when the profile is unfilled.

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 nothing for the description to disambiguate; baseline 4 applies. The mention of statuses describes output semantics rather than inputs, which is harmless but not a parameter clarification.

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 ('screening calendar') scoped to the user's profile, with the caveat that it is age-gated. It is clearly distinguishable from data-retrieval siblings like get_health_summary or query_observations, but it never explicitly contrasts itself with any of them.

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 use case (viewing a screening calendar) is implied, and one prerequisite is stated: 'Requires a filled-in profile.' However no alternatives or when-not conditions are given, e.g. nothing says what to call instead if the profile is empty (set_profile is a sibling).

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 (readOnlyHint=true, openWorldHint=false), and the description adds real behavior beyond them: newest-first ordering, a hard cap of 200 rows, and the explicit boundary that it lists events, not values. It doesn't discuss truncation behavior when more than 200 events exist or whether the window is inclusive, which keeps it short of 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?

Four tightly packed sentences, front-loaded with what the tool returns, then when to use it, then the sibling boundaries, then the parameter. No filler and no repetition of the schema.

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 expounded, yet the description still sketches the row shape. Scope, ordering, cap, alternatives, and the sole parameter are all covered — nothing an agent needs to call this correctly 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 coverage is 0% for the single 'days' parameter, so the description carries the full burden — and does: it states the meaning (how far back to look) and decodes the opaque default of 3650 as roughly 10 years. Nothing about the parameter is left ambiguous.

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: it names the chronology of health events (diagnoses, labs, visits, medications, hospitalizations, vaccinations) and states ordering and row shape. It explicitly distinguishes itself from query_observations and get_trend, so an agent can route without opening any 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?

Gives concrete when-to-use context ('what happened when' questions, orienting before a visit) and explicit alternatives for adjacent needs (numbers → query_observations, direction of a marker → get_trend). This is the when/when-not/alternatives pattern in 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=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond them: the minimum-5-values threshold, the no_trend-with-reason fallback, and the restriction to approved values. It stops short of describing pagination or performance, but for a read-only statistical tool this is solid.

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 output shape, then routing guidance, then parameter notes. Dense but nearly every clause adds information; the parenthetical method name and unit glosses are justifiable, though the description is on the longer side.

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?

Output schema exists, so return fields need not be re-specified, yet the description still summarizes the result shape (direction, z, p-value, slope). Combined with usage routing, the 5-value precondition, and parameter meanings, nothing an agent needs to invoke this correctly 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 coverage is 0%, so the description must carry the burden, and it does: type_code is explained as a catalog code with concrete examples (ldl, hemoglobin, vitamin_d) plus where to obtain it, and days is described as the window with its default meaning (~5 years). Both parameters gain meaning not present 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+method ('Statistical trend of one marker over time (Mann-Kendall test + slope)') and scopes it to 'approved values'. It also explicitly distinguishes itself from the sibling query_observations, so an agent can tell them apart without opening schemas.

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?

Gives explicit when-to-use ('Use for "is X going up/down"') and names the alternative for the contrasting case ('for the raw values use query_observations'). It also states the prerequisite (at least 5 values in the window) that determines whether the tool is even applicable.

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 and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: 'Deterministic' signals stable, reproducible output, and it discloses what the health section measures (review-queue size, share of corrected extractions, approved values missing a canonical value). It does not discuss latency or pagination, but for a fixed 7-day aggregate that is a minor gap.

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, then the content inventory, then the routing sentence. The parenthetical system-health list is dense but each item is substantive; slightly heavy for a single description but no sentence 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?

An output schema exists, so the description need not explain return structure, yet it still summarizes the report contents and the intelligence gathered (deterministic scope, alternatives). Everything an agent needs to select and call this zero-arg tool is present.

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 the schema imposes no documentation burden and the baseline is 4. The description correctly implies no arguments are needed by framing the report as a fixed last-7-days window.

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 ('Deterministic report for the last 7 days') and enumerates the four content blocks it returns (new values, abnormal approved values, nutrient deficiencies/excesses, system health). This is clearly distinguishable from generic siblings like get_health_summary or nutrition_report.

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 names the use case ('weekly check-in') and routes to two alternatives with their selecting conditions: get_trend for a single marker and prepare_doctor_visit for a visit. Nothing about tool selection 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.

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds only that the returned records are saved templates for frequent meals; it says nothing about ordering, limits, or whether all templates are returned, though the output schema carries return structure.

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 resource front-loaded and no filler. It is telegraphic, but every word earns its place and nothing is buried.

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 zero-param read tool with an output schema and annotations, the definition is minimally adequate - it tells the agent what the records are and hints at the downstream workflow. It stops short of confirming scope (all templates vs. filtered) or the role it plays alongside save_meal_template.

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 nothing for the description to disambiguate. Baseline 4 applies for a parameterless listing 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 identifies the resource precisely ('Saved templates for frequent meals'), which lets an agent distinguish it from log_from_template, save_meal_template, and log_meal. It is a noun phrase rather than an explicit verb, but the tool name supplies 'list' and the scope is unambiguous.

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 parenthetical '(for quick log_from_template)' implies the intended workflow - fetch templates before logging from one - but states no explicit when-to-use condition or alternative to choose instead. Usage is inferable rather than 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, so the safety profile is covered, but the description adds real value beyond that: it discloses the pending/unverified marking on each record and a hard behavioral constraint against citing the data as facts or in trends. It stops short of describing ordering or pagination, so it isn't 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?

Front-loaded with the definition of what is listed, then the constraint, then the workflow and alternative. Dense but every sentence earns its place; the em-dash clause is slightly heavy but not wasteful.

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 explanation is not required, yet the description still summarizes the fields and adds the critical 'do not treat as verified' caveat plus the approve workflow. Nothing needed to call this correctly 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 tool takes zero parameters, so the schema carries no semantics to add. The description correctly focuses on the returned content instead, which is the right use of space for a no-arg listing 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?

States a specific resource and scope: lab values that were staged via stage_lab_panel but not yet approved, and enumerates the returned fields (marker, value, unit, date, status). It clearly separates this from query_observations, which reads approved 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?

Gives explicit when-to-use (show so the user can compare with the original report and approve via approve_staged_source) and when-not-to-use (never cite as facts or trends). It also names the upstream tool (stage_lab_panel) and the approved-value alternative (query_observations).

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 the safety profile (readOnly=false, destructive=false, idempotent=false), so the description's real contribution is the multiplicative nutrient semantics of portion_factor, which is genuine behavioral context not present in the schema. It stops short of noting duplicate-logging behavior despite idempotentHint=false, keeping it out of the top band.

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, then inline param semantics in a single dense passage with no wasted sentences. Slightly compressed, but every clause carries information an agent needs before invoking.

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 explained, and the annotations cover the mutation/idempotency profile. For a 5-param write tool with zero schema descriptions, the description supplies 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?

Schema description coverage is 0%, so the description must carry all param meaning – and it does: name resolves via list_meal_templates, eaten_at gives format 'YYYY-MM-DD HH:MM' and default now, wellbeing/symptoms are flagged optional, and portion_factor is explained with worked values (1.0 = one portion, 1.5 = one and a half).

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 ('Log a meal from a saved template in one call') and immediately distinguishes itself from the sibling log_meal for untemplated meals. An agent can tell exactly what this does and which sibling it is not.

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 names the alternative and its selecting condition ('For a meal without a template use log_meal') and routes the agent to list_meal_templates for resolving the name. Both the when-to-use and when-not-to-use cases are covered.

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 it is a non-read-only, non-idempotent mutation; the description adds genuinely new context by disclosing that entries are auto-approved, which matters given the existence of approve_staged_source and list_pending_reviews siblings. It also explains that nutrient estimation is model-generated 'including from a photo'. It stops short of describing edit/delete or duplicate 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?

Dense but front-loaded: the core action and the required parameter lead, followed by per-parameter semantics in a compact semicolon-delimited form. The em-dash 'Review — query_food' fragments are slightly awkward but every line carries usable information.

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 11-parameter mutation tool with an output schema (so return values need no explanation), the description covers nearly all parameters and the approval behavior. Missing minor coverage of notes, portion, and nutrient_source, but nothing an agent needs to call it correctly is absent.

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 load and largely does: it documents meal_type values, the eaten_at ISO format and default, the {code: amount} shape of nutrients with a long code list, the added_sugar vs natural-sugar distinction, glycemic_index/load scope, and symptoms/wellbeing semantics. Only notes, portion, and nutrient_source (default model_estimate) go unexplained.

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 ('Log a meal into the diary') and adds the consequential detail that the entry is auto-approved. It does not explicitly name which sibling it supersedes (save_meal_template, log_from_template, list_pending_reviews), though it does point to query_food and query_nutrition at the end.

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 by the closing pointers ('Review — query_food; daily norms — query_nutrition'), which route the agent for follow-up reads but never state when to choose this tool over log_from_template or save_meal_template. No prerequisites or exclusions 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 readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real value by disclosing the analysis window semantics and, crucially, the interpretation caveat 'Association, not causation,' which prevents the agent from over-claiming causal links. It does not mention computation cost or data-sufficiency requirements.

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?

Compact and front-loaded: the analytic subject comes first, outputs second, and the caveat last. The phrasing is dense with domain shorthand (%RDA+flags, GI), but no sentence 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 read-only, single-parameter analytics tool with an output schema present, the description covers purpose, window semantics, output composition, and interpretation limits. The only gap is routing guidance against the many sibling query/report 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 0%, so the single 'days' parameter has no documentation in the schema beyond its title. The description compensates by framing it as the analytics window ('over N days'), clarifying that it drives the lookback period rather than acting as a filter — the schema default of 30 is the only remaining detail.

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+resource ('Nutrition analytics over N days') and enumerates the concrete outputs (deficiencies/excesses with %RDA flags, GI/sugar/sodium grouped by wellbeing category). It implicitly separates itself from raw-data siblings like query_nutrition, though it never names them.

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 explicit statement of when to use this report versus query_nutrition, get_trend, or get_weekly_report. The analytic nature is implied by the output description, but the agent must infer the selection condition entirely.

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 (readOnlyHint=true, openWorldHint=false), so the bar is lower, yet the description still adds real behavioral context: only 'approved' values are surfaced (pending ones excluded), an explicit cap of 15 abnormal values, a deterministic summary, and inclusion of a disclaimer. The specialty echo-not-filter behavior is also disclosed. It does not discuss freshness or data-source limits, keeping it at 4.

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 clauses: what the briefing contains, when to use it, and the specialty caveat. The output contents are front-loaded and every sentence adds information with no 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?

An output schema exists, so return-value documentation is not strictly required, yet the description still summarizes the payload's composition. Combined with the usage trigger and the specialty caveat, an agent has everything needed to select and invoke this 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 0%, so the description must carry the parameter burden, and it does: it states specialty is optional, that it is merely a label echoed in the output, and explicitly warns the content is not filtered by it. That is exactly the semantics an agent needs to avoid a wrong mental model; only the format/valid values of the label remain unspecified.

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 a specific deliverable (a one-call doctor-visit briefing) and enumerates its exact contents: deterministic health summary, latest abnormal approved values with severity levels capped at 15, due/overdue screenings, pending-review count, and disclaimer. This is clearly distinguishable from siblings like get_health_summary, get_screening_recommendations, and list_pending_reviews because it declares itself as the aggregate of those.

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 gives explicit triggering contexts — 'Use before an appointment or when the user asks "what should I tell my doctor"' — which is strong when-to-use guidance. It does not name alternatives it might be confused with (e.g., get_health_summary) or state when not to use it, so it falls short of 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior: a 200-meal cap, newest-first ordering, and the shape of what comes back. It doesn't clarify whether the cap implies truncation/pagination behavior or how the days window interacts with it, which is the only real gap.

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 what the tool returns, then routing guidance, then parameter notes — every sentence earns its place and there is no filler. The field list is dense-but-necessary; slightly tighter phrasing would push this to a 5.

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 explain return values, yet it still names key fields and the 200-meal cap, which is sufficient for correct invocation. The only unaddressed item is truncation/pagination behavior at the cap, a minor omission for a two-param read 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 0%, so the description must carry the parameter burden and largely does: days is described as a look-back window with default 7, and meal_type as an optional filter with an explicit value set (breakfast/lunch/dinner/snack/drink) that appears nowhere in the schema. Minor gap: no stated bounds on days or whether meal_type accepts multiple values.

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 (food diary entries), the scope (last N days, newest first, max 200 meals), ordering, and the exact fields returned. It explicitly contrasts itself with query_nutrition and nutrition_report, so an agent can distinguish it from siblings 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?

Gives explicit when-to-use ('see WHAT was eaten') and names both alternatives with the conditions that select them ('daily totals vs norms' → query_nutrition; 'deficiencies and food↔wellbeing patterns' → nutrition_report). Nothing 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.

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered without the description. The description nonetheless adds real behavioral context the annotations cannot: the per-logged-day averaging caveat (incomplete logging understates intake), the recommendation to check days_logged, the <70% / upper-limit thresholds, and the rule that limit-only nutrients are never flagged deficient. That is substantive, though it stops short of return-format details.

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 output shape and flag semantics are front-loaded, caveats follow, and the sibling routing plus the days param are packed into trailing sentences with no 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?

An output schema exists, so return values need not be re-explained, and the description covers the interpretive quirks an agent would otherwise get wrong (averaging basis, days_logged, limit-only nutrients, flag thresholds). Nothing essential to calling it correctly 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 coverage is 0% for the single parameter, so the description must carry it — and it does, defining days as the look-back window with default 7, matching the schema default. Slight credit withheld only because the format/range expectations of the window are not spelled out.

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?

Opens with a specific verb+resource+scope: average daily intake of every logged nutrient over the last N days, including the derived %RDA and deficient/excess flags. It explicitly distinguishes itself from nutrition_report (ranked summary with food↔wellbeing associations) and query_food (the meals themselves), 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?

Gives an explicit use case ('am I getting enough X') plus two named alternatives with the conditions that select them, so when-to-use and when-not-to-use are both covered.

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 and openWorldHint, so the description carries real weight here and delivers: it discloses the >90-day weekly min/avg/max aggregation rule and that unconfirmed values are excluded. That is genuine behavioral context beyond the annotations, though response shape/pagination is left to the 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?

Three terse fragments, core purpose front-loaded, no filler. The telegraphic style is efficient though it reads more like shorthand notes than a polished description.

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 explained. For a two-parameter read-only query the description covers scope, aggregation behavior, and data filtering; only the type_code vocabulary and the days default remain implicit.

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 compensate for both parameters. It gives an example value for type_code and explains that days controls the window and triggers weekly aggregation past 90 days, but says nothing about the default of 365 or valid code formats, leaving part of the burden unaddressed.

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 (marker values) and the shape of the query (over N days) with a concrete example code ('cholesterol_total'), so the agent knows exactly what it retrieves. It does not distinguish itself from similar-looking siblings such as get_trend or get_health_summary, which is the only thing keeping it from 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?

No statement of when to prefer this tool over alternatives like get_trend or query_nutrition, and no prerequisites. The 'only confirmed (approved) values' clause hints at data scope but is a filter, not usage 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?

Annotations declare non-readonly, non-idempotent, non-destructive, but the description adds genuinely non-obvious behavior: entries are stored immediately as approved with manual provenance, and unverified allergies are still treated as real. It could go further on duplicate handling given dedup is recommended.

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-loads the action and side effect, then a compact parameter glossary, then a dedup warning. Dense but every line carries needed information given the empty schema.

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 annotations present and an output schema existing, the description covers creation semantics, provenance, parameter meanings, and dedup. Minor gaps remain around duplicate handling and whether edits/removals 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 coverage is 0% and the description fully compensates, defining each of the 5 parameters with examples (Penicillin) and candidate values for severity and allergen_type, plus the critical semantic that unverified allergies are still treated as real.

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 ('Add an allergy the user reports') and immediately distinguishes itself from the sibling get_allergies by telling the agent to check that first. The scope and write semantics are unambiguous.

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?

Gives explicit operative guidance: check get_allergies first to avoid duplicates, and use verified=true only when doctor/test-confirmed. Clear context, though it does not state when not to record an allergy (e.g. duplicate handling behavior).

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?

With annotations declaring non-readOnly/non-destructive/non-idempotent, the description adds real context beyond them: records are 'stored immediately as approved, with manual provenance,' which tells the agent there is no review gate. It stops short of describing failure modes (e.g., what happens if a duplicate is recorded) or permission requirements.

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-loads the operation and its key behavioral trait, then enumerates parameters compactly with no filler. The unbulleted parameter dump is slightly dense to scan but every line 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?

An output schema exists, so return values need no explanation, and the description covers all parameters plus the immediate-approval behavior. Minor gaps remain around duplicate handling and auth, but the core calling information is 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 description coverage is 0%, so the description carries the full burden, and it does so: date format (YYYY-MM-DD), which fields are optional, defaults for clinical_status and verification_status, and the full verification_status value set. This is materially more than the schema provides.

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 ('Add a diagnosis') and immediately characterizes the write as immediate and approved, which separates it from read siblings like get_diagnoses. An agent knows exactly what this does 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 tells the agent to 'Check get_diagnoses first to avoid duplicates' and gives value-level guidance for verification_status ('use suspected or provisional for anything not confirmed by a doctor'). It lacks guidance on when not to record, or how this relates to other write siblings like record_allergy or record_medication.

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 write/non-idempotent/non-destructive, so the bar is lower. The description still adds meaningful behavior beyond them: entries are 'stored immediately as approved', i.e. no staging or review step, and defaults are stated (product_type prescription). It does not describe duplicate handling or error behavior, keeping it short of 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?

Front-loaded purpose followed by parameter guidance and a boundary statement; every clause earns its place. The semicolon-chained delivery is dense and slightly run-on, which costs a point against a cleanly separated layout, but nothing is redundant.

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 explained, and the description covers all parameters plus the key behavioral fact (immediate storage) and a hard usage boundary. Only minor gaps remain — behavior on re-recording an existing medication or how this interacts with pending-review 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 0%, so the description carries the full burden — and it does so for all 8 params: medication_name (brand or generic), start_date format (YYYY-MM-DD), dose_amount+dose_unit pairing with an example, times_per_day, product_type enum values with the default, prescribed_for, and atc_code optionality. This is exactly the compensation the schema lacks.

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+resource ('Add a medication or supplement') and immediately narrows scope with 'the user currently takes', which cleanly separates it from read tools like get_medications and from the other record_* siblings. An agent can identify the operation 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?

Provides real usage conditions: 'record these whenever known' for dose fields, points to check_medication_safety as the consumer of dose data, and gives an explicit exclusion ('Never use this to change a prescribed dose — that is for the doctor'). It does not contrast with siblings like record_allergy/record_diagnosis, but the context is otherwise 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 idempotentHint=true and destructiveHint=false, and the description reinforces this with '(or overwrite)', so the agent understands repeated saves replace rather than duplicate. It also adds a genuinely useful data semantic — nutrients are for ONE portion — that no annotation conveys. Auth requirements and error behavior are not covered.

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-loads the purpose before walking through parameters, and every clause adds information an agent needs (overwrite behavior, per-portion units, example values). It is dense but could be trimmed marginally in the nutrients enumeration.

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 mutation tool with an output schema, so return values need not be described. The annotations cover the safety/idempotency profile, and the description fills the 0%-coverage parameter gap completely, including the nutrient code schema and portion basis.

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 carries the full burden and does so well: it defines 'name' as a short unique key with an example, enumerates meal_type values, explains nutrients as a {nutrient_code: amount} map per portion with sample codes, and marks glycemic_index as optional.

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 ('Save (or overwrite) a reusable template for a meal') and clarifies the create-or-update semantics. It distinguishes itself from siblings by naming log_from_template and list_meal_templates and explaining their relationship.

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?

Gives clear context for when to use it ('a meal eaten often, so it can later be logged in one call with log_from_template') and points to list_meal_templates for existing templates. It stops short of explicit when-not-to-use guidance, but the routing between the three template-related tools 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 and openWorldHint, and the description adds a genuinely non-obvious behavioral trait: results are marked untrusted and are not instructions, which is important for an agent handling injected text. It does not cover result shape or ranking behavior, but the untrusted-content warning is meaningful added 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?

Three sentences, front-loaded with purpose, then usage, then a safety note; each sentence adds distinct value with no redundancy.

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 no explanation, and annotations cover the safety profile, which the description reinforces with the untrusted-content note. The only real gap is the undocumented days/limit parameters, which slightly undercut completeness for a 3-param 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 0% for three parameters, so the description carries the burden but only 'query' is self-evident from 'full-text search'. The 'days' (recency window) and 'limit' (max results) parameters are left completely unexplained in both schema and description.

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-text search over document narratives) and enumerates the content types covered (doctors' conclusions, immunogram interpretations, ultrasound descriptions). It also implicitly distinguishes itself from numeric siblings like query_observations and sql_query by framing the answer as 'text, not numbers'.

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?

Gives concrete triggering questions ('what did the immunologist say', 'why polycythemia') and states the selection condition ('where the answer is in text, not numbers'), which usefully excludes numeric tools. It does not name specific sibling tools as alternatives, so it stops short of 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?

Annotations already declare the mutation/upsert safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description adds real value beyond them: 'Calling again overwrites the profile' clarifies the upsert semantics concretely, and the note that emergency_contact is visible via crisis_resources discloses a cross-tool data visibility characteristic.

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 critical fact (create/update profile) is front-loaded, followed by rationale then field formats. The list of dependent features is slightly wordy but each phrase earns its place by justifying the call. No padding 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?

For a 5-param mutation tool with an output schema (so no return-value explanation needed), the description covers required vs optional fields, formats, overwrite behavior, and downstream dependents. It stops short of noting permission/auth needs or what happens to unspecified fields on partial updates.

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 carries the full burden. It supplies formats for date_of_birth (YYYY-MM-DD) and sex (male/female), an example for blood_type (A+), a unit-implying name for height_cm, and a definition of emergency_contact as name and phone — plus which fields are optional. It does not clarify accepted date/sex validation edge cases, hence not a 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 first sentence gives a specific verb pair and resource: create or update the user's profile. It also states the downstream rationale (age/sex-dependent features). No sibling in the list competes for this job, so sibling differentiation is a non-issue, but the description never explicitly frames it as the sole profile-setting 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 states why the tool matters (reference ranges, screening calendar, risk calculators depend on it) and notes that crisis_resources surfaces emergency_contact, which implies when to populate it. There is no explicit when-not guidance or prerequisites, but the context is clear enough for an agent to place the call.

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 cover read-only status, but the description adds substantial behavioral detail beyond them: view-only database role, read-only transaction, 5-second timeout, 200-row cap with a `truncated` flag, and explicit statement that base tables, pending values, and writes are inaccessible. This is exactly the context an agent needs before issuing arbitrary SQL.

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 usage guidance are front-loaded in the first two sentences, followed by the view catalog and examples. It is long, but nearly every line (column lists, the pending-view caveat, the allergy caveat) earns its place for a free-form SQL tool; only slight density keeps it from a 5.

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 high-complexity, open-ended SQL tool, the description covers access scope, limits, timeout, row truncation, view/column inventory, and usage routing. An output schema exists, so return-shape explanation is unnecessary, and the `truncated` mention is appropriate extra signal.

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 0% for the single `sql` parameter, so the description must compensate — and it does thoroughly. It enumerates every accessible view with its columns, flags semantic traps ('verified=false is ALSO an allergy', pending view 'NOT fact'), and gives two worked SQL examples, far exceeding what the bare schema provides.

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 ('Run a custom read-only SQL query (one SELECT or WITH … SELECT) over the approved views') and adds a scope qualifier ('when no other tool answers the question'). An agent can immediately tell this apart from the dedicated query tools listed as siblings.

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 states when to use it ('when no other tool answers the question — e.g. comparing several markers, custom date filters or aggregates') and when not to ('Prefer the dedicated tools (query_observations, get_trend, query_food…) when they fit'), naming the alternatives. Nothing 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.

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true. The description adds genuinely useful behavioral context beyond that: the PENDING state, immediate alerting of critical values, and the requirement of explicit human approval before downstream approval. It stops short of specifying idempotency or re-staging behavior, which matters given idempotentHint=false.

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, front-loaded with the action and state, followed by the row shape and the required follow-up. No filler, though the trailing dash construction is slightly 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?

An output schema exists, so return values need not be explained. The description covers purpose, the staged/PENDING lifecycle, critical-value behavior, and the mandatory approval follow-up, leaving only minor gaps around the non-rows 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 description coverage is 0%, so the description must carry the parameter burden. It documents the rows item shape ({raw_name, value, unit, ref_min, ref_max}) well, but leaves facility, panel_type, and even the required panel_date format/expectations unaddressed, so it only partially 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 (Stage) and resource (extracted lab panel) plus the resulting state (PENDING), and it clearly positions itself before approve_staged_source. It does not name a sibling to avoid, but the two-step relationship is explicit enough to distinguish it from the read/report siblings.

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?

Gives clear usage context: stage now, then show the table to the user and wait for an explicit approve_staged_source. This tells the agent when the tool fits in the workflow and what must follow, though it doesn't state exclusions for panels already staged or alternative staging paths.

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