healthclaw-guardrails

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

Annotations already indicate destructiveHint: true, but the description adds context about step-up authorization and the need for explicit patient consent, which goes 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?

Two sentences with no superfluous information; front-loaded with the core action and conditions.

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 single parameter, no output schema, and adequate annotations, the description fully covers when, how, and prerequisites for using 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?

Schema coverage is 100% with one parameter. Description adds minor context that action_id comes from action_propose, but this is not substantially new 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 verb 'execute' and the resource 'previously proposed action', distinguishing it from siblings like action_propose and action_status.

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 specifies when to use (only after patient approval), prerequisites (step-up token via fhir_get_token), and the condition for invoking 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?

The description adds significant behavioral context beyond the annotations: it clarifies that the tool returns a draft and the patient MUST review before commit, and that it does not execute anything. This aligns with the readOnlyHint annotation and provides clear transparency.

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, consisting of two sentences that efficiently convey the purpose and key behavioral constraints without extraneous information.

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

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

For a tool without an output schema, the description mentions the return value (draft with id and script) and the workflow (review before commit). This, combined with the sibling tools like action_commit, provides sufficient context for correct 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?

With 100% schema description coverage, the schema already documents the 'kind' enum and 'payload' object. The description does not add new parameter details beyond what the schema provides, 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 clearly states the tool proposes a real-world action (phone call or SMS) on the patient's behalf, specifying the verb 'propose' and the resource 'real-world action'. It distinguishes itself from siblings like action_commit by noting that it only returns a draft and does not execute anything.

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 states the tool returns a draft that must be reviewed before commit and does not execute anything, thereby guiding when to use this tool versus action_commit. However, it does not explicitly list alternative tools or when-not-to-use scenarios.

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 clear. The description adds some behavioral context by listing statuses (proposed/executing/completed/failed) and mentioning reporting, but does not disclose further traits like permissions or rate limits.

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 long, the first fully covering the tool's purpose and outcome types, the second providing a usage direction. No superfluous words; 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 operation with one parameter and no output schema, the description is nearly complete. It specifies the action and possible statuses. It could have elaborated on the exact return structure (e.g., JSON fields) but the current text is sufficient for most use cases.

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 schema already describes the single parameter action_id as 'ID returned by action_propose'. The main description does not add additional parameter meaning beyond what the schema provides, 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 clearly states the verb 'Check' and targets the resource 'status and outcome of an action', listing possible statuses. It distinguishes from sibling tools like action_propose and action_commit by implying its role as the read/check step, though not explicitly naming 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 phrase 'Use after commit to report the result back to the patient' provides specific usage context and a workflow hint. However, it does not include when-not-to-use instructions or explicitly mention alternative tools for other scenarios.

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 annotations by stating the returned context is 'bounded, policy-stamped, time-limited.' This provides behavioral context that is not in the annotations, which already indicate read-only and non-destructive behavior.

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

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

The description is a single sentence that effectively front-loads the purpose and key characteristics, with no wasted words. Every part contributes to understanding.

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 low complexity (one parameter, no output schema), the description provides adequate context for basic understanding. However, it could mention what kind of resource the envelope contains or how to interpret the output.

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 parameter 'context_id' is described in the schema. The description does not add additional meaning beyond what the schema provides, warranting the baseline score of 3.

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 retrieves a pre-built context envelope with patient-centric FHIR resources using a specific verb and resource. It does not explicitly differentiate from sibling tools, but the unique 'context' concept sets it apart.

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, nor any context on prerequisites or typical use cases. The agent must infer usage solely from the purpose.

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?

Discloses creation of a linked Provenance record and step-up authorization needs, adding behavioral context beyond the annotations (which only indicate readOnlyHint=false and destructiveHint=false). No contradictions 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?

Two concise sentences: one for primary action (apply fix + Provenance), one for authorization requirements. No wasted words; front-loads key behavior.

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?

Missing output schema and no mention of return value or side effects (e.g., whether resource is updated in place). Given it's a write tool with no output schema, the description should explain what the agent gets back (e.g., success indicator, updated resource). Incomplete for a tool of this 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 covers all parameters with descriptions, so baseline is 3. The description adds no extra meaning beyond the schema; it only restates 'patient-approved' context. No parameter details beyond 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?

