Health Gorilla MCP by usefulapi

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

Annotations already supply destructiveHint=true, and 'State-changing' plus the POST /Patient mapping corroborate the mutation. The description usefully discloses that only a 'minimal FHIR R4 Patient resource' is built from the given args, but omits what happens on duplicate MRNs, idempotency, or permission requirements.

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

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

Three tight sentences, front-loaded with the core purpose, then the API mapping, then the state-changing caveat. Nothing is 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 create tool with no output schema, the description never says what comes back (e.g., the new patient's FHIR id), which the agent likely needs for follow-up calls. The mutation semantics are covered by the annotation, but the return contract is left unspecified.

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 every parameter is documented in the schema and the baseline is 3. The phrase 'built from the given args' loosely indicates the args map to FHIR Patient fields, but adds no format or mapping 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 ('Registers a NEW patient record in your Health Gorilla tenant') and pins the underlying operation to 'FHIR: POST /Patient'. The capitalized 'NEW' and 'State-changing' implicitly separate it from the read-oriented siblings (get_patient, find_patients), but no sibling is named explicitly.

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

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

There is no explicit when-to-use guidance and no mention of alternatives. Given siblings like find_patients and get_patient, the description should tell the agent whether to check for an existing record first, but it does not.

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, and the description reinforces that with the concrete GET URL shape and an escape-hatch framing. It does not discuss pagination behavior, result limits, error handling, or auth scoping beyond the '_count' hint in the example, so it adds only modest context over 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?

Three short sentences, front-loaded with the 'Escape hatch' role, then the concrete URL form, then the routing rule. Every sentence carries information and nothing is 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 two-parameter read tool with no output schema and annotations covering safety, the description supplies enough to invoke it correctly (URL form, example, when to reach for it). It omits any mention of pagination or response shape, which a generic search tool could reasonably note.

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 both parameters are already documented individually. The description's composed example (resource_type='Observation', query='patient=123&category=laboratory&_count=5') shows how the two combine into a real query string, adding meaning beyond the isolated schema descriptions.

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

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

The description states a specific verb (search) and object (arbitrary FHIR resource via GET /{resource_type}?{query}) and positions it as an escape hatch distinct from the dedicated list/get siblings. An agent can immediately tell this apart from healthgorilla_list_observations or healthgorilla_find_patients.

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

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

It explicitly says 'Use when a dedicated tool does not cover your query,' which gives clear context for selection over the many dedicated siblings. It never names which sibling to prefer in a given case and states no explicit exclusions, so it falls just short of a 5.

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

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

Annotations only declare readOnlyHint=true, so the description carries most of the behavioral burden. It adds the raw FHIR endpoint (GET /Patient?given=&family=&birthdate=&identifier=), the response shape (a FHIR searchset Bundle), and the downstream usage pattern, which go meaningfully beyond the annotation. It omits pagination/result-count behavior despite exposing _count.

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 sentences, front-loaded with purpose and with no filler. The FHIR endpoint line slightly restates the demographic parameters already in the schema, which keeps it just short of ideal.

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

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

With no output schema, the description correctly notes the return value is a searchset Bundle, and the parameter set is fully documented in the schema. The remaining gap is pagination behavior for _count and handling of zero/many matches, minor for a low-complexity search tool.

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

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

Schema description coverage is 100%, so every parameter is already documented, and the FHIR query string simply echoes given/family/birthdate/identifier. It does not explain the 'system|value' format edge case or the _count parameter, 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?

States a specific verb ('Search') and resource ('patients') plus the scope ('by demographics'), which clearly separates it from id-based siblings like get_patient and from the list_* family. An agent can identify this as the demographic lookup entry point without opening the schema.

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

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

The closing line 'Use the returned Patient id with the other tools' implies the intended chaining, which is useful. However, it never says when to prefer this over the sibling healthgorilla_fhir_search for raw FHIR queries, and there are no exclusions or prerequisites stated.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely useful return-behavior context — the payload may be a FHIR Binary JSON resource, XML C-CDA, or base64, and is returned as-is (raw text if not JSON) — which tells the agent how to parse the result.

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 and no filler. The middle FHIR-path sentence is mildly redundant given the name and title, but it usefully maps to the canonical API route.

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

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

For a one-parameter read tool with no output schema, the description covers the operation, the identifier source, and the possible response encodings. Minor omissions are error/not-found behavior, but nothing critical to 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 single binary_id parameter is documented in the schema as coming from a DocumentReference. The description adds no extra syntax or sourcing detail, 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 — 'Retrieve raw document content by Binary id' — plus the underlying FHIR endpoint GET /Binary/{id}. The 'by Binary id' scoping implicitly separates it from list tools like healthgorilla_list_documents, but no sibling is named explicitly.

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

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

Usage is only implied: an agent can infer this is the follow-up call after discovering a Binary reference, but the description never states when to prefer this over healthgorilla_list_documents or healthgorilla_get_patient_everything, nor any 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?

readOnlyHint=true already declares this is a safe read, so the description's added value is the disclosure that the response is a FHIR searchset Bundle rather than a single Coverage resource — meaningful since no output schema exists. It still omits pagination, empty-result behavior, and auth requirements, so it adds context but not rich behavioral detail.

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 zero redundancy, front-loaded with the human-readable purpose before the FHIR implementation detail. Every sentence 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 single-parameter read-only tool, the description covers purpose, endpoint, and return shape (searchset Bundle), which partly compensates for the absence of an output schema. Missing only pagination and result-count behavior to be fully 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 there is only one parameter (patient_id, documented as 'Patient resource id.'). The description's 'patient={id}' simply restates the schema, adding no format or source-of-id guidance, 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 insurance coverage') and pins the underlying FHIR operation (GET /Coverage?patient={id}), so the agent knows exactly what domain data is returned. It does not explicitly differentiate itself from siblings such as healthgorilla_fhir_search or healthgorilla_list_allergies, but the resource is inherently distinct enough to route correctly.

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, no prerequisites, and never mentions that healthgorilla_fhir_search could be an alternative way to query Coverage. The agent must infer usage purely from the resource 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?

The readOnlyHint=true annotation already tells the agent this is a safe, non-mutating read, so the bar is lower. The description adds the underlying FHIR endpoint and the return type, modest useful context, but says nothing about auth requirements, error behavior for unknown ids, or cost. Adequate 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?

Three short, front-loaded sentences with zero waste: action, endpoint, and return shape. Nothing repetitive 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 one-parameter read tool, the description covers the operation, the FHIR route, and the return shape, which compensates for the absent output schema. Only minor gaps (error handling, whether a Patient 360 enrichment exists) remain.

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

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

Schema description coverage is 100% and the single parameter patient_id is fully documented in the schema. The description's 'by id' adds no meaning beyond 'Health Gorilla Patient resource id', 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 (Read) and resource (a single patient by id), and the FHIR endpoint mapping (GET /Patient/{id}) reinforces exactly what is fetched. The singular 'single patient' implicitly distinguishes it from find_patients/search siblings, though it doesn't name them 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 implied by 'by id' – call this when you already have a patient id – but there is no explicit when-to-use guidance, no mention of alternatives like find_patients or get_patient_everything, and no prerequisites stated.

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

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

The readOnlyHint=true annotation already establishes this is a safe read, so the bar is lower. The description adds that the result is a whole-patient Bundle that can be date-scoped and paginated, which is useful context, but it omits any warning about payload size or cost typical of $everything operations.

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 verb, resource, and return type, then the exact FHIR path, then the optional modifiers. Every sentence carries information with no filler.

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

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

With no output schema, the description correctly tells the agent the return is a FHIR Bundle, and it covers optional scoping/paging. It leaves a minor gap in not flagging the potentially large volume of a $everything response, but nothing needed to invoke 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 description coverage is 100%, so patient_id, _since, and _count are already fully documented in the schema. The description merely names _since and _count without adding format or interaction details beyond what the schema provides, matching the baseline 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?

States a specific verb (fetch), resource (patient's comprehensive record), and return shape (FHIR Bundle), plus the exact FHIR operation GET /Patient/{id}/$everything. The word 'comprehensive' implicitly separates it from the single-resource get_patient and the granular list_* siblings.

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

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

The description explains how to scope (_since) and page (_count) results, but never says when to choose this over siblings like healthgorilla_get_patient or the list_* tools. Usage is only implied by the word 'comprehensive' rather than stated with an exclusion or alternative.

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 value beyond annotations by disclosing the underlying FHIR call and the return shape (a searchset Bundle), which is genuinely useful since no output schema exists. However, it says nothing about pagination behavior even though a _count parameter exists.

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

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

Three short sentences, zero filler, and the core purpose is front-loaded ahead of the implementation detail. 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-only list tool with full schema coverage and no output schema, the description supplies the return type (FHIR searchset Bundle) and the endpoint, which is enough for an agent to call it correctly. The only minor gap is pagination behavior tied to the _count parameter.

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

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

Schema description coverage is 100%, so both patient_id and _count are already documented in the schema. The description's `patient={id}` notation mildly reinforces the required parameter, but adds no format or syntax detail beyond the schema, so the baseline of 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 (List) and resource (a patient's allergies/intolerances), and the FHIR endpoint pinpoints the exact operation. This is unambiguous against siblings like list_conditions, list_medications, and list_immunizations, which the agent can distinguish by resource 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 narrow resource scope, but there is no explicit when-to-use guidance, no mention of when a broader sibling such as get_patient_everything or start_patient360_query would be preferable, and no prerequisites stated. Adequate but with clear gaps.

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. The description adds useful context by disclosing the FHIR endpoint shape and that the result is a searchset Bundle, but it says nothing about pagination behavior (beyond the _count param) or whether results are filtered by the caller's access scope.

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, zero filler: purpose first, then the underlying FHIR call, then the return shape. Every sentence earns its place and the most important information is front-loaded.

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

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

With no output schema, the description correctly compensates by naming the return type (FHIR searchset Bundle), and all parameters are documented in the schema. The main omission is pagination/next-page guidance for a list endpoint, but the definition is otherwise sufficient to call the tool correctly.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema (including _count and category examples). The description only echoes the patient identifier via the endpoint template, adding no meaning beyond the structured fields — 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 maps it to the underlying FHIR operation, so an agent knows exactly what this retrieves. It does not explicitly differentiate from siblings like get_patient_everything or fhir_search, which also surface clinical resources, so it stops short of a 5.

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

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

The description gives no when-to-use guidance: it does not say when to prefer this over healthgorilla_get_patient_everything, healthgorilla_fhir_search, or healthgorilla_get_patient, all of which can return overlapping data. No exclusions or prerequisites (e.g., auth or patient-context requirements) are mentioned.

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 the description adds the concrete FHIR call and return shape (searchset Bundle), which is useful context. However, it says nothing about pagination behavior, result ordering, or authorization requirements needed to retrieve a patient's records.

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 fragments with zero waste: what it lists, the mapping to the underlying FHIR call, and the return type. Front-loaded so the purpose is readable at a glance.

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 noting the FHIR searchset Bundle return is a genuine and necessary addition. The only minor gap is that pagination and how _count interacts with the returned Bundle are left to 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 patient_id, _count, and category are fully documented in the schema. The description adds no format or syntax detail beyond what the schema already provides, 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 (List) plus resource (diagnostic reports) and even disambiguates with examples (lab panels, imaging). This clearly separates it from siblings like list_observations or list_documents. It stops short of explicitly naming an alternative tool, but the resource itself is unambiguous.

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

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

The description gives no when-to-use/when-not-to-use guidance and never references alternatives among the many list_* siblings. Usage is only implied by the resource being listed.

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 still adds real behavioral context: the entries are references (not the document bodies) that point at Binary objects, and it surfaces the FHIR resource mapping. It does not mention pagination behavior beyond the schema's _count.

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

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

Three sentences, front-loaded with the purpose, then the FHIR mapping, then the workflow pointer. No filler; each sentence carries distinct value for the caller.

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 and read-only annotations, the description does the important work of explaining that results are references pointing to Binary resources, which is the key thing an agent needs to act on results. It stops short of describing entry fields or pagination specifics.

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 only the endpoint form GET /DocumentReference?patient={id}, which lightly reinforces how patient_id is used but adds little beyond the schema. 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 document references) and gives concrete examples (C-CDA, notes) plus the underlying FHIR resource. It is immediately distinguishable from siblings like list_medications or list_conditions, and it points at the follow-up tool get_binary.

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 establishes the workflow context by naming healthgorilla_get_binary as the tool to fetch each referenced Binary, so the agent understands the list-then-fetch pattern. It lacks an explicit 'when not to use this' or comparison against overlapping siblings such as get_patient_everything, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real context beyond that: the REST/FHIR mapping (GET /Immunization?patient={id}) and the return shape (a searchset Bundle). It stops short of describing pagination behavior or auth requirements, so it is useful 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?

Three short sentences with no waste: purpose first, then the FHIR mapping, then the return type. Every sentence carries information an agent can use.

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 discloses that a FHIR searchset Bundle is returned, and the two-parameter surface is simple. It could say more about paging through large result sets, but for a read-only list tool it is nearly complete.

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

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

Schema description coverage is 100%, so both patient_id and _count are already documented in the schema. The description only echoes the patient={id} binding and adds no semantics for _count or paging limits, 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 scoped to a patient ('List a patient's immunizations') and even names the underlying FHIR interaction, so it is unambiguous. It does not explicitly distinguish itself from siblings like healthgorilla_get_patient_everything, which may also carry immunization data, but the resource name makes the target obvious.

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 statement of when to use this tool versus alternatives such as healthgorilla_fhir_search or healthgorilla_get_patient_everything, and no prerequisites or exclusions are given. The only usage signal is the patient scoping implied by the 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 establishes the safety profile, and the description adds value beyond that by disclosing the return shape ('FHIR searchset Bundle') and the exact upstream FHIR endpoint, which clarifies result structure and pagination semantics. It still does not state rate limits, auth requirements, or how paging interacts with _count.

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: purpose first, then endpoint, then return type. No filler, and the most important information is front-loaded.

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

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

With no output schema, the description usefully names the return container (searchset Bundle), and parameters are fully covered by the schema, so an agent has what it needs. Only the paging behaviour across the Bundle entries is left implicit.

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

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

Schema description coverage is 100%, so all three parameters (_count, status, patient_id) are already documented in the schema. The description only restates the patient scoping via the FHIR path and adds no new 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 medication requests/prescriptions') and even pins the upstream FHIR call (GET /MedicationRequest?patient={id}), so the agent knows exactly what is retrieved. It does not, however, distinguish itself from siblings like healthgorilla_fhir_search or healthgorilla_get_patient_everything that could also surface medication data.

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

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

Usage is implied by the resource and the required patient_id, so an agent will infer 'call this to see a patient's medications'. There is no explicit when-to-use statement, no exclusions, and no pointer to an alternative tool for broader searches.

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 genuinely useful context beyond that: the underlying FHIR call and the return shape ('a FHIR searchset Bundle'), which tells the agent what to expect back. It omits pagination/rate-limit behavior, but for a read-only list this is solid.

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

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

Three short sentences, front-loaded with the primary action before the endpoint, filters, and return type. Every sentence carries information and nothing is 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?

With no output schema, the description correctly compensates by naming the return type (FHIR searchset Bundle) and the filter options. Pagination is only covered via the _count schema field, not the description, which is the only minor gap for a 5-parameter search tool.

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

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

Schema description coverage is 100%, so the schema already documents each parameter with examples and FHIR semantics. The description restates the filter axes (category, LOINC code, date) but adds no syntax or format detail beyond what the schema provides, 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?

The description uses a specific verb+resource ('List a patient's observations'), scopes it to a patient, and names concrete examples (labs, vitals) plus the FHIR endpoint. This clearly distinguishes it from siblings like list_allergies, list_conditions, and list_diagnostic_reports.

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 lists the available filter dimensions (category, LOINC code, date), which implies when the tool is useful, but never states when to prefer it over alternatives such as healthgorilla_fhir_search or healthgorilla_get_patient_everything. No exclusions or prerequisite guidance are given.

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

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

Annotations declare readOnlyHint=true, and the description adds real behavioral detail beyond that: HTTP 202 means still processing, 200 means done, plus the retrieval metric names returned on completion. It does not mention polling interval, timeout, or URL expiry, which would matter for a poll loop.

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 compact sentences, front-loaded with the action, then the workflow link, then the status-code semantics; 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?

With no output schema, the description steps in to describe the { status, body } return shape and the metrics present on completion, which is what an agent needs to branch on. Missing only operational guidance such as how often or how long to keep polling.

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 sole parameter is fully documented in the schema. The description restates its origin (returned by the start query) but adds no format or usage nuance beyond what the schema already provides, 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 ('Poll') plus the resource (a RequestResult URL), and names the producer tool healthgorilla_start_patient360_query so it is clearly distinguished from the start/query siblings.

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

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

Explains the workflow context: use it against the URL returned by healthgorilla_start_patient360_query, and gives the decision rule for interpreting 202 vs 200. It does not state a retry cadence or when to give up polling, so it falls short of full when/when-not 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, and the description adds substantial context beyond that: it is asynchronous, it is state-changing (consistent with the annotation), it writes external documents into the tenant, and the result arrives via the Location header rather than inline. Missing permission/consent prerequisites or rate-limit notes, but the behavioral profile is well disclosed.

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: purpose, wire-level mechanics, and the required follow-up call. Front-loaded with the operation's nature and scope, and every clause carries information an agent needs.

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

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

For an async kickoff tool with no output schema, the description covers the essentials: what it starts, where the poll URL comes from (Location header), and which sibling continues the flow. It stops short of describing what document types are imported or any network-specific prerequisites, but nothing blocking is omitted.

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

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

Schema description coverage is 100% and the single parameter is already documented as the Patient resource id. The description only echoes this via the FHIR template 'patient={id}', adding no new format or constraint detail, 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 (initiates), resource (national-network records retrieval across CommonWell/Carequality/QHINs), and outcome (imports external documents into your tenant). This clearly distinguishes it from local-read siblings like healthgorilla_get_patient_everything or healthgorilla_list_documents.

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 healthgorilla_poll_query_status for the follow-up step and clarifies this tool only kicks off the query, which is critical for an async operation. It does not, however, say when to prefer this over alternatives such as get_patient_everything, so sibling selection is only implied.

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