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 destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description still adds real value by noting the deletion also alters nutrient totals, which is a side effect not visible in the annotations. It stops short of saying whether the user should be asked to confirm or whether deletion is recoverable, leaving one small behavioral 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?

Two sentences, no filler, with the destructive scope stated first and the routing caveat second. Every clause 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?

With an output schema present, rich annotations, and a single required parameter, the description covers everything an agent needs: what is removed, what it affects, when to call it, and where the ID comes 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?

Schema coverage is 0%, so the description must carry the parameter, and it does by giving the value's provenance ("food_log_id from query_food"). It does not describe the expected format (e.g., UUID vs. integer string), which is the one remaining ambiguity for a single-param 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 verb and resource ("Remove a meal from the food diary and the nutrient totals") and immediately distinguishes itself from update_meal and, by implication, log_meal. An agent can tell exactly what this tool does without reading 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?

Gives an explicit precondition ("only when the user says it was logged by mistake or twice") and names the correct alternative for the adjacent case ("To fix a time, portion or nutrients use update_meal instead"). It is a model of when-to-use / when-not-to-use 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 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?

The readOnlyHint already tells the agent this is a safe read operation, but the description adds meaningful behavioral context: it includes former habits as well as current ones and explains why past exposure matters for risk. It also specifies the expected tone for presenting habits, though it does not describe empty states, ordering, or other retrieval mechanics.

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 reasonably compact and front-loads the resource and returned fields. It includes some extra clinical-presentation guidance ('state them as facts, without moralising') that is useful for a health assistant but slightly beyond bare tool-selection content.

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 the zero-parameter schema, read-only annotation, and available output schema, the description covers the important gaps: scope of habits, inclusion of former habits, relevant fields, clinical relevance, and sibling routing for add/update. Nothing essential for correct invocation 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 has zero input parameters, so the schema needs no parameter explanation and the baseline score is 4. The description adds output-field detail, but because there are no input parameters and an output schema exists, it does not need to do more for parameter semantics.

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 clearly identifies the resource as user-reported habits (smoking, alcohol, cannabis, vaping, and similar) and enumerates the returned fields such as habit_type, status, frequency, and optional quantities. It also distinguishes this retrieval tool from the mutating siblings record_habit and update_habit at the end, so an agent can tell exactly what this tool is for.

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 description explicitly routes add and change operations to record_habit and update_habit, which is strong alternative guidance. It also gives clinical context for using the returned data, but it does not spell out a when-not-to-use condition or a full decision rule for when get_habits itself should be selected.

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 declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real value beyond that by disclosing the status="taking" filtering (stopped meds are excluded) and a behavioral guardrail against dose-change advice. It does not discuss ordering, counts, or empty-result 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?

Scope and field list are front-loaded, then the safety rule, then the sibling routing. Dense but nearly every clause carries information; the trailing sibling list is compressed into a single readable sentence set, though it borders on enumeration for its own sake.

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 plus an output schema, the description supplies everything an agent needs: what is returned, when to call it, the required follow-up call, the safety constraint, and where the write operations live.

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 baseline is 4; the description instead documents what the result objects contain (name, dose, unit, times per day, route, product type), which is useful framing even though an output schema exists.

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 (medications and supplements) with an explicit scope filter (only entries with status "taking") and enumerates the fields returned. This makes it clearly distinguishable from siblings like record_medication, update_medication, and check_medication_safety.

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 when to call it (before any medication question), the mandatory follow-up (check_medication_safety), a hard constraint (never suggest dose changes), and routes the add/fix/stop cases to the three sibling tools by name. No inference required.

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 only declare readOnlyHint and openWorldHint, so the description carries the substantive behavioral load: every row is labeled 'PENDING — unverified', these values are unsafe to treat as facts or trends, and the unmapped=true subset has no marker type. That is exactly the operational context annotations cannot express.

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

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

It is front-loaded with the core definition and every sentence carries actionable information (data warning, approval path, unmapped branch, alternative reader). It is slightly dense — the field enumeration and the unmapped=true aside overlap with the output schema — but nothing 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?