Clearly states it applies patient-approved data quality fixes to FHIR resources and creates a Provenance record. Differentiates from sibling tools like curatr_evaluate (evaluation) and action_commit (generic commit) by specifying the 'apply fix' and 'patient-approved' context.

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

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

Provides explicit authorization requirements (step-up token, human confirmation) for clinical resources, which guides when to use. However, it lacks explicit when-not-to-use guidance or direct comparison to siblings like action_propose or fhir_commit_write, leaving some ambiguity.

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 behavioral details: it checks against specific public terminology services, applies structural rules, and returns plain-language issues with patient-facing impact and resolution suggestions. This enriches the annotations 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?

The description is three sentences, front-loading the core action and then details. Every sentence adds value: purpose, what it checks, output format, and safety guarantee. 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?

Given the tool's complexity (multiple terminology services, structural rules, plain-language output) and the absence of an output schema, the description covers the essential aspects: what it evaluates, how it evaluates, and what it returns. It could mention whether the evaluation is synchronous or the format of the issues, but it is sufficiently complete for an agent.

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?

Input schema coverage is 100% with clear parameter descriptions ('ID of the resource to evaluate', 'FHIR resource type to evaluate'). The description does not add parameter-specific details beyond what the schema provides, so the description's added value is limited.

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 FHIR resources for data quality issues, specifying checks on coding elements against public terminology services (SNOMED, LOINC, ICD-10-CM, RxNorm) and structural rules. It differentiates from siblings like curatr_apply_fix by focusing on evaluation rather than applying fixes.

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 'Read-only — no step-up required' implying safe usage without special permissions, but does not explicitly guide when to choose this tool over siblings like fhir_validate or curatr_apply_fix. The context of data quality evaluation is clear, but alternative usage scenarios are not addressed.

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 read-only, non-destructive behavior. Description adds server-side PHI redaction and metadata return, which is useful 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?

Two sentences efficiently convey core purpose, input format, and output characteristics with no wasted words. Front-loaded with key 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?

For a simple read tool with one parameter and no output schema, description adequately explains inputs and outputs. Doesn't mention error handling or performance, but not critical.

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 already describes parameter, but description reinforces the format and source ('as returned by search'), adding practical context for correct usage.

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 the tool fetches one FHIR resource by id in 'ResourceType/id' format, distinguishes from search tools by referencing 'as returned by search', and specifies outputs (full document, PHI-redacted, with metadata).

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 implies usage after search results, but does not explicitly exclude alternatives like fhir_read or state when not to use. Provides context for typical workflow.

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 description reinforces this. Adds step-up authorization requirement, providing useful extra behavior 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?

Two sentences, 14 words, front-loaded with key action. No fluff, every word 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?

Covers main purpose, authorization, and destructiveness. However, lacks details on return value, how to use parameters effectively, and what constitutes a 'previously proposed write'. Adequate but has gaps.

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 50% schema description coverage (resource has description, operation does not), the description adds no parameter guidance. Could explain expected format for resource or operation choices, but omits.

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 verb 'commit' and resource 'previously proposed write', distinguishing from siblings like fhir_propose_write. Also mentions authorization and destructive nature, making 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?

Description implies use after a proposal action and specifies authorization requirement, but does not explicitly state when not to use or compare with alternatives like fhir_read.

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. The description adds that the response is 'Redacted, audited' and includes a `_meta.ui.resourceUri` pointing to an embeddable review UI. This provides extra behavioral context beyond annotations, such as redaction and audit features, 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?

The description is two sentences. The first sentence concisely states the core function. The second provides usage guidance and highlights key features (curation_state, quality_score, UI link). No redundant information.

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

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

