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

Beyond the annotations, the description discloses that the call does not execute anything, requires a deployment-supplied step-up token the agent cannot pass, never accepts a human-confirmed flag, returns status 'awaiting_confirmation', and terminates the agent's turn. This adds valuable behavioral clarity without contradicting readOnlyHint=false or destructiveHint=true because the destructive/real-world effect is deferred to the patient's confirmation.

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 front-loads the core purpose, then each sentence adds a distinct operational fact: auth requirement, no execution, no confirmation flag, return status, terminal behavior, and follow-up tool. There is no filler or 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?

Despite having no output schema, the description supplies the essential return detail and names the companion tools action_propose and action_status. Auth, side-effect scope, and repeat-call policy are all covered, leaving no critical gap for an agent selecting or invoking the 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?

The input schema already fully describes action_id as the ID returned by action_propose, so the description is not required to compensate. It reinforces that the action must be previously proposed and that the same id must not be reused, but it adds no format-level semantics beyond the schema.

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

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

The description names a specific verb and resource: submit a previously proposed action for the patient's out-of-band confirmation. It clearly separates this from upstream action_propose and downstream action_status, so an agent can place it in the workflow.

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 explicitly states the precondition: call only AFTER the patient has reviewed and agreed to the draft. It also instructs to use action_status to check approval and warns not to call action_commit again for the same action_id, providing both when-to-use and 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 indicate read-only and non-destructive behavior; the description confirms no execution and adds the draft review step, providing full transparency without contradiction.

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

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

Two concise sentences front-load purpose and behavior, with zero wasted words.

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?

Despite no output schema, the description adequately explains the return value (draft with id + script) and the required workflow, making it complete for the tool's complexity.

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

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

Schema coverage is 100% with detailed descriptions for both parameters; the tool description adds no new information beyond what the schema already provides, so a baseline score of 3 is appropriate.

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 states the tool proposes a real-world action (phone call or SMS) on the patient's behalf and distinguishes it from the sibling action_commit by noting it returns a draft for review.

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 the draft must be reviewed before submitting via action_commit and clarifies that it does not execute anything, providing clear when-to-use and alternative 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=true and destructiveHint=false, aligning with the 'check' verb. The description adds behavioral context beyond annotations by explaining the implications of specific statuses (declined, needs_review, unknown) and prescribing follow-up actions, which prevents inappropriate re-proposals. No contradiction 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?

The description is comprehensive yet efficient, starting with the purpose and status list, then explaining critical statuses with actionable guidance, and ending with usage context. Every sentence adds value with no filler, and the main function is front-loaded.

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 single-parameter read-only status tool with no output schema, the description covers the tool's function, all possible outcomes, their meanings, and when to use it. The only minor gap is not explicitly describing the return structure, but the status enumeration implies it. Given the simplicity and annotations, this is nearly 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?

The single parameter action_id is described in the schema as 'ID returned by action_propose', and the description also mentions action_propose, reinforcing its origin. Schema coverage is 100%, so the description does not add extra detail; baseline 3 is appropriate since the parameter is fully documented.

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 states the tool's purpose: to check the status and outcome of an action, enumerating all possible statuses. It differentiates from siblings by referencing action_commit and action_propose, making it evident this is a read-only status query rather than a creation or confirmation 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?

The description explicitly instructs usage after action_commit to check patient approval and report the final result. It also provides conditional guidance: never re-propose for declined or unknown, and show evidence for needs_review. This gives clear when-to-use and when-not-to-use advice relative to alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds value by stating it is guideline-based decision support, explicitly clarifying it is not a diagnosis or directive, and mentioning the _meta.ui.resourceUri in the response that points to an embeddable review UI. These are behavioral traits beyond the annotations, giving the agent useful context about what the tool does and what the response includes.

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 two sentences with no fluff. The first sentence states the core purpose and scope, and the second sentence clarifies the decision-support nature and points to a UI resource. It is front-loaded and every sentence earns its place, making it highly efficient and readable.

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 single-parameter, read-only tool with no output schema, the description covers the essential aspects: what it checks, the guideline basis, the 'not a diagnosis' caveat, and a key response element (the UI resource). It does not detail error handling or behavior when no gaps are found, but given the tool's complexity and the annotations covering safety, the description is sufficiently complete for an agent 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?