For a zero-parameter read tool with an output schema, this is complete: the agent knows what comes back, how to present it, why it must not be cited, and which sibling to use for approval or mapping. No gaps that would cause misuse.

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 baseline is 4 and there is nothing to disambiguate. The description instead characterizes output fields (including raw_name for unmapped rows), which is helpful context even though an output schema exists.

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 precise verb+resource+state: lab values staged via stage_lab_panel but not yet approved. It enumerates the returned fields (marker, value, unit, date, status) and explicitly contrasts itself with query_observations for approved values, so the agent can distinguish it from siblings 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?

It gives explicit when-to-use and when-not-to-use rules: show these rows so the user can verify against the original report, never cite them as facts or use them in trends, approve via approve_staged_source, and read approved values with query_observations. It also branches on the unmapped=true case with a concrete next step (ask the user, then map_pending_observation).

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 write, non-idempotent, non-destructive. The description adds real value beyond them: 'auto-approved' signals no review queue, and it discloses the time_check response signal and that daily totals are attributed by eaten_at date. It does not cover duplicate handling or what happens on a repeated log, 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?

Core instruction is front-loaded, but the nutrient code enumeration consumes most of the text and the inline em-dash lattice ('nutrients — {...}; added_sugar — ...') reads as run-on. The volume is justified by the 0% schema coverage, but it could be tighter.

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-param mutation with an output schema present, the description covers what the agent must know to call it correctly: required field, formats, defaults, the estimate-by-model expectation. Only the auxiliary fields (notes, portion, nutrient_source) lack any explanation.

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?

With 0% schema coverage across 11 params, the description carries the load and mostly succeeds: it enumerates meal_type values, gives the eaten_at ISO format and default, spells out the nutrients map keys against a long list of nutrient codes, and explains the non-obvious added_sugar distinction and per-meal scope of glycemic_index/load. notes, portion, and nutrient_source are left undefined.

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: 'Log a meal into the diary', plus a state qualifier '(auto-approved)' that tells the agent the entry is committed immediately rather than staged. It clearly implies a create operation, distinguishable from sibling update_meal/delete_meal, though those are never named.

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 usage context: pass eaten_at as when the meal was actually eaten when logging retrospectively, and confirm with the user if the response contains a time_check. It also routes adjacent needs to siblings ('Review — query_food; daily norms — query_nutrition'). No explicit when-not-to-use or guidance on choosing between log_meal and log_from_template.

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?

Goes well beyond the annotations: it discloses that the value is re-normalized into the canonical unit, that the critical-value check is re-run, that learn_synonym persists the printed name for future automatic mapping, and that a unit-dimension mismatch causes refusal. These side effects explain the non-idempotent, non-read-only profile declared in annotations.

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 verb and resource, and each clause adds real information (precondition, normalization, critical check, synonym learning, refusal, PENDING state). Dense but almost no waste; the parenthetical example could be tightened slightly.

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 mutating, open-world tool with an output schema, the description covers precondition, side effects, failure mode, and the post-state of the row. Nothing an agent needs to call it correctly is missing, and return values are covered by the output schema.

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 load. It explains type_code with its source table and an example ('observation_types.code, e.g. "lymphocytes_abs"') and explains what learn_synonym actually does. observation_id is left implicit, a minor gap in an otherwise strong compensation.

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: assigns a marker type code to a specific pending observation row that is unmapped or mis-mapped. The final clause ('The row stays PENDING; approve separately') explicitly separates this from the approval sibling, so an agent can distinguish it from approve_staged_source or list_pending_reviews.

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 a clear precondition ('only after the user confirmed which marker it is') and states the triggering condition (row unmapped or matched to the wrong marker). It also warns the row remains PENDING and approval is a separate step. It doesn't name the approval sibling by exact tool name, which keeps it just below 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 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 safety is covered. The description adds real behavioral detail beyond them: newest-first ordering, a hard cap of 200 meals, the field inventory returned per entry, and the fact that the id is the handle for update_meal/delete_meal. It does not say what happens when the 200-meal cap is hit (truncation vs error), 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?