Given the tool has 2 required parameters, clear annotations, and no output schema, the description sufficiently covers what the tool does and what it returns (compiled truth, evidence trail, curation_state, quality_score, resourceUri). It is complete for its intended 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 coverage is 100%, so the baseline is 3. The description does not add additional semantics beyond the schema's definitions for resource_type and resource_id. It mentions FHIR types in examples but does not enhance parameter understanding further.

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 returns the current best understanding of a FHIR resource along with an append-only evidence trail. It uses a specific verb ('Return') and identifies the resource type ('FHIR resource') and the additional provenance entries. This clearly distinguishes it from siblings like fhir_read or fhir_search which return raw resources or search 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?

The description advises using the tool before presenting resource-specific facts to a patient, highlighting that it surfaces curation_state and quality_score. This provides a clear when-to-use scenario. It does not explicitly mention when not to use it or alternatives, but the given context is sufficient for most 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 declare readOnlyHint=true and destructiveHint=false, and the description's 'Get' aligns. Adds context about token expiry (5 minutes) and return value (token string), enhancing transparency 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?

Three sentences, each purposeful: first states purpose, second gives usage context, third details expiry and output. 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 simple tool with one required parameter and no output schema, the description covers purpose, usage order, expiry, and output handling completely.

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?

Only one parameter (tenant_id) with 100% schema coverage. The description does not add new detail beyond what the schema provides, so baseline score 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?

The description clearly states the verb 'Get' and the resource 'step-up authorization token', specifying its purpose for write operations. It differentiates from sibling tools by naming specific subsequent 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?

Explicitly states when to use this tool: 'Call this before fhir_propose_write, fhir_commit_write, or curatr_apply_fix'. Also mentions token expiry. Lacks explicit when-not-to-use, but context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so the description's addition of 'Decision support, not diagnosis' and 'Read-tier' adds valuable behavioral context beyond what annotations provide, clarifying non-diagnostic use and read-only nature.

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, front-loaded with the core purpose, and ends with a critical caveat. Every sentence adds value with no redundancy or 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?

While the purpose and safety are clear, the description does not explain how multiple optional parameters interact (e.g., is bundle preferred over subject?), nor does it mention that reference ranges may depend on patient demographics. With no output schema, the return format details are absent. Adequate but has gaps.

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 parameter descriptions in the input schema. The tool description does not add any additional meaning or constraints beyond what is already in the schema, so the 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 interprets lab Observations against reference ranges, flags values (low/normal/high/critical), and returns clinician and consumer summaries. It distinguishes itself from sibling tools like fhir_read by adding interpretative 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 includes 'Decision support, not diagnosis' and 'Read-tier,' which provide some usage context but no explicit comparison to alternatives or when-not-to-use guidance. It lacks explicit differentiation from similar tools like fhir_search or fhir_validate.

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 description's mention of 'Returns most recent observations by storage order' adds minimal behavioral context. It doesn't discuss potential limitations or performance implications.

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 unnecessary words. The first sentence states the core action, and the second provides standard information. Well-structured and 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 the tool is a standard FHIR operation and has no output schema, the description is adequate but does not explain response format or pagination. For a simple tool with high schema coverage, it is minimally complete.

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

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

Schema description coverage is 100%, so each parameter (max, code, patient) is documented in the schema. The description adds 'per code' context but does not elaborate on parameter usage beyond what the schema provides. 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?

The description clearly states the action ('Get the last N observations per code'), identifies the FHIR standard operation ('$lastn'), and distinguishes from sibling tools like fhir_search by specifying 'per code' grouping. The title 'Latest Observations' reinforces the 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 for retrieving recent observations but does not explicitly state when to prefer this tool over alternatives (e.g., fhir_search with sorting). No guidance on when not to use it or specific prerequisites.

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 confirms it evaluates and returns results, adding context about separating from consent. No additional behavioral traits (e.g., side effects, auth needs) are disclosed. Consistent with annotations, 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?

Three sentences, each serving a purpose: states function, outputs, and differentiation from consent. No redundant or extraneous text. Efficient and 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?

