health-gorilla

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

Annotations only declare destructiveHint=true, so the description usefully adds the FHIR mapping (POST /Patient) and that the resource is 'minimal' — implying optional fields not supplied are omitted rather than defaulted. It does not cover auth requirements, duplicate handling, or what is returned, but with annotations carrying the mutation signal this is above baseline.

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

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

Three tight sentences with the action and tenant front-loaded, then the protocol mapping, then the state-changing warning. No filler, every clause carries 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 9-parameter create call with no output schema and only a destructiveHint annotation, the description leaves notable gaps: whether the created patient's id is returned for later retrieval, how duplicates are handled, and any required scopes. What is present is accurate and adequate, but not 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% and each of the 9 params is documented in the schema, so the baseline is 3. The description adds only the aggregate note that args are assembled into a minimal Patient resource; it adds no per-parameter 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?

States a specific verb and resource ('Registers a NEW patient record in your Health Gorilla tenant') and pins the underlying operation (FHIR POST /Patient), clearly separating it from siblings like get_patient, find_patients, and fhir_search. The uppercase NEW signals creation rather than retrieval.

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

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

Usage is implied by the verb, but the description never says when to choose this over healthgorilla_find_patients (e.g., to check for an existing/duplicate patient first) or what prerequisites exist. No explicit alternatives or exclusions are given.

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

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

Annotations only declare readOnlyHint=true; the description confirms the read-only GET shape and adds genuinely useful behavior context: the query is passed through raw and untyped, so the agent must supply valid FHIR syntax itself. It omits error behavior for unsupported resource types and result pagination/size 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?

Three short sentences, front-loaded with the 'Escape hatch' role, then the call shape, then the routing rule. Zero filler; 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 2-parameter, annotation-light, no-output-schema tool, the definition covers purpose, call format, and routing to dedicated tools. It would be fully complete with a note on unsupported resource types or pagination limits, but nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a concrete composed example ('Observation' with 'patient=123&category=laboratory&_count=5') showing how resource_type and a multi-clause query combine in practice, which goes slightly beyond the schema's simpler example.

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 scope: 'run an arbitrary FHIR search' against 'GET /{resource_type}?{query}'. The 'Escape hatch' framing immediately distinguishes it from the dedicated list_* and get_* siblings that cover specific resources.

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 to use it 'when a dedicated tool does not cover your query', which names the alternative class of tools and the selecting condition. It stops short of enumerating edge cases (e.g. what to do when a dedicated tool exists but lacks a filter) or when-not-to-use beyond that single rule.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the description only needs to add context. It does add the return shape ("a FHIR searchset Bundle") and the downstream id-reuse pattern, which is genuinely useful, but says nothing about pagination behavior, empty results, or matching semantics despite the paging parameter.

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

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

Three short, front-loaded sentences: purpose first, endpoint second, downstream usage third. Every sentence carries information, though the FHIR query-string restatement of parameters is partly redundant with the schema.

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

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

For a read-only search tool with full schema coverage and no output schema, the description supplies the one thing the schema cannot: the return type (searchset Bundle) and what to do with the result. Only pagination handling and no-match behavior are unaddressed.

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 all five parameters (given, family, birthdate, identifier, _count) are already documented with types, patterns, and constraints. The description merely echoes four of them in the FHIR query string and adds no matching logic or format detail 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?

States a specific verb and resource ("Search for patients by demographics") and pins it to the concrete FHIR operation (GET /Patient?given=&family=&birthdate=&identifier=). It implicitly distinguishes itself from the retrieval siblings (get_patient, get_patient_everything) by noting the returned id feeds other tools, but never names an alternative explicitly.

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

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

Usage is only implied: the demographics-based search and the note that "Use the returned Patient id with the other tools" suggest this is the entry point when you lack an id. There is no explicit statement of when to prefer this over get_patient or fhir_search, nor any prerequisite or exclusion 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?

readOnlyHint=true already covers the safety profile, and the description adds meaningful context beyond that: content may be a FHIR Binary JSON resource, XML C-CDA, or base64, and is returned as-is with raw text when not JSON. This return-shape disclosure is valuable, especially given there is no output schema.

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

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

Three tight sentences, front-loaded with the verb and resource, followed by the FHIR endpoint and then the return-format caveat. No sentence is redundant and nothing is buried.

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

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

For a single-parameter read tool with no output schema, the description supplies the essential missing piece: what the returned payload can look like (JSON, C-CDA XML, or base64, returned as-is). This makes the definition self-sufficient for correct invocation, short of explicit usage routing.

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 one parameter at 100% schema coverage, the schema already documents binary_id fully (including its origin in a DocumentReference). The description's 'by Binary id' adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Retrieve) and resource (raw document content) keyed by Binary id, plus the underlying FHIR path GET /Binary/{id}. It is clearly distinct from the sibling list_documents operation, though it does not explicitly contrast itself with any sibling by name.

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 you need a Binary id, and the schema notes it comes from a DocumentReference, but it gives no explicit when-to-use guidance, no when-not conditions, and does not route the agent to or away from alternatives such as list_documents.

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 safety is covered. The description adds genuine behavioral value the annotations do not supply: the underlying FHIR call shape and the return contract ('FHIR searchset Bundle'), letting the agent plan for the response envelope.

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

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

Three terse sentences, front-loaded with the action and immediately followed by the endpoint and return type. Nothing redundant or padded.

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 tool with no output schema, the description supplies the two things missing from structured fields: the FHIR endpoint and the Bundle return shape. Only broader routing guidance (vs. get_patient_everything) is absent.

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

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

Schema coverage is 100% with a single documented patient_id, so the schema carries the parameter meaning entirely. The description's 'patient={id}' restates the schema without adding format or lookup semantics, so baseline 3 applies.

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

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

States a specific verb and resource ('List a patient's insurance coverage') and pins it to a concrete endpoint. It is clearly distinguishable from the list_allergies/list_conditions siblings, though it does not explicitly address overlap with healthgorilla_get_patient_everything, which may also surface coverage.

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 when-to-use or when-not-to-use guidance, no prerequisites, and no mention of alternatives for retrieving coverage data. The agent must infer that this is the right call whenever coverage 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 declare readOnlyHint=true, so safety is covered; the description adds value by disclosing the underlying FHIR call (GET /Patient/{id}) and the return type (a FHIR Patient resource). With no output schema present, that return-type disclosure is genuinely useful context.

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

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

Three tight sentences with the core action front-loaded, followed by the FHIR mapping and return type. No padding 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 single-parameter, read-only, no-output-schema tool, this covers action, scope, endpoint, and return type adequately. It could be stronger by contrasting with get_patient_everything, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100% and the sole parameter patient_id is fully documented in the schema, so the schema carries the load. The description's 'by id' phrasing reinforces but does not extend that meaning, making the baseline 3 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?

States a specific verb (read) and resource (a single patient) scoped to retrieval by id, which cleanly separates it from search-style siblings like healthgorilla_find_patients and healthgorilla_fhir_search. It does not name a sibling explicitly, but 'single ... by id' implies the distinction.

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

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

Usage is implied (fetch one known patient record), but the description offers no explicit when-to-use or when-not guidance against close alternatives such as healthgorilla_get_patient_everything (full clinical bundle) or healthgorilla_find_patients (lookup without an id).

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?

readOnlyHint=true already declares the safe-read profile, so the bar is lower. The description adds useful context by naming the return format (FHIR Bundle) and the underlying $everything operation, but it does not disclose payload size expectations, pagination behavior beyond _count, or any 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?

Three short sentences with the core action front-loaded, followed by the endpoint and optional scoping. Every sentence is useful, though the explicit FHIR path is slightly redundant with the tool name and endpoint convention.

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 no output schema, the description adequately covers the return type (FHIR Bundle) and the optional scoping controls. It could say more about what 'comprehensive' includes or how paging links work, but the essential call context is present.

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

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

Schema description coverage is 100%, so the schema fully documents patient_id, _since, and _count. The description repeats the existence of _since and _count but adds no format, syntax, or edge-case detail beyond what the schema already provides, making the baseline 3 correct.

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

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

States a specific verb and resource ('Fetch the comprehensive record for a patient as a FHIR Bundle') and adds the exact FHIR endpoint, so it is distinguishable from simpler siblings like get_patient or list_* by scope. However, it never explicitly names an alternative, so it falls short of the sibling-differentiating 5.

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

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

The description gives no when-to-use guidance or alternatives; it only notes optional scoping parameters. An agent must infer that this is the comprehensive read path versus get_patient or start_patient360_query, which is exactly the kind of inference the rubric penalizes.

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?

readOnlyHint=true already declares the safety profile, so the description only needs to add context. It does add value by disclosing the exact FHIR path and that the result is a FHIR searchset Bundle, but it says nothing about pagination behavior, error cases, or authentication needs.

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

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

Three short, front-loaded sentences with no filler: purpose first, then the concrete FHIR mapping, then the return shape. Every sentence carries information the agent can act on.

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 low-complexity, single-required-param read tool, the description covers purpose, API mapping, and return type even though no output schema exists. It does not explain how multi-page searchset Bundles should be traversed, which is the only real 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 both parameters are documented in the schema, so the baseline is 3. The description only restates patient={id} via the URL template and adds no format, validation, or paging 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?

States a specific verb and resource ('List a patient's allergies/intolerances') and even pins the exact FHIR interaction (GET /AllergyIntolerance?patient={id}), making it clearly distinguishable from list_conditions, list_medications, and other list_* siblings. It stops short of explicitly routing the agent away from any sibling, but the resource name is unambiguous.

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

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

Usage is only implied by the name and endpoint; there is no stated when-to-use, when-not-to-use, or comparison to alternatives such as get_patient_everything or fhir_search. An agent can infer the intended case (fetching allergy data for a known patient id) but the description adds nothing explicit.

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, so safety is already covered; the description goes further by naming the underlying FHIR endpoint and the response shape ('FHIR searchset Bundle'), which tells the agent to expect paged Bundle semantics. It stops short of stating auth requirements, hard result limits, or how paging links are followed.

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

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

Three short sentences with no filler; the purpose is front-loaded, followed by the endpoint and return type in priority order. Every sentence carries distinct 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 simple read-only list tool with full schema coverage and no output schema, the description covers purpose, endpoint, and return format adequately. The remaining gap is paging/category behavior, which the schema touches on only briefly.

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 all three parameters are already documented. The description only restates the patient filter via the FHIR template ('patient={id}') and adds nothing about category value semantics or _count paging behavior, so the baseline 3 applies.

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

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

States a specific verb and resource ('List a patient's conditions/problems') and pins the exact FHIR operation being proxied, so the agent knows precisely what it does. It does not, however, distinguish itself from siblings such as healthgorilla_fhir_search or healthgorilla_get_patient_everything, which could also surface conditions.

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

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

Usage is strongly implied by the name and the required patient_id, but there is no explicit when-to-use statement and no guidance on when to prefer this over healthgorilla_fhir_search or get_patient_everything. The FHIR path adds context but not decision 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, so the safety profile is covered, and the description still adds value by disclosing the underlying HTTP verb/path and the return shape ('FHIR searchset Bundle'), which is notable because no output schema exists. It does not expand on pagination behavior beyond the _count parameter, keeping it short of a 5.

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

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

Three short sentences with the resource and scope front-loaded, followed by the endpoint mapping and return type. No filler, no repetition of schema 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 simple read-only list tool with fully documented params, the definition covers purpose, scope, endpoint, and return container, compensating for the absent output schema. Only minor gaps remain (no pagination/traversal guidance, no mention of how results interrelate with other list_* siblings).

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%: patient_id, category (with LAB/RAD examples), and _count are all documented in the schema itself. The description adds only the {id} substitution hint via the FHIR path, which is marginal, so the baseline 3 applies.

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

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

States a specific verb and resource ('List a patient's diagnostic reports') and concretizes it with examples ('lab panels, imaging') plus the underlying FHIR operation. It does not explicitly contrast itself with adjacent siblings such as list_observations or list_documents, so an agent must infer the boundary from the resource name alone.

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

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

Usage is implied by the scoping to a single patient, but there is no explicit when-to-use, no when-not-to-use, and no mention of alternatives like healthgorilla_fhir_search or list_observations for related clinical data. The agent can infer the context but gets no routing 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, so safety is covered. The description adds real behavioral value beyond that: the FHIR resource path and the key insight that returned entries reference a separate Binary retrievable via get_binary. It omits pagination/rate/auth details, but for a read-only list tool this is solid additive context.

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

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

Three short, front-loaded sentences with zero waste: purpose, endpoint, and follow-up action in order of importance.

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, yet the description explains what each entry represents and how to fetch the actual document, which is the essential missing piece. It does not describe item-level fields or pagination behavior, leaving a minor gap for a tool with a fully documented input schema.

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

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

Schema description coverage is 100%, so the schema already documents patient_id, type, and _count. The description adds no syntax or format detail (e.g. LOINC system|value format) 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?

Specific verb+resource ('List a patient's document references') with examples (C-CDA, notes) and the underlying FHIR endpoint (GET /DocumentReference?patient={id}). This clearly distinguishes it from sibling list_* tools that target allergies, conditions, observations, etc.

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

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

Explicitly routes the agent to the natural follow-up tool: 'Each entry points at a Binary you can fetch with healthgorilla_get_binary,' establishing a two-step workflow. It does not state when-not-to-use or contrast with the sibling list_* tools for other resource types, so it stops short of full 5-level 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, so safety is covered. The description adds real value beyond that: the exact FHIR endpoint semantics and the return shape (a FHIR searchset Bundle), which tells the agent what to expect back.

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

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

Three tight sentences with no filler: purpose, endpoint, and return type, in that order. Everything is front-loaded and each 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?

With no output schema, the description usefully names the return type (FHIR searchset Bundle), and readOnlyHint covers the safety profile. For a simple two-parameter read tool this is nearly complete; only pagination/alternative selection is unaddressed.

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 both patient_id and _count are already documented in the schema, and the description adds no per-parameter detail. Baseline 3 applies when the schema does the heavy lifting.

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 (list a patient's immunizations) and even pins the underlying FHIR operation (GET /Immunization?patient={id}). The resource is naturally distinct from siblings like list_medications or list_conditions, though the description never explicitly names or contrasts with them.

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

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

There is no when-to-use or when-not-to-use guidance. Notably, the sibling healthgorilla_get_patient_everything likely also returns immunizations, yet the description gives no condition to choose between the targeted list and the aggregate call.

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

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

readOnlyHint=true already establishes this as a safe read. The description adds the useful return shape (a FHIR searchset Bundle) and the backing endpoint, but says nothing about pagination behavior, auth requirements, 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?

Two tightly packed sentences with the purpose front-loaded, followed by the FHIR endpoint and return type. 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 simple read-only list tool with annotations covering safety and a fully documented schema, this is nearly complete; it even names the return type. The main omission is pagination/bulk behavior, though _count is documented in the schema.

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

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

Schema description coverage is 100%, so all three parameters are documented in the schema itself. The description's 'patient={id}' simply restates the patient_id parameter and adds no format or syntax detail beyond the structured fields.

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 ('List') and resource ('patient's medication requests/prescriptions'), plus the underlying FHIR endpoint. The resource name distinguishes it implicitly from sibling list tools like list_allergies or list_conditions, though there is no explicit sibling callout.

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 when-to-use or when-not-to-use guidance is given. It does not indicate when an agent should prefer this over healthgorilla_get_patient_everything or healthgorilla_fhir_search, both of which could surface medication data. Usage is only inferable from the tool name.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds genuine value beyond that by disclosing the return shape ('a FHIR searchset Bundle'), which implies paged results. It does not mention pagination limits, _count behavior, or missing-patient handling, so it is solid but not rich.

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

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

Four short, front-loaded sentences: purpose, endpoint, filters, return type. No filler, no repetition, and the most decision-relevant information comes first.

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

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

There is no output schema, so the description usefully characterizes the return as a FHIR searchset Bundle, and the schema covers filter syntax and _count. The only real gap is guidance on result limits/paging behavior and relationship to the broader search siblings.

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 all five parameters are already documented in the schema, including prefix syntax for date and system|value for code. The description's filter list merely restates that coverage and adds no new syntax or constraint, so the baseline 3 applies.

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

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

States a specific verb and resource ('List a patient's observations') and immediately disambiguates with concrete content examples ('labs, vitals') plus the underlying FHIR path. This lets an agent separate it from siblings like list_conditions, list_medications, or list_diagnostic_reports without opening 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?

It names the available filters (category, LOINC code, date), which implies when the tool is the right choice, but never states alternatives or exclusions — e.g. when to prefer healthgorilla_fhir_search or healthgorilla_get_patient_everything over this targeted list. Usage is inferable but not guided.

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

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

Annotations only declare readOnlyHint=true; the description goes further by decoding the HTTP contract (202 = processing, 200 = done) and naming the return shape and metrics. That is meaningful behavior disclosure beyond the annotation, though retry/backoff expectations and error behavior are unstated.

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

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

Three short sentences, front-loaded with the action and the source tool, then the status-code semantics and return shape. Dense and free of filler, with only minor terseness in the final 'Returns { status, body }' line.

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

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

There is no output schema, so the description carries the return-value burden and does so by naming status, body, and the retrieval metrics. It is nearly complete for a one-parameter polling tool, missing only terminal error/timeout handling.

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 documents the single parameter as a Health Gorilla RequestResult URL. The description restates the same origin (returned by start_patient360_query) without adding format or constraint detail 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?

States a specific verb (poll) and resource (RequestResult query status) and explicitly ties the tool to the sibling that produces the URL, healthgorilla_start_patient360_query. An agent can distinguish it from the list_* and get_* siblings at a glance.

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

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

Makes the usage context explicit: this is the follow-up to healthgorilla_start_patient360_query, and the input is the URL that tool returns. It does not state when-not-to-use or a recommended polling cadence, so it stops short of full routing 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 only supply destructiveHint=true; the description adds substantial context beyond that: it is asynchronous, imports documents into the caller's tenant, is state-changing, requires a Prefer: respond-async header, and returns a Location poll URL. It does not describe rate limits, cost, or how much data gets imported, so it stops short of a 5.

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

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

Three tightly packed sentences, front-loaded with the operation and scope, then the technical mechanism, then the poll handoff. Every clause carries information; nothing is filler.

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

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

For an async, no-output-schema tool, the description covers the trigger, the mechanism, the return (poll URL) and the next step, which is what an agent needs. It could still say what document types or time range are retrieved, but the essentials are present.

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

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

Schema coverage is 100% and the single patient_id parameter is fully documented in the schema, so the schema already carries the burden. The description only restates the id as {id} in the FHIR path, adding no syntax or semantic detail. Baseline 3 applies.

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

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

States a specific verb (initiates) plus the exact resource and scope: an asynchronous national-network records retrieval across CommonWell/Carequality/QHINs that imports external documents. This is unmistakably distinct from siblings like healthgorilla_get_patient or healthgorilla_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?

Explicitly names the follow-up tool (healthgorilla_poll_query_status) and the poll URL to use, which tells the agent the workflow. It does not, however, state when to prefer this over alternatives like get_patient_everything, so the exclusion guidance is absent.

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