Front-loaded with resource and scope, then routing to siblings, then parameter semantics at the end. The field list is dense but every item is informative and there is no filler sentence.

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, return values need no explanation, and both parameters plus the sibling routing are covered. The only residual gap is pagination/truncation behavior at the 200-meal cap, which an agent calling a bounded list may still need to know.

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

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

Schema coverage is 0%, so the description carries the full burden and does: days is documented as a look-back window with default 7, and meal_type is documented as an optional filter with the allowed values breakfast / lunch / dinner / snack / drink — enum values the schema lacks entirely. Both parameters are fully usable from the prose alone.

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 (food diary entries), a scope (last N days, newest first, max 200 meals), and enumerates the returned fields including the id used by update_meal/delete_meal. It also explicitly separates itself from query_nutrition and nutrition_report, so an agent can pick it 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?

Gives an explicit positive trigger ('Use it to see WHAT was eaten') and names two alternatives with the condition that selects each: query_nutrition for daily totals vs norms, nutrition_report for deficiencies and food↔wellbeing patterns. 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 only declare the safety envelope (not read-only, not destructive, not idempotent, closed-world); the description adds the key non-obvious behavior that entries are stored immediately as approved rather than staged for review — important given siblings like list_pending_reviews and approve_staged_source exist. It also discloses default behavior (status defaults to current) and warns against inventing dates. It stops short of stating anything about duplicate handling beyond a manual check.

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 verb and the storage semantics before the field list, and every clause is operational (formats, defaults, exclusions). It is a dense run-on string with semicolon-separated parameters, which costs a little readability but wastes no sentences.

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 9-parameter write tool with zero schema documentation, the description supplies formats, defaults, enumeration values, cross-tool workflow, and an anti-hallucination rule for dates. An output schema exists, so return values need not be explained; 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%, so the description carries the full burden and does: it enumerates every field, gives accepted values and casing for habit_type, the three status values with default, the free-text quoting style for frequency, the YYYY-MM-DD format plus the negative rule for dates, and which quantitative fields apply when known. This is meaning an agent could not recover from bare property titles.

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 ('Add a habit the user reports') and immediately scopes it with a behavioral consequence ('stored immediately as approved'). It names the allowed habit_type values and clearly separates this from siblings by referencing get_habits (dedupe check) and update_habit (pattern changes).

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?

States explicit workflow rules: check get_habits first to avoid duplicates, and route pattern changes through update_habit by marking the old entry former then recording the new one. It also gives a when-not rule for dates: only supply start/end when the user gave the day, otherwise put 'since July 2026' into notes.

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 a non-destructive, non-idempotent write in a closed world; the description adds genuinely new behavior: records are committed immediately as approved (no staging/approval step, unlike stage_lab_panel), duplicates are possible so a pre-check is needed, and dose fields feed the safety checker. That is real operational context beyond the structured hints.

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 storage behavior are front-loaded, and every clause carries usable information with no filler. It is dense prose rather than a structured list, though, so scanning nine parameter explanations in one block takes more effort than necessary.

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 mutating intake tool, all the essentials are present: when to use, when not to, duplicate avoidance, parameter formats, and the meaning of 'approved' on write. Return values need not be explained since an output schema exists, and annotations already cover the safety profile.

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% across 9 parameters, so the description carries the full burden and does: it documents format and semantics for medication_name (brand/generic + strength), start_date (YYYY-MM-DD), dose_amount/dose_unit pairing, times_per_day, product_type with its default and value set, route with examples, and marks prescribed_for and atc_code 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 — 'Add a medication or supplement the user currently takes' — and pins the resource scope with 'currently takes', which separates it from stop_medication and update_medication. The parenthetical clarifies the write path (stored immediately as approved), so an agent knows exactly what this tool does on its own.

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 preconditions ('Check get_medications first to avoid duplicates') and an explicit exclusion ('Never use this to change a prescribed dose — that is for the doctor'). It also discloses a downstream dependency (check_medication_safety uses dose fields), which tells the agent why to capture those parameters now.

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?