The single parameter 'subject' is fully described in the schema with an example ('Patient/pt-1'), and schema coverage is 100%. The description does not add any additional meaning or constraints about the parameter beyond what the schema already provides. With high schema coverage, a baseline of 3 is appropriate since the description doesn't need to compensate.

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 states a specific verb ('Check') and resource ('preventive-care screenings/immunizations'), and enumerates concrete examples (blood pressure, cholesterol, etc.). It also names the guideline sources (USPSTF/ACIP/ADA), which distinguishes it from generic FHIR read/search tools in the sibling list. The purpose is unambiguous and distinct.

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 implies the use case: when you need to check which preventive-care screenings a patient may be due for. It also notes it is 'not a diagnosis or directive', which is a limitation but not an explicit routing instruction. It does not name alternatives or specify when NOT to use this tool, though the purpose itself makes the context clear. This is implied usage rather than explicit 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 cover safety profile (readOnlyHint, destructiveHint). Description adds context about bounded, policy-stamped, time-limited return, which goes beyond annotations but is not extensive.

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 concise sentences, each adding value. Front-loaded with action and key properties, no redundant or unnecessary words.

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 simple tool with one parameter and annotations, description adequately explains what is returned and key attributes. Could elaborate on 'context envelope' for full completeness.

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 parameter meaning is clear from schema. Description adds no specific parameter details beyond the schema, achieving baseline score.

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?

Description clearly states it retrieves a context envelope with FHIR resources, distinguishing it from generic read tools. However, it does not explicitly contrast with sibling tools like fhir_read or fhir_search, leaving some ambiguity.

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 guidance on when to use this tool versus alternatives, no prerequisites or exclusions provided. Agent must infer usage from context.

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 readOnlyHint=true annotation, the description fully discloses the non-mutating draft behavior, the two-phase approval requirement, the version pinning with refusal-on-change, and the linked Provenance record on the eventual execution. This is rich, accurate behavioral context that no structured field conveys.

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, each earning its place: the first states purpose, the second details workflow and non-effect, the third explains version pinning and field restrictions. It is front-loaded with the most important fact (proposal, not execution) and contains 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?

Despite having no output schema, the description tells the agent what it returns ('a draft (action id)'), the required subsequent step (action_commit), the out-of-band approval, and the concurrency guard. For a tool that is one step in a multi-step workflow, this is as complete as an agent needs to invoke 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?

With 100% schema description coverage, the baseline is 3, but the description adds meaningful semantics: it explains that record_version can be omitted and the tool reads the current version, and it restricts fixes to fields the evaluator can propose. These clarifications go beyond the schema's literal parameter descriptions and help the agent choose correct values.

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

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

The description opens with a specific verb and resource ('Propose data quality fixes to a FHIR resource as a 'curatr-fix' action') and immediately clarifies that it is a proposal, not an execution ('Nothing changes when this is called'). It distinguishes itself from siblings like action_commit and fhir_propose_write by explicitly framing the draft-then-commit workflow, leaving no ambiguity about the tool's role.

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 names the next step in the workflow ('the patient must submit with action_commit') and states what this tool does not do ('Nothing changes when this is called'), giving clear when-to-use/when-not-to-use guidance. It also signals a dependency on the Curatr evaluator by declaring 'Only fields the Curatr evaluator can propose are accepted,' effectively telling the agent to consult curatr_evaluate first.

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

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

The description adds significant behavioral context beyond the annotations: it specifies external terminology services used (tx.fhir.org, NLM, RXNAV), output format (plain language with impact descriptions and suggestions), and confirms read-only with 'no step-up required.' No contradiction with readOnlyHint=true.

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 concise sentences, front-loaded with the core purpose, and each sentence adds distinct value: purpose, technical detail, and behavioral trait. No unnecessary words.

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 tool's complexity (evaluating FHIR data quality with multiple services), the description covers the key aspects: what it does, how it does it, what output looks like, and its read-only nature. Even without an output schema, the output description is sufficient. Annotations cover safety profile. The description feels complete for an agent to use 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 100% with clear descriptions for both parameters. The description does not add new information about parameter semantics beyond what the schema already provides, thus baseline score of 3 is appropriate.

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 states the tool evaluates a FHIR resource for data quality issues, specifying it checks coding elements against public terminology services and structural rules. This distinguishes it from sibling tools like fhir_validate or guardrail_conformance, which are more about validation or conformance.

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 implies usage for data quality evaluation of FHIR resources, but does not explicitly state when to use this tool over alternatives like fhir_validate or curatr_apply_fix. It provides helpful context about the checks performed, but lacks direct guidance on exclusions or when not to use it.

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 destructiveHint=false. The description adds valuable behavioral detail: server-side PHI redaction, return of full document with metadata, and 'ChatGPT-connector-compatible' operation. No contradictions.

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, concise sentence that packs essential information: purpose, id format, return content, and redaction. It is front-loaded and efficient, though it could benefit from slight restructuring for clarity.

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

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