No output schema exists, but the description notes the return is 'permit/deny', which is sufficient for the tool's simplicity. However, it does not cover prerequisites (e.g., authentication) or how multiple rules are handled. Adequate but could be more complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add any parameter-level details beyond what the schema provides (action, subject, resource). No additional meaning or usage context is given for 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 clearly states the tool evaluates R6 Permission resources for access control decisions, returning 'permit/deny'. It distinguishes this from consent records, making the purpose specific and 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 mentions separating access control (Permission) from consent (Consent), hinting at when to use this tool instead of a consent evaluator. However, it does not explicitly state when to use or not use this tool relative to the many sibling tools (e.g., fhir_read, curatr_evaluate). Guidance is implied but not strong.

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 read-only and non-destructive behavior. The description adds value by clarifying that no commit occurs and that no special authorization is needed, enhancing transparency beyond the 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 extremely concise at two sentences, front-loads the core action ('Propose a write'), and contains no superfluous words. Every sentence contributes essential information.

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

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

Given the lack of an output schema, the description should explain what the 'preview' contains (e.g., validation errors, success confirmation). It does not, leaving a gap in understanding what the tool returns.

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 does not add new parameter details beyond what the schema provides; it simply mentions validation and preview, which are already implied by the tool's purpose.

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 by validating the resource and returning a preview. It explicitly distinguishes from actual commits, and the verb 'propose' accurately captures the dry-run nature.

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 notes that the tool is safe to call without step-up authorization, implying it should be used before committing. However, it does not explicitly mention alternatives like fhir_validate or fhir_commit_write, leaving some ambiguity about when to use each.

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, establishing a safe read operation. The description adds behavioral details: returns a redacted resource with PHI protection and supports specific FHIR versions. This adds value beyond annotations, though it doesn't cover edge cases like error handling.

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 superfluous text. The primary action is front-loaded, and the second sentence adds necessary version and privacy context. Every word serves a 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?

Given the simple nature of a read operation with comprehensive annotations and schema, the description covers all essential aspects: action, parameters, supported resources, versions, and response characteristics (redaction). No gaps for typical 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 coverage is 50% (both parameters are documented in schema, but resource_type enum values lack individual descriptions). The description mentions 'by type and ID' but doesn't enrich beyond the schema's basic definitions. It adds some context about supported FHIR versions, marginally compensating for the coverage gap.

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

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

The description clearly states the action ('Read') and the target resource ('specific FHIR resource by type and ID'). It distinguishes from sibling tools like fhir_search (which retrieves resources based on criteria) by specifying direct retrieval via type and ID.

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 usage context by listing supported FHIR versions (R4 US Core and R6 ballot) and noting PHI protection. However, it lacks explicit guidance on when not to use this tool or alternatives (e.g., fhir_search for batch queries). The implied usage is clear but could be more directive.

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 behavioral context: supports two FHIR versions, returns paginated and redacted Bundle. 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?

Two sentences, front-loaded with purpose and supported versions, then parameters and return type. 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 no output schema, description adequately mentions return format (paginated, redacted Bundle). Covers supported versions and key parameters. Could mention read-only nature but annotations cover it. Reasonably complete.

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

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

Schema coverage is 86%, so baseline is 3. Description merely lists parameters already detailed in schema, with minimal extra context (e.g., code matching example, sort defaults). No significant added meaning beyond 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?

Description clearly states it searches for FHIR resources, specifies supported FHIR versions (R4 and R6), lists key parameters, and mentions the return type (paginated, redacted Bundle). This distinguishes it from siblings like fhir_read (single resource) and fhir_lastn.

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 implicitly suggests it is the general search tool but does not explicitly state when to use it versus alternatives. No 'when not to use' or exclusions provided, though sibling names offer some 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 indicate readOnlyHint=false and destructiveHint=false. The description adds that the tool returns 'created resource IDs and a ready-to-use step_up_token', providing behavioral details beyond annotations. It does not specify idempotency or overwrite behavior, but the context is sufficient for a non-destructive seeding 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: the first states the action and content, the second advises when to use it and what it returns. Every word is purposeful, with no superfluous content.

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

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

For a 1-parameter, non-nested tool with no output schema, the description covers the purpose, usage context, and return values (resource IDs and step_up_token), providing complete information for an AI agent 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?

The input schema provides 100% coverage for the single optional parameter (tenant_id) with a description and default. The description's mention of 'Seed a tenant' aligns with the parameter, adding minimal extra value. A baseline of 3 is justified, but the clarity of the default earns a 4.

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 ('Seed') and resource ('tenant with realistic Patient + Observations + Condition bundle'), clearly distinguishing it from sibling tools like fhir_commit_write or fhir_read, which handle general operations.

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 states when to use the tool ('at the start of a demo session'), providing clear context. It does not enumerate alternatives or when not to use it, but the purpose is narrow enough that no exclusion is needed.

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 readOnly hint. Description adds behavioral detail: follows standard $stats operation, limited to valueQuantity, and filter capabilities. Does not describe response format but overall context is sufficient.

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 covering purpose, standard compliance, limitation, and filters. No redundant information; highly 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 the tool's simplicity and absence of output schema, description covers essential aspects. Could mention response aggregation type or limits, but not necessary 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?

Parameter descriptions in schema are already detailed (examples for code and patient). Tool description only briefly restates filtering. With 100% schema coverage, description adds little beyond 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?

Description clearly states it computes statistics (count, min, max, mean) over numeric Observation values. Specifies the FHIR standard ($stats) and resource type. Distinguishes from sibling tools like fhir_search or fhir_read by its specific aggregative 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?

Mentions FHIR standard, only supports valueQuantity, and filter options (patient/code). Provides clear conditions but lacks explicit when-not-to-use or comparison to alternative tools like fhir_search with aggregations.

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 context about R6 normative status and discovery purpose, enhancing understanding 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?

Three sentences: defines purpose, provides background, reiterates use. Minor redundancy but overall concise and 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?

Simple tool but lacks description of return value (list of topic definitions). No output schema, so description should compensate.

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?

Input schema has no parameters, so description does not need to explain any. Baseline for 0 parameters is 4.

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 verb 'List' and resource 'SubscriptionTopics'. Distinguishes purpose as discovering available subscription topics for events. However, does not explicitly differentiate from sibling tools like 'fhir_search' or 'fhir_read'.

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?

Implied usage: agents use this to discover events they can subscribe to. No explicit guidance on when not to use or alternatives 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 declare readOnlyHint=true and destructiveHint=false. Description adds that the return type is OperationOutcome, confirming a safe, read-only validation.

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?

Single sentence, front-loaded with key action, no redundancy. Perfectly 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 no output schema, description mentions OperationOutcome return. Low complexity; annotations cover safety. Could add more detail on structural rules scope, but 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?

Schema parameter description is adequate (100% coverage), but tool description adds context about FHIR R6 and structural rules, enhancing meaning beyond the schema field.

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 tool validates a FHIR R6 resource against structural rules and returns OperationOutcome. Distinguishable from siblings 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?

Implies usage for validating proposed resources before committing, but no explicit when-to-use or alternatives among siblings (e.g., 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?

Description adds write-tier and step-up context beyond annotations (destructiveHint=true). Explains that dry_run=true avoids actual writing, clarifying safe usage. 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?

Two sentences front-loaded with key purpose and immediate usage condition. No extraneous content.

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

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

Covers main purpose, write behavior, and dry_run condition. Absence of output schema is mitigated by mentioning 'transaction Bundle'. Missing details on return structure are acceptable given schema covers inputs well.

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?

Input schema has 100% description coverage, so baseline is 3. Description mentions dry_run behavior but doesn't add significant new detail beyond 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?

Description clearly states 'extract FHIR resources from a completed QuestionnaireResponse into a transaction Bundle', identifying specific verb (extract) and resource (QuestionnaireResponse). Distinguished from sibling 'questionnaire_populate' which fills rather than extracts.

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

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

Provides explicit guidance: 'Write tier; requires step-up unless dry_run=true'. Indicates when to use write vs preview mode, and hints at permissions needed. No explicit when-not-to-use or sibling comparison.

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 context beyond annotations: it specifies 'SDC $populate', declares it as a 'Read tier' operation, and notes token minting for non-public tenants. This supplements the readOnlyHint=true annotation 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?

The description is concise (two sentences) and front-loaded with the core purpose. Every sentence adds value with no redundant information.

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

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

The description covers the tool's main function, side effect (token minting), and return type (QuestionnaireResponse). While it does not elaborate on pagination or error states, the annotations and schema provide sufficient completeness for a read operation.

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 does not provide additional detail beyond what the input schema already covers for each 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?

The description clearly states the verb 'pre-fill', the resource 'Questionnaire', and the target 'subject'. It distinguishes from sibling tools like questionnaire_extract, which likely performs the inverse operation.

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 does not explicitly state when to use this tool versus alternatives. It mentions 'Read tier' and token minting, but no direct comparison with siblings like questionnaire_extract.

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 annotations (readOnlyHint, destructiveHint), description adds that reads are PHI-redacted and audit-logged server-side, and returns compact results. 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, zero waste. Front-loaded with purpose and compatibility, then query format, then return characteristics. 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?

For a single-parameter search tool with no output schema, description covers query format, return structure, and behavioral notes. Missing pagination/error info, but adequate given simplicity.

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 100% for single parameter. Description adds format examples (e.g., 'Observation?code=4548-4'), clarifying acceptable FHIR search strings beyond schema's generic 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?

Description clearly states it searches FHIR records with compatibility note. Provides examples. Does not explicitly differentiate from sibling fhir_search, but adds context of compact results and PHI-redaction.

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?

Implied usage with ChatGPT connector, but no explicit when-to-use or alternatives. Sibling fhir_search exists but no guidance on choosing between them.

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?

Description discloses that the tool writes (not read-only), performs client-side encryption, uploads ciphertext, and requires a step-up token. It adds significant detail beyond annotations, such as consent and security constraints.

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?

Description is well-structured with purpose first, then process, then warnings. At 4 sentences, it is fairly concise but could be slightly tighter. Good front-loading of key information.

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

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

The description adequately explains the complex workflow (fetch, encrypt, upload, return) and lists all three return values. It covers security and consent. No output schema exists, but the description sufficiently fills that gap.

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 description does not add meaningfully beyond what the schema already provides for each parameter (e.g., label length, profile enum, expires default). 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?

The description clearly states the verb 'Generate', the resource 'SMART Health Link', and the purpose 'sharing the patient's record with a clinic'. It distinguishes itself from the listed sibling tools, none of which involve SHL generation.

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 provides explicit guidance: always get patient consent, deliver manage link only to patient, and mentions step-up token requirement. It lacks explicit alternatives but given the sibling list, no other SHL tool exists, making the guidance 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?

Annotations already indicate readOnlyHint=true and destructiveHint=false. Description adds behavioral context: it surveys all sources at once and returns specific data. 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?

Two sentences, front-loaded with purpose, followed by usage scenario. 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?

No output schema, but description explains return values (status and record counts). Sufficient for a simple, parameterless 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?

No parameters in input schema, so no need for additional param info. Baseline score of 4 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?

The description uses a specific verb ('Survey') and resource ('all connected health data sources'), lists example sources, and clearly states what it returns (connection status and record counts). It distinguishes from siblings like wearables_sync_status by focusing on all sources.

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

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

Explicitly states when to use: 'when the patient asks what's connected or to check for data across services.' Does not mention when not to use, but the context is clear enough for an agent to decide.

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, so the description adds value by detailing the returned fields (last sync time, observation count, status) and mentioning the UI URI. It does not contradict 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 two sentences, front-loaded with purpose and specific details. Every sentence earns its place with no redundancy.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers purpose, usage, return information, and integration with FHIR and UI. It is complete.

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

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

Schema coverage is 100% for the single parameter tenant_id, which already describes its default behavior. The description adds no additional parameter meaning, so 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?

The description clearly states the tool lists wearable connections for a tenant with specific brands, last sync time, observation count, and status. It distinguishes from siblings like fhir_search by noting that data flows into HealthClaw as FHIR Observations retrievable via that 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 tells when to use: 'Use this to tell a patient what's connected, when data last arrived, and surface a connection-management UI.' It provides clear context but does not explicitly mention when not to use or suggest alternatives.

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