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

Goes well past the annotations: it discloses that nothing is stored unless a save link is opened, that saved data is held ~30 minutes and deleted if unclaimed, and what the response contains (prioritized list, guideline source per item, doctor questions, printable checklist). This directly supports the readOnly/idempotent/non-destructive hints without contradicting them.

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 purpose, then inputs, then output, then privacy and re-run guidance in a sensible order. It is dense but long, and the closing account/scheduling upsell ('saving the checklist to a free Phi Longevity account...') sits outside the tool's actual behavior and could be trimmed.

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 four-parameter tool with a nested object and a large enum set, the description covers population, inputs, safety posture, data retention, output contents, and re-run cadence. With an output schema present it does not need to spell out return values, and it still summarizes them usefully.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including the test-status enum and its 'omit what you don't know' behavior. The description restates the inputs ('only the condition, a few medicine classes, and for each routine test whether it was done recently') and adds the rationale that the closed options make it safe for a real person, but adds no new per-parameter meaning.

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 ('check which routine tests and checks may be due') plus the exact population it applies to (type 2 diabetes, kidney disease, lupus, cancer history). The clause 'It needs NO lab values, dates, names or records' implicitly separates it from lab-results siblings like explain_my_lab_results and get_my_medical_records.

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 ('when the person you are helping has... and wants to know which routine tests may be due') and an explicit boundary ('decision support for visit preparation, not a diagnosis'), plus re-run guidance with the check_again date and a weekly cadence. It never names a sibling tool as the alternative, so the routing is implied 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?

Goes well beyond the annotations: discloses expected latency (10–20 seconds), the structure of the return (health picture, graded/sourced connections, what is due, safety notes, what is unknown, recommendations), and an explicit caveat that a second automated check — not a clinician — reviews output. It also states the data-retention behavior in detail: inputs are not stored except that a claim link may hold submitted values for up to 30 minutes, after which unclaimed values are deleted. That is exactly the kind of privacy/limitation 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?

Front-loaded with the core purpose in the first sentence, and every later clause (latency, reviewer caveat, alternative tool, PHI ban, retention) carries real decision weight. It is a single dense paragraph with heavy parenthetical nesting and a run-on final sentence about claim links, which costs it some readability but not substance.

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 medical-adjacent, open-world tool this is thorough: it covers scope restrictions, privacy and retention, latency expectations, the absence of clinician review, and the sibling to use for deeper analysis. With an output schema present, it correctly does not waste space describing return fields in detail.

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

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

Schema description coverage is 100%, so the schema already documents age, biologicalSex, biomarkers, conditionFocus and include_partner_options. The description mentions condition areas that map loosely onto the conditionFocus enum (diabetes, kidney, lupus, cancer survivorship), but adds no new syntax, defaults or semantics for any parameter beyond what the schema states — baseline 3 applies.

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

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

States a concrete verb and transformation ("turns a set of lab values ... into guideline-cited suggestions and questions for the care team") plus the specific guideline frameworks cited (ADA, KDIGO, EULAR/ACR, NCCN). It distinguishes itself from the nearest sibling by naming start_lab_analysis for the deeper reading, so an agent can pick between the two 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 a clear boundary for the closest alternative ("For the deepest reading on our strongest model, use start_lab_analysis") and a hard scope restriction (synthetic/de-identified, research/education only, no PHI). However, with 13 siblings including quick_check, get_lab_analysis, full_prism_report and sample_prism_report, it only routes away from one of them, leaving several plausible confusions unresolved.

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: discloses the two-step x402 payment handshake (call without `payment` → receive terms → retry with base64 payload), the exact price and chain, and a retention policy (nothing stored except an optional claim link holding values up to 30 minutes). The non-idempotent hint is effectively explained by the pay-per-call model. Minor tension: a charging tool with temporary value retention is arguably not purely read-only, but this is disclosed rather than contradicted.

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 paid nature and capability, then payment mechanics, then safety/retention constraints — a sensible order. It is dense and slightly repetitive (price appears in both title and body), but nearly every sentence carries operational information an agent needs.

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

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