Adds substantial context beyond the readOnlyHint/openWorldHint annotations: view-only DB role, read-only transaction, 5 s timeout, 200-row cap with a `truncated` flag, and that base tables, pending values and writes are inaccessible. These are operational limits the annotations could never convey.

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 purpose, constraints and alternatives before the reference material, and the view catalogue is genuinely necessary for writing a correct query. Minor redundancy: the 'approved/not deleted' and 'no base tables/pending/writes' ideas are restated in the view section.

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 open-ended SQL tool is the hardest case for description completeness, and this covers dialect limits, role/permissions, timeout, row cap, and the full readable schema. Return-value detail is unnecessary since an output schema exists, and the `truncated` note still flags the one return behavior an agent must act on.

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 single `sql` param has no description, so the description must carry the full burden — and it does: it constrains the statement form, enumerates every queryable view with column names and inline caveats (e.g. v_allergies verified=false is still an allergy; v_observations_pending is not fact), and supplies two worked examples.

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') and narrows the surface to 'one SELECT or WITH … SELECT' over approved views. It explicitly separates itself from the dedicated tools by naming the escape-hatch purpose (custom aggregates, cross-marker comparisons).

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 when-to-use condition ('when no other tool answers the question'), concrete examples of that condition, and names the alternatives (query_observations, get_trend, query_food) with 'Prefer the dedicated tools … when they fit.' This is exactly the when/when-not/alternative triad.

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 the safety profile (not read-only, non-destructive, open-world, non-idempotent), and the description adds meaningful traits: items are stored PENDING, critical values trigger immediate alerts, and unrecognized markers land in an UNMAPPED queue rather than failing. It doesn't discuss duplicate staging or idempotency behavior, which is the remaining 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 action and the required date/rows contract, then the parsing rules, then the workflow. Dense and largely waste-free, though the row-parsing sentence is a run-on that could be split for scanning.

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, return values need no explanation, and the staging/approval lifecycle is fully described. The only omissions are the two optional metadata parameters (facility, panel_type), whose semantics an agent must guess.

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 load, and it does well for the hard parts: panel_date format, the row object shape (raw_name, value, unit, ref_min, ref_max), numeric parsing of comma decimals, and the qualitative/limit escape hatch via value_text. However, facility and panel_type are never explained.

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 ('Stage an extracted lab panel') plus the resulting state (PENDING), and immediately distinguishes itself from map_pending_observation and approve_staged_source by naming them in context.

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: unmapped/unit-mismatched names should be resolved with map_pending_observation, and the tool must be followed by showing the table and waiting for an explicit approve_staged_source. The sequencing is unambiguous.

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 idempotent and non-destructive but say nothing about downstream effects; the description supplies them — the medication drops out of get_medications and safety checks yet remains on the timeline as medication_stop. It also states the end_date constraint (not in the future), which is behavioral, not schema, information. No contradiction with annotations.

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 constraints, then guardrails and escalation — a sensible ordering. The heavy parenthetical example clusters ('course finished', 'doctor stopped it'…; 'rash') make individual sentences dense, but nothing 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?

For a 4-parameter mutation whose output schema already documents return values, the description covers source of IDs, defaults, validation, downstream effects, and a safety escalation path. An agent has everything needed to invoke it correctly and safely.

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: medication_id is sourced from get_medications, end_date format YYYY-MM-DD with a default of today and a future-date restriction, and stop_reason/side_effects are marked optional with concrete example values. All four parameters gain meaning beyond bare string titles.

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 precise verb+resource: 'Record that the user no longer takes a medication.' This is clearly differentiated from the sibling mutations record_medication and update_medication, which add or edit rather than terminate a medication.

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 ('Only when the user says it was stopped') and an explicit prohibition ('never suggest stopping a medication'), plus a routing rule to a sibling: 'If the side effect sounds like an allergic reaction, offer record_allergy too.' That is the full when/when-not/alternative triad.

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 this as a non-destructive, idempotent, closed-world write, so the bar is lower, yet the description still adds substantive behavior: empty fields are preserved (true partial-update semantics), notes are wholesale replaced rather than appended, and dates must be YYYY-MM-DD and non-future. The notes-replacement warning is exactly the kind of data-loss nuance annotations cannot express.

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 tightly packed sentences with the core verb/scope front-loaded, then invocations rules, then the notes caveat, then format constraints. The quoted user phrasings earn their space by mapping natural language directly onto parameters.

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 need not be explained since an output schema exists, and the main update workflow is fully described. The gap is the four undocumented habit-type-specific fields, which an agent could misuse given 0% schema coverage, though they are optional and niche.

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% across 10 parameters, so the description must carry the full burden; it covers habit_id's source, notes replacement semantics, status/end_date via example, date formatting, and frequency. Four parameters — habit_type, smoking_years, drinks_per_week, cigarettes_per_day — get no explanation at all, leaving an agent to guess their meaning and units.

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 ('correct'/'update') and resource ('a recorded habit'), making clear this operates on an existing record rather than creating one. The 'habit_id from get_habits' clause anchors it against get_habits, but the sibling it most needs to be distinguished from, record_habit, is never named explicitly.

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

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

Gives concrete when-to-use guidance through worked examples ('I quit in September' = status former + end_date; 'now twice a week' = frequency) and the key invocation rule 'pass only the fields to change (empty = keep)'. What is missing is any exclusion — it never says when to use record_habit instead or what to do if the habit doesn't exist.

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 non-destructive, idempotent mutation; the description adds real semantics beyond that: empty fields are preserved, eaten_at re-dates the entry and shifts daily totals, and nutrients is a partial overwrite rather than a replacement. It omits error behavior for an unknown food_log_id, keeping it from 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-loads the verb and identifier requirement, then layers the merge rule, date semantics, and the sibling pointer. Dense but every clause carries operative information; 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?

For an 11-parameter mutation tool, the description plus annotations and an output schema give an agent enough to call it correctly. Only individual semantics for the plain string fields and failure modes are unstated.

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 burden — it documents food_log_id, the eaten_at format 'YYYY-MM-DD HH:MM' with its effect on daily aggregation, and the nutrients {code: amount} merge behavior with a worked halving example. The remaining fields (notes, symptoms, portion, meal_type, wellbeing, description, glycemic_*) are only covered by the general 'empty = keep' rule.

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 ('Correct a logged meal'), with the required identifier source named (food_log_id from query_food). It also differentiates from the sibling delete_meal, so an agent can route correctly 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?

Explicitly states when to use it (correcting a logged meal), how partial updates work ('pass only what to change (empty = keep)'), and names the alternative for the other case ('To remove a meal logged by mistake or twice use delete_meal').

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?

Beyond the annotations (idempotent, non-destructive), the description discloses that partial updates are supported ('pass only the fields to change (empty = keep)') and that the prior version is retained in change history — material context for a mutation tool. It also adds a safety guardrail against suggesting dose changes. It stops short of stating permissions or confirmation needs, keeping it at 4 rather than 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 source-of-id, then the routing rule. Every sentence is load-bearing, though the final 'Never suggest dose changes yourself' reads as a policy instruction folded into a tool description, and the block is dense with no visual separation of the routing rule.

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 shape need not be described, and the annotations cover the mutation safety profile. The description supplies the partial-update contract, history retention, id provenance and sibling routing. The only real gap is the three undocumented optional fields (atc_code, product_type, prescribed_for), which an agent may leave unset for lack of guidance.

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% across 10 parameters, so the description carries the burden; it covers medication_name, dose_amount, dose_unit, times_per_day, route and start_date, and explains the empty-string/null default semantics as 'keep'. It leaves atc_code, product_type and prescribed_for entirely unexplained, so the compensation is only partial.

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 ('Correct a recorded medication') and immediately enumerates the kind of correction (name typo, dose, unit, times_per_day, route, start date). It explicitly distinguishes itself from stop_medication and record_medication, so an agent can route between the three 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 the trigger condition ('the user says is wrong or incomplete'), an explicit exclusion ('Not for a dose the doctor changed'), and the exact alternative workflow with tool names and the stop_reason argument value. Nothing about when to pick this tool 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.