For a simple fetch tool with one parameter and no output schema, the description adequately covers the inputs, return value, and server-side processing. It does not discuss error handling or permissions, but the annotations cover safety.

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 parameter description in the schema is identical to the usage in the tool description. The description adds no new meaning beyond what the schema already 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?

The description clearly states it fetches a single FHIR resource by ID and returns the full document with PHI redacted. It specifies the id format 'ResourceType/id', distinguishing it from search endpoints. However, it does not explicitly differentiate from the sibling tool 'fhir_read', which likely serves a similar purpose.

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 implies usage after a search by stating 'as returned by search', but it lacks explicit guidance on when to use this tool versus alternatives like 'fhir_read' or 'fhir_search'. No mention of when not to use it.

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 annotations already include destructiveHint: true, and the description redundantly states 'This is a destructive operation.' However, it adds value by disclosing the need for a step-up authorization token, which is not covered by annotations. The description goes beyond annotations but only marginally.

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 very concise with only two sentences, front-loading the core purpose. Every sentence contributes information. However, it could be slightly reordered for better impact, but overall it is efficient.

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 there is no output schema, and the siblings include fhir_propose_write, the description should explain the relationship with the propose step (e.g., 'Call after fhir_propose_write to finalize'). It also lacks details about what gets destroyed or the return value. The description is incomplete for an agent to use correctly in context.

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 description does not discuss any parameters. The input schema has two parameters with descriptions, but the 'operation' parameter description incorrectly repeats the resource description, reducing its usefulness. With 50% schema coverage and no compensatory information in the description, the parameter semantics are poorly supported.

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 'Commit a previously proposed write', which clearly indicates the verb (commit) and the resource (previously proposed write). However, it does not explicitly differentiate from sibling tools like action_commit, so there's room for improvement in distinguishing from similar tools.

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 mentions a prerequisite ('Requires step-up authorization token') but provides no guidance on when to use this tool versus alternatives, nor does it exclude any inappropriate use cases. No when-not or alternative references are given.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds 'Redacted, audited' and mentions curation_state and quality_score surfaces, plus an embeddable review UI link. No contradictions.

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, each adding value: first states core function, second gives usage context, third lists additional outputs. No wasted words.

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?

Tool has two required params and no output schema, but description adequately explains the key outputs (provenance, curation_state, quality_score, UI link). Could mention any rate limits or performance characteristics, but not essential for a read-only tool with annotations.

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 covers both parameters fully (100% coverage). Description does not add new details about parameters themselves, but explains what the tool produces (provenance, curation_state, quality_score, UI link), which indirectly clarifies the expected input usage. Baseline 3 is appropriate.

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?

Description clearly states it returns 'current best understanding of a FHIR resource plus the append-only evidence trail (Provenance entries)'. Distinguishes from siblings like fhir_read by focusing on compiled truth with provenance and quality indicators.

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

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

Explicitly says 'Use this before presenting resource-specific facts to a patient', providing specific context for its use. Does not mention when not to use or alternatives, but the sibling list is large and this guidance helps narrow down.

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 readOnlyHint/destructiveHint annotations, it discloses the 5-minute expiry, that the token is carried in the X-Step-Up-Token header set by the caller, and that the tool is a privileged operator tool withheld from hosted deployments. These are behavioral details that materially affect invocation and use.

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, each carrying essential information: purpose, expiry, then operational constraints. The most important identifying statement is first, and 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?

For a one-parameter token tool, the description is nearly complete: purpose, expiry, header name, and deployment availability are all covered. The only gap is the absence of an explicit response-shape description (no output schema exists), so the agent must infer how the returned token is represented.

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 single parameter tenant_id is fully documented in the schema ('Tenant ID to scope the token to'). The description does not add new parameter-level meaning, so the baseline of 3 applies; it only reinforces the scoping context indirectly via 'for write operations'.

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 uses a specific verb-resource pair ('Get a fresh step-up authorization token') and states the purpose ('for write operations'). This clearly marks it as a token-minting tool rather than one of the many write/read siblings, even without naming 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?

It gives clear context for when to use it: when a fresh step-up token for write operations is needed, and the 5-minute expiry implies it should be obtained right before the write. It also gives a strong when-not/how-not constraint — the token is never an argument to another tool and is not present in hosted deployments — though it does not name alternative tools.

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 destructiveHint=false, and the description reinforces with 'Read-tier'. It adds beyond annotations by specifying the response contains clinician and consumer summaries and includes a resourceUri for a trend timeline, plus the caution that it's decision support, not diagnosis. 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?

The description is three sentences, each adding essential information: the action and flags, the decision-support caveat, and the response detail. No fluff or redundancy; front-loaded with the primary purpose.

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?

The description explains the output (summaries, resourceUri) and safety (read-tier, not diagnosis). It leaves a minor gap: it does not clarify that at least one of bundle, subject, or observation must be provided, but this is a read-tier tool and schema descriptions partially cover this.

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% for all three parameters (bundle, subject, observation), each already having a clear description. The tool description does not add additional parameter-specific guidance beyond the schema, so the baseline of 3 is appropriate.

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 ('Interpret') and resource ('lab Observations'), and explicitly details what interpretation yields: flags values low/normal/high/critical and returns summaries. This distinguishes it from generic read/search siblings.

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

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

The description provides context ('Decision support, not diagnosis' and 'Read-tier') but does not name specific alternative tools or explicitly state when not to use it. The intended use is clear from the verb and resource, but no exclusions or comparisons are given.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description aligns with 'Get' and 'Returns'. It adds behavior detail 'by storage order', which is useful. No contradictions. With annotations covering safety, the description provides additional ordering 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?

The description is concise with two sentences. The first sentence efficiently states the core function, and the second adds standard reference and ordering behavior. No unnecessary words.

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 tool with 3 optional parameters and no output schema, the description explains the core operation (last N per code, FHIR standard, storage order). It does not detail return format or empty results, but the information provided is sufficient for basic usage.

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

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

Schema coverage is 100% with clear parameter descriptions. The description only reinforces 'per code' for the code parameter but adds no extra meaning beyond the schema. Baseline score is appropriate as no additional semantic value is 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?

The description clearly states the verb 'Get', resource 'observations per code', and explicitly references the standard FHIR $lastn operation. It distinguishes itself from sibling tools like fhir_search by specifying 'per code' and 'last N' semantics.

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 indicates it's the standard way to retrieve last N observations per code but does not explicitly state when to use this tool versus alternatives like fhir_search. It lacks guidance on exclusions or prerequisites, leaving the agent to infer usage context.

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 indicate readOnlyHint=true and destructiveHint=false, so the description does not need to repeat that. It adds that the tool returns permit/deny, which is behavioral, but no additional context on authentication, rate limits, or side effects. Given the annotations, the description is adequate but minimal.

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 concise at three sentences with no redundant information. It front-loads the purpose and adds a clarifying statement about the distinction from Consent.

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 tool's simplicity, the description covers the core functionality (evaluate permission, return permit/deny) and clarifies the separation from consent. It lacks mention of edge cases or default behavior but is sufficient for a straightforward evaluation 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?

The input schema has 100% coverage, so baseline is 3. The description does not add any extra meaning or context for the parameters beyond what the schema already provides (action enum, subject and resource strings).

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 states the tool evaluates R6 Permission resources for access control decisions and returns permit/deny. It specifically mentions the resource type (R6 Permission) and the output, and distinguishes from Consent records. No sibling tool performs this exact function.

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 provides some context by separating Permission from Consent, implying when to use this tool (for access control) vs. a consent-related tool. However, it does not explicitly state when to use or not use this tool, nor does it name any alternative tools.

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

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

The description goes beyond the annotations by disclosing critical runtime behavior: it requires an X-Step-Up-Token header supplied by the deployment, and the agent cannot obtain or pass it itself. It also specifies the exact return condition 'requires_step_up' when the token is absent and instructs the agent to inform the patient rather than attempt another route. The annotation readOnlyHint=true already covers the non-committing nature, but the description adds significant operational details, making behavior fully transparent.

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 well-structured and front-loaded with the core purpose ('Propose a write — validates the resource and returns a preview'). It then covers the non-commit behavior, the token requirement, and the contingency plan in a compact sequence. Every sentence earns its place, and it avoids fluff. It is slightly longer than strictly necessary but remains efficient and clear.

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 that there is no output schema, the description mentions that it 'returns a preview' but does not specify the structure or content of that preview. This could be a gap for an agent expecting to interpret the result. However, it does mention the error condition 'requires_step_up' and the necessary authorization context. For the tool's complexity (nested resource, single operation enum), the description is largely complete, but the lack of preview detail leaves it one step short of full completeness.

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 input schema provides 100% coverage for both parameters (resource and operation) with clear descriptions and an enum for operation. The tool description does not add any additional meaning beyond the schema—it doesn't explain resource structure or operation options more deeply. Given the high schema coverage, a baseline score of 3 is appropriate, as the schema already carries the semantic load.

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 states the tool's purpose: 'Propose a write — validates the resource and returns a preview.' This uses a specific verb (propose/validate) and resource (write) and distinguishes it from the committing sibling (fhir_commit_write) by explicitly noting it 'Does NOT commit.' The agent can immediately grasp what this tool does and how it differs from other write-related tools.

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 provides clear context on when to use the tool ('Propose a write') and notes that it does not commit, implying it is for previewing before an actual commit. It also explains the step-up token requirement and directs the agent on how to handle the 'requires_step_up' response. However, it does not explicitly name an alternative like 'use fhir_commit_write to actually commit,' relying on the sibling list and context signals to make that connection. This is a minor gap.

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 as read-only and non-destructiveasi. The description adds useful context beyond annotations: version support for FHIR R4 US Core v9 and R6 ballot3, plus return behavior of a 'redacted resource with PHI protection.' This is meaningful behavioral disclosure for a clinical data tool.

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

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

Two sentences with no filler. The core operation is front-loaded, followed by a concise note on supported FHIR versions and returned data. Every sentence 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?

For a simple read tool with two required parameters and safe annotations, the description covers the operation, resource scope, version support, and return redaction. It does not explain error cases or exact response shape, but those are less critical given the absence of an output schema and the low complexity of the call.

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%, with resource_id described and resource_type having an enum. The description says 'by type and ID' and clarifies supported resource versions, but it does not add format details for resource_id or explain which versions apply to specific enum values. It provides marginal compensation but not full extra semantic depth.

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 and resource: 'Read a specific FHIR resource by type and ID.' This clearly distinguishes it from siblings like fhir_search and search, which are for finding resources rather than reading one by known identifiers.

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 clearly establishes the intended use case—reading a resource when you have its type and ID. It does not explicitly name alternatives or exclusions, but the contrast with fhir_search is implied strongly enough for an agent to route correctly.

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 destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it returns a 'paginated, redacted Bundle' and notes that _count is 'capped for token safety', which discloses output behavior and a safety constraint beyond the 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 sentences with no waste. The core purpose is front-loaded, followed by supported versions, parameters, and output behavior. Every sentence 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?

For a read-only search tool with rich schema coverage and annotations covering safety, the description is nearly complete. It covers supported FHIR versions, parameters, and output format. It could mention pagination behavior in more detail (e.g., how to request next pages), but the 'paginated' note is sufficient for basic use.

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 86%, so the schema already documents most parameters. The description adds meaning by grouping the parameters (patient, code, status, _lastUpdated, _count, _sort) and noting the _count cap for token safety, which is not in the schema. It does not fully compensate for the undocumented parameter, but the schema carries most of the burden.

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 ('Search') and resource ('FHIR resources'), and immediately distinguishes itself from siblings like fhir_read and fhir_lastn by listing supported parameters and resource types. It clearly identifies what the tool does and its scope.

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 provides clear context on what the tool supports (FHIR R4 US Core v9 stable and R6 ballot3 experimental resources) and lists the filter parameters, which implies when to use it. However, it does not explicitly state when not to use it or name alternative tools like fhir_read or fhir_lastn for specific use cases.

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 indicate readOnlyHint=false and destructiveHint=false. The description adds that the tool writes (seeds) data and returns a step_up_token, which is useful context. No contradictions; the behavioral summary is transparent for a population tool.

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 fluff. The purpose and usage are front-loaded, and every word adds value. Highly concise.

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 one optional parameter and no output schema, the description covers the main points: action, when to use, and what is returned (IDs and token). Could specify format or more detail, but sufficient for a simple seeding 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?

Parameter schema has 100% coverage with a description for tenant_id. The tool description does not add extra meaning beyond the schema, which is adequate. Baseline 3 is appropriate as schema already documents the parameter.

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?

Clearly states the action (seed), specific resources (Patient + Observations + Condition bundle), and purpose (live testing, demo session). The description is distinct from sibling tools, which focus on reading, searching, or committing, not seeding demo data.

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

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

Explicitly says 'Use this at the start of a demo session to populate data,' providing clear context. While it doesn't explicitly state when not to use, the demo/testing context is clear and implies production avoidance. No alternatives mentioned, but the tool is unique among 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 indicate readOnlyHint=true and destructiveHint=false. The description adds that it is a standard FHIR operation and only supports valueQuantity, which is behavioral context beyond annotations. No contradictions.

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 concise with three sentences. The first sentence immediately states the tool's purpose, and no extraneous information is included. Efficiently structured.

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 tool's simplicity and no output schema, the description covers the key aspects: purpose, supported value type, and filtering. It does not detail the output format, but the listed statistics (count, min, max, mean) provide reasonable expectation.

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 both parameters are described in the schema. The description adds meaning by explaining filtering and providing an example format (LOINC code) for the 'code' parameter, which goes beyond the schema.

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

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

The description clearly states the tool computes statistics (count, min, max, mean) over numeric Observation values using valueQuantity, and mentions FHIR R4 standard. This is specific and distinguishes it from sibling tools like fhir_search or fhir_interpret_labs.

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 provides context on filtering by patient and/or code, and specifies that only valueQuantity is supported. It implies usage for numeric observation statistics but does not explicitly exclude alternative scenarios or mention when not to use the 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 readOnlyHint=true, so the description does not need to reiterate safety. It adds some context about R6 and normative status but does not disclose additional behavioral traits beyond what annotations provide.

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 two sentences, concise and front-loaded with the main action. Every sentence adds value without 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?

Given the tool's simplicity (no parameters, no output schema), the description is complete. It explains what the tool does and why it is relevant (R6 normative status), which is sufficient for an agent to understand its purpose.

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 input schema has no parameters, so schema description coverage is 100% by default. With zero parameters, the description does not need to add parameter semantics, and the baseline score of 4 is appropriate as there is no missing information.

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

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

The description clearly states the verb 'List' and the resource 'SubscriptionTopics', and distinguishes from siblings by specifying 'event-driven subscriptions' and 'discover what events they can subscribe to', which is not the purpose of other tools like fhir_read or fhir_search.

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 indicates when to use the tool: to discover events for subscriptions. It does not explicitly state when not to use it or provide alternatives, but the context is clear enough for agents to infer appropriate usage.

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 indicate readOnlyHint=true, destructiveHint=false. Description adds that validation is structural and returns OperationOutcome. Does not contradict annotations; could elaborate on what happens on failure or whether it interacts with external systems.

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 efficient sentences with front-loaded action. No redundant information; every sentence adds 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?

Given a single parameter with full schema coverage and annotations present, the description is adequate. Mentions return type; could specify whether it accepts bundles or single resources, but overall sufficient.

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 has 100% coverage with description 'The FHIR resource to validate'. Description adds no additional parameter meaning beyond the schema, 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?

Clearly states the verb 'validate', the resource 'FHIR R6 resource', and the scope 'against structural rules'. Also mentions the return type 'OperationOutcome'. Distinct from sibling tools like fhir_read or fhir_commit_write.

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 explicit guidance on when to use this tool vs alternatives. Usage is implied as a pre-commit check, but no exclusions or contextual hints provided.

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 destructiveHint false. The description adds that the tool uses synthetic data only and may return cached results (with a 10-minute staleness). It does not mention specific auth requirements or error behavior, but the annotations cover the safety profile.

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: the first states the main purpose and enumerates the seven guardrail properties; the second explains the lone optional parameter. No wasted words, front-loaded with the core action.

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 no output schema, the description lists the seven properties in the scorecard, which provides sufficient expectation. It also explains caching and synthetic data. However, it lacks prerequisites or error conditions, which are not critical for a self-test tool.

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

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

Schema coverage is 100% for the single 'fresh' parameter. The description adds context that the cached result is <=10 minutes old and that setting fresh=true forces a new run, which goes beyond the brief schema 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?

The description clearly states the tool runs a guardrail conformance self-test and returns a graded scorecard across seven specific properties. It distinguishes itself from the numerous sibling tools, none of which perform a similar guardrail 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?

The description implicitly indicates when to use (to check guardrail conformance) and includes a note about synthetic data, but does not explicitly state when not to use or discuss alternatives. The uniqueness among siblings reduces the need for explicit exclusions.

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 indicate destructiveHint=true and readOnlyHint=false, but the description adds valuable context: it requires step-up authorization even for dry_run=true previews. This goes beyond the annotations and clarifies that the operation is sensitive. However, it does not specify whether the extraction itself commits or merely returns a Bundle, leaving some behavioral ambiguity.

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 sentence that front-loads the primary action, names the output, and includes a critical authorization note. Every word earns its place with no filler or 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?

For a tool with no output schema and nested object parameters, the description should clarify whether the transaction Bundle is returned or committed. It mentions the Bundle as the target but does not explicitly state the tool's side effects or return value beyond that. The authorization note is useful, but the ambiguity about commit vs. extract leaves a gap for agents deciding whether to use this or fhir_commit_write.

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 input schema has 100% description coverage for all three parameters, so the baseline is 3. The description mentions dry_run in the authorization context, reinforcing the parameter's purpose, but adds no new syntax or format details beyond what the schema already provides. No extra compensation is needed.

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 operation (SDC $extract) and a concrete resource (completed QuestionnaireResponse) plus the output (transaction Bundle). It clearly distinguishes itself from siblings like questionnaire_populate (which populates a form) and fhir_commit_write (which commits a bundle), making its purpose 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 description states the core action and notes the write tier and authorization requirement, but does not explicitly enumerate when to use this tool versus alternatives or provide exclusion conditions. The 'Write tier' phrase hints at a context but does not guide an agent on when to prefer this over fhir_propose_write or fhir_commit_write.

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 indicate readOnlyHint=true and destructiveHint=false. Description adds value by stating it mints a tenant token, which is not in annotations, and clarifies the access tier. No contradiction.

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

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

Two sentences, front-loaded with key action and result, no redundant words. Every sentence adds 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?

Despite no output schema, description specifies return type (QuestionnaireResponse). It mentions token minting for non-public tenants, adding context. Could elaborate on when to use inline vs stored questionnaire, but schema handles that.

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 covers all three parameters with descriptions (100% coverage). Description does not add additional meaning beyond what is in the schema, so baseline score of 3 is appropriate.

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 'pre-fill a Questionnaire for a subject' with a specific verb and resource, and includes return type and access tier. It distinguishes from sibling 'questionnaire_extract' by focusing on population rather than extraction.

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?

Description mentions 'Read tier' indicating safe context, and notes token minting for non-public tenants, but does not explicitly state when not to use or provide alternative tools. Sibling list includes 'questionnaire_extract' which could be an alternative but is not referenced.

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 indicate readOnlyHint=true and destructiveHint=false, and the description confirms it only creates a draft, not executing any action. It adds behavioral context: Schedule II refusal, need for patient review, and reliance on action_commit for confirmation. 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?

The description is three sentences, front-loaded with the core action. Every sentence adds essential information: purpose, process, constraints, and next steps. No redundancy or unnecessary detail.

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?

Despite no output schema, the description states what is returned (a draft requiring review) and explains the workflow with action_commit. It covers key behavioral aspects (Schedule II refusal) and the open-world hint (patient must review). It could detail the draft format more, but it's complete enough for an agent to use 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 100%, so baseline is 3. The description adds meaning beyond the schema by explaining medication_names as optional limiting and clarifying the roles of from_pharmacy vs to_pharmacy. It also connects parameters to the transfer process, adding value.

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 states the tool drafts a prescription transfer request, explains the US transfer process, and distinguishes from sibling action_commit. It specifies the resource (active medications) and the action (staging a phone call to receiving pharmacy). The purpose is unambiguous and differentiated.

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 says to use action_commit after reviewing the draft, providing a clear workflow. It also warns that Schedule II medications are not transferable, guiding appropriate use. However, it does not explicitly list scenarios where the tool should not be used (e.g., emergency transfers), but the context is sufficient for an AI agent.

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 destructiveHint=false. The description adds that results are compact (id, title, url), PHI-redacted, and audit-logged, providing valuable behavioral context beyond 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?

The description is three sentences with no redundancy: first sentence states purpose, second explains query format, third describes result and behavior. Front-loaded and efficient.

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

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

For a simple search tool with one parameter and no output schema, the description covers purpose, usage, and result format. It lacks mention of pagination or limits, but is otherwise adequate given the context.

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 schema already covers the 'query' parameter with a description. The description adds concrete examples (e.g., 'Observation?code=4548-4') which aid understanding, going beyond the schema's textual 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?

The description clearly states it performs a FHIR search over tenant records, specifying the query format. However, it does not differentiate from sibling tools like fhir_search, which likely have overlapping functionality.

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 how to form queries (FHIR search string or bare resource type), but does not provide guidance on when to use this tool versus alternatives like fhir_search or other search-related 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?

Goes far beyond the annotations by revealing a step-up authentication requirement via the X-Step-Up-Token header, client-side encryption with the server never seeing plaintext, and the returned artifacts (shlink URI, viewer link, private manage link). It also discloses the consent and privacy obligations. This fully carries the behavioral burden for a write operation.

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 compact and well-ordered: purpose first, process next, safety obligations last. Three sentences contain zero filler, and each sentence contributes either behavioral detail or critical usage constraints.

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?

Even though there is no output schema, the description names all three returned artifacts and explains the encryption, auth, and consent requirements. For a four-parameter, all-optional tool with this level of process complexity, an agent has everything needed to invoke 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 100%, so the baseline is 3. The description discusses the overall process but does not add parameter-specific detail; however, the schema already thoroughly documents each parameter (label, profile, patient_id, expires_in_days), so no compensation is needed.

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: 'Generate a SMART Health Link (shlink:/ QR payload) sharing the patient's record with a clinic.' This clearly distinguishes it from all listed siblings — none of which mention SHL generation or QR payloads — so an agent can identify the correct tool immediately.

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 conveys the use context: sharing a patient's record with a clinic. It also provides critical operational guidance, such as requiring explicit patient consent and delivering the manage link only to the patient. It does not explicitly name alternatives or exclusions, but no sibling performs a comparable SHL generation function, so the context is sufficient.

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

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

The description adds value beyond the readOnlyHint and destructiveHint annotations by explaining that the tool surveys all sources at once and returns per-source status and counts. This behavioral context is not deducible from annotations alone.

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: first describes functionality, second gives usage guidance. No filler, every word adds value. Front-loaded with the key action ('Survey ALL').

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 input and no output schema, the description sufficiently explains what the tool does and when to use it. It could be slightly more detailed about the output format, but it is adequate.

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 zero parameters, the schema covers all. The description doesn't need to add parameter info, and a baseline of 4 is appropriate as per guidelines.

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 uses the specific verb 'Survey' and clearly states it checks ALL connected health data sources at once, returning connection status and record counts. This distinguishes it from sibling tools like wearables_sync_status which focus on a single source.

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 provides use cases: 'when the patient asks what's connected or to check for data across services.' While it doesn't list exclusions, the context is clear enough for an agent to decide when to use this 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, providing a solid safety profile. The description adds context about data flowing into HealthClaw as FHIR Observations, but does not detail any additional behavioral traits like error handling or pagination. The added value is moderate.

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 well-structured, starting with the core function, followed by use case and data flow. It is informative without being excessively verbose. A minor reduction for including information about HealthClaw that is not essential for immediate tool usage.

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 simplicity of the tool (one optional parameter, no output schema), the description fully covers purpose, usage context, and output format. It also references the UI resource URI and relates to other tools, making it complete for agent decision-making.

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 covers 100% of parameters (tenant_id with description). The description does not add any additional semantics beyond what the schema already provides for the parameters.

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 explicitly states the tool lists wearable connections with details like last sync time, observation count, and status. It lists supported brands and clearly distinguishes itself from sibling tools like fhir_search by stating its specific use for checking sync status, not reading observations.

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 provides clear usage guidance: 'Use this to tell a patient what's connected, when data last arrived, and surface a connection-management UI.' It does not explicitly list when not to use or alternatives, but the context is sufficient for an agent to decide when to invoke this tool.

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