With no output schema, the description compensates by naming the return artifact (rendered markdown report plus score breakdown). Together with the payment flow, data-handling caveats, and PHI prohibition, an agent has everything needed to call this correctly on the first try.

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

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

Schema coverage is 100%, so the schema already documents every field; the description still adds real meaning by explaining the `payment` parameter's protocol semantics that the schema only hints at ('omit on first call to receive payment terms'). It also reinforces the 'up to 4 condition tracks' bound on compareTracks.

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 ('runs up to four condition tracks ... returns a written report') and explicitly positions itself against a sibling ('Everything explain_my_lab_results does, plus: multi-track compare/contrast analysis...'). The added scope items (Phi Longevity Score with per-pillar breakdown, partner options, markdown report) make the differentiation concrete rather than generic.

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 (developers, synthetic/de-identified values, research/education) and when-not (real person's own records → philongevity.com; no PHI). It also names the superset relationship to explain_my_lab_results, so an agent can trade cost against feature scope.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so safety is covered. The description adds genuinely new behavior: the operation is stateless ('Nothing is stored') and the job_ref itself encodes the chosen closed options, which explains why retrieval works across conversations. It omits failure/expiry behavior for an invalid or unfinished job_ref.

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, front-loaded with the purpose and source, then portability, then the statelessness caveat. No sentence is redundant.

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

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

With an output schema and strong annotations, the description only needs to cover origin, timing and durability of the job_ref, which it does. The remaining gap is error/readiness behavior — what happens if the job is not yet complete — for a tool whose whole value is deferred retrieval.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the job_ref is the value returned by prepare_for_my_appointment and is self-contained, carrying only the closed options that were chosen. That tells the agent the ref is opaque and portable, beyond the schema's 'returned by ... (or start_job)' note.

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 — 'fetch the finished result of prepare_for_my_appointment' — and ties it to the exact sibling that produces the job_ref. An agent can distinguish it from preparation and from the other report/fetch tools 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 clear context: use it after prepare_for_my_appointment, 'any time later and in a new conversation.' It does not state a when-not case (e.g. what to do if the job is not finished yet, or how this differs from start_job named in the schema), so a small gap remains.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld, so the safety profile is covered; the description goes further by enumerating the four possible states and disclosing the 30-minute retention window for expired results. It stops short of describing what a failed response contains, which matters since no output schema exists.

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, zero filler, with the identity of the returned job result and the status semantics front-loaded. Every clause (polling cadence, payload fields, retention window) carries distinct operational value.

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

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

With no output schema, the description correctly carries the burden of naming the return shape for the done state (health_picture, recommendations) and the full status taxonomy. The gap is the failed-state payload and the unresolved overlap with the get_job_result sibling.

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

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

Schema coverage is 100% and the single job_id parameter is fully documented in the schema as the value returned by start_lab_analysis. The description's "Takes only the job_id" restates that without adding format, validation, or reuse semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ("Returns the result of a start_lab_analysis job") and explicitly anchors the tool to its producer sibling, start_lab_analysis. An agent can distinguish it from the start tool or explain_my_lab_results 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 concrete polling guidance: pending means call again in a few seconds, and expiry after 30 minutes sets a deadline for retrieval. It does not address when to use this versus the sibling get_job_result, which could be a competing way to fetch job output.

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 safe, read-only, idempotent, non-destructive operation. The description adds useful content scope by noting the five health areas, weights, methodology link, and cited clinical guidelines, but does not disclose further behavioral traits such as freshness or whether the explained methodology is static.

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 a single well-structured sentence that front-loads the main purpose and includes only relevant details. Every phrase, including the parenthetical about health areas and weights, adds useful specificity without waste.

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-only explainer with an output schema and safety annotations, the description is largely complete. It could be slightly improved by clarifying that this returns general methodology rather than personalized results, but the core scope is adequately covered.

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 parameters, so parameter semantics are not a concern. The empty schema is self-evident, and the description correctly does not introduce parameter details that would be irrelevant.

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 and resource: it explains how PRISM scores results, including five health areas, weights, a link to full methodology, and clinical guidelines. This is clear and distinct in substance from siblings like full_prism_report, though it does not explicitly name alternatives.

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 explains what the tool contains but gives no explicit guidance on when to call it versus alternatives such as full_prism_report, sample_prism_report, or quick_check. Usage is only weakly implied by the word 'Explains'.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds genuinely new behavioral facts: 'Public directory lookup only; stores nothing' (a privacy guarantee) and 'Not medical advice' (an output boundary), plus an itemization of what is returned. It stops short of describing failure modes (hospital not found, ambiguous names), which is the only 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?

The trigger conditions are front-loaded and useful, but the middle is a single long run-on sentence that swells into promotional detail about Phi Longevity PRISM ('a cited Care Team Brief that their own Claude or ChatGPT can then read'). That product-marketing clause is longer than the operational content it accompanies and could be cut without losing invocation guidance.

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

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

For a two-parameter read-only lookup with no output schema, the description covers the full picture: what to pass, what not to pass, what comes back (EHR system, download steps, guide page, connection link), privacy behavior, and the non-medical-advice boundary. An agent has everything needed to call it correctly and set expectations for the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it reinforces that only the organization name and optional US state go in, and explicitly forbids person names, dates or health details. That restates and strengthens the schema's privacy constraint in the calling instruction, going slightly beyond the field-level text.

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

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

The description states a specific resource and outcome: given a hospital/clinic name, it returns which records system the hospital uses (Epic MyChart or Oracle Health), download steps, a guide page, and a connection link. That is a concrete, distinguishable capability an agent can match against a user request without opening the schema, and it is clearly not the same as siblings like get_lab_analysis or prepare_for_my_appointment.

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 enumerates four explicit trigger conditions (records spread across doctors, wanting records/lab results out of a portal, wanting them usable by the assistant, not knowing which portal the hospital uses). It also states the negative input constraint ('NAME only... never the person's name or any health detail') and scopes itself as a public directory lookup, which tells the agent when this is the wrong tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds two things they cannot: that it takes no health data (a privacy reassurance that matters for a health context) and the shape of what comes back. It does not discuss rate limits or fallbacks, but for a static guide tool 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?

The first sentence is front-loaded and useful, but the parenthetical "Every doctor, your complete record: their records from every doctor in one place they control" is a garbled marketing fragment that interrupts the flow and adds no operational meaning. Two sentences carry the load; the third fragment does not earn 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?

For a zero-required-parameter tool with an output schema, full annotation coverage, and a documented enum, the description supplies the triggering condition and the privacy signal that matter most. The only gap is the unmentioned effect of the optional goal parameter, which the schema already handles.

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

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

Schema description coverage is 100% and the single optional enum parameter is documented in the schema itself, so the baseline of 3 applies. The description never mentions the goal parameter or the fact that it only alters the first sentence, leaving that entirely to the schema.

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

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

States a concrete output: five plain steps, the cost, and a sign-up link that the agent can relay to the person it is helping. That is specific enough to separate it from data tools like get_my_medical_records or explain_my_lab_results, though it never names a sibling directly.

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?

"Call this when your owner has real records or asks how to get started" gives a clear triggering condition, which is stronger than most definitions. It stops short of naming an alternative or an explicit when-not-to-use case against near-neighbors such as quick_check or start_my_phi_account.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world. The description adds real value beyond that: the returned content is fixed reference material with units and ranges, and explicitly contains no patient data, so the agent knows no PHI is exposed. Missing only notes on result size or ordering.

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

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

Two sentences, no filler. The scope statement (51 tests, examples, units, ranges) is front-loaded, and the privacy qualifier follows as a short, purposeful clarification.

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 tool with a rich set of annotations and an output schema, the description covers what it returns and confirms no patient data is involved. Only the relationship to sibling tools is absent, which is minor given how self-contained this tool is.

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 a 4, but the description adds nothing about arguments because there are none to describe. The single sentence about contents is a return-value hint rather than parameter guidance, keeping this at a solid baseline.

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

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

States a specific verb and resource: lists the 51 lab tests PRISM interprets, with concrete examples (A1c, eGFR, LDL, ApoB, thyroid) and what each entry contains (units, reference ranges). The static reference-list nature clearly separates it from patient-specific siblings like explain_my_lab_results or get_my_medical_records.

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?

"Reference data only, no patient data" implies the context of use (capability discovery rather than result interpretation) but never states when to call it or which sibling to use instead. An agent can infer it is the right first step before explain_my_lab_results, but that routing is left to inference.

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

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

Annotations already declare it read-only, idempotent and closed-world, and the description still adds real substance: cost ('Free'), retention ('Nothing is stored'), a stable job_ref retrievable later via get_job_result, and a guaranteed trailing next_steps block. The only soft spot is that 'Nothing is stored' sits in mild tension with a job_ref that reproduces the sheet later in a new conversation.

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 trigger condition and the payoff, then the input burden, then the job_ref lifecycle, then the disclaimer. It is long and the clinician list in prose duplicates the visit_with enum, but nearly every clause carries genuine signal.

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 five-parameter tool with a nested status object and an output schema, the description covers the trigger, the inputs required and explicitly not required, the shape of the return, the follow-up retrieval path, cost, retention, and the non-diagnostic framing. Nothing an agent needs in order to call it or to decide to call it 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 100%, so the baseline is 3; the description earns above that by telling the agent the call is deliberately low-burden, using only condition, a few medicine classes, which clinician, and per-test status as recent/overdue/never/unsure. It adds intent and framing rather than syntax, which is the right thing to add here.

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 ('be ready' for an 'upcoming appointment') plus the exact contents of the reply (checks, questions, what to bring, printable visit sheet). The parenthetical 'no lab values or records needed' carves it away from sibling record/lab tools such as get_my_medical_records and explain_my_lab_results.

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 triggering condition (a person with an upcoming appointment for one of the listed conditions who wants to be ready) and an explicit negative requirement (no labs, dates, names, or records). It also routes to get_job_result for later retrieval, but never names or contrasts siblings like check_care_gaps, so when this beats the care-gap 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.

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior. The description goes well beyond them by disclosing latency profile (local check, no engine round-trip), the non-diagnostic nature of the output, and a precise data-retention policy including the 30-minute claim-link window and deletion of unclaimed values.

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 core purpose and the alternative-tool routing are front-loaded in the first two sentences. The retention sentence is long and slightly heavy for its position, but it carries substantive privacy information rather than 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 explanation is unnecessary. Given a one-parameter tool with full schema coverage and complete annotations, the description still supplies privacy constraints, the alternative path, and what the result means clinically—nothing an agent needs to call it safely 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 100% and the single nested parameter is documented with an inline example, so the schema carries the semantics. The description's biomarker examples ('A1c, eGFR, LDL') loosely map to the schema but add no format or naming rules beyond it, so baseline 3 applies.

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

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

States a specific verb and resource ('fast first look at a few lab values'), names the concrete outputs (A1c, eGFR, LDL flagged against PRISM reference ranges), and scopes it with 'not a diagnosis.' It is clearly separable from explain_my_lab_results and full_prism_report 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?

Explicit routing: use explain_my_lab_results for guideline-cited suggestions, use this for a quick reference-range check on synthetic/de-identified data only. It also states a hard exclusion ('Do NOT submit PHI'), which is exactly the kind of when-not guidance agents need.

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, idempotent, non-destructive, closed-world, and the description adds genuine value beyond them: no input is analyzed, the patient is fictitious, and PHI must not be submitted. The retention sentence is the weak spot — it describes a claim link holding 'the submitted values' for up to 30 minutes even though the tool accepts no inputs, which reads as carry-over text and muddies the data-handling story.

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 payoff ('Free and instant: returns a complete sample...') and scannable, but it runs long for a zero-parameter demo tool. The non-real-patient point is made twice (in the opening and again as 'not a real patient'), and the retention clause about 'submitted values' consumes a sentence that does not apply here.

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?

Complete on the axes that matter: purpose, safety posture, PHI restriction, and sibling routing, with return values covered by the output schema so no format description is required. The one gap is the retention/claim-link sentence, which is unexplained and inert for a tool with no inputs, leaving an agent unsure whether any data-handling consideration applies at all.

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

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

Zero parameters, so the baseline is 4, and the description reinforces this by stating outright that the tool takes none — preempting an agent's attempt to pass demographics. No further parameter meaning is needed or possible.

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 concrete deliverable — a complete sample PRISM report for a made-up 58-year-old with type 2 diabetes — and immediately clarifies it is a fixed sample that analyzes no input. The sibling differentiation is explicit: explain_my_lab_results is named for the compute-your-own-values case, and the fixed-sample framing separates it from full_prism_report and start_lab_analysis.

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 positive trigger (show the owner what they would get before they sign up) and routes the alternative case explicitly ('For your own made-up values use explain_my_lab_results'). It also sets exclusions for data type (SYNTHETIC or de-identified only) and forbids PHI, leaving nothing to inference.

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

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

Annotations already mark this read-only, open-world and non-destructive, but the description adds genuinely new behavior: the async job pattern, an expected 30-60 second runtime, a 30-minute result retention window, and the fact that no clinician reviews the output. The PHI constraint ('never names, dates or record numbers') is a critical operational caveat that 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?

Front-loads the identity of the analysis and the async/job mechanics before the output inventory, and every clause carries content. The opening sentence is long and the parenthetical output list is dense, but no sentence 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?

There is no output schema, so the description must explain return values, and it does: the health picture components (plain-language story, graded connections, doctor questions with urgency, due tests, safety notes, unknowns) plus the recommendations shape and the job_id. Combined with the timing and retention notes, an agent has everything needed to call it and to poll 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 coverage is 50%: biomarkers and conditionFocus carry schema descriptions, while age and biologicalSex do not. The description reinforces the biomarker constraint (made-up or de-identified values only), which is valuable, but adds nothing about what age or biologicalSex are used for. Baseline 3 is appropriate given the partial 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?

States a specific action and resource: it produces a PRISM 2 lab-panel reading (model reasoning plus a second automated check), and returns a job_id rather than the reading itself. It also positions itself against explain_my_lab_results by saying the output has the 'same recommendations shape', implying PRISM 2 is the deeper variant, though it never names a clear contrast with full_prism_report or quick_check.

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 follow-up mechanics: call get_lab_analysis with the job_id after about 30 seconds, pending until ready, result kept 30 minutes. That is precise when-to-use guidance for the retrieval sibling. It stops short of saying when an agent should pick this over quick_check or explain_my_lab_results, leaving that comparison 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?

Goes well beyond the supplied annotations: it discloses the email/link delivery mechanism, that "Nothing attaches to their account until they confirm; unused, it is deleted after 3 days," and that "The answer is the same whether or not they already have an account" — directly explaining the non-idempotent, open-world behavior. The privacy guardrail ("never lab values, names, birth dates or documents") adds consent/PII handling not encoded anywhere in the structured 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?

Front-loads the outcome (sign-in link) and the consent gate, then layers the pre-population and retention details; almost every sentence carries operational weight. The opening tagline "Every doctor, your complete record" is mild product framing rather than instruction, the only genuinely dispensable clause.

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

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

With an output schema present, the description needn't explain returns, and it nonetheless warns that the response is identical for existing and new accounts. For a 5-parameter, nested-object, open-world tool it covers the consent gate, data provenance, retention, and PII limits — everything an agent needs to invoke it 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 coverage is already 100%, so the schema defines each field; the description adds provenance the schema lacks by tying hospitals to get_my_medical_records, job_ref to prepare_for_my_appointment, and care_gaps to check_care_gaps. It also restates the content restriction ("Hospital names and closed options only"), reinforcing the schema's "closed options only" note.

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 ("Start my Phi Longevity account" / "call this with their email address") and immediately explains the effect: "Phi Longevity emails them a one-tap sign-in link (no password, free to start)." It is clearly distinguishable from the read-only siblings like get_my_medical_records and check_care_gaps, which it names as data sources rather than alternatives.

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 ("When the person you are helping wants their own Phi Longevity account") and a hard prerequisite ("ask them first; never call it without their clear yes"). It also tells the caller what to pre-populate from which sibling tools. It does not explicitly contrast against how_to_get_started_for_my_owner, so the alternative-routing is inferred rather than stated.

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