healthgorilla_list_documentsList a patient's document references (C-CDA, notes, etc). FHIR: GET /DocumentReference?patient={id}. Each entry points at a Binary you can fetch with healthgorilla_get_binary.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Document type code (e.g. LOINC), optionally system|value. | |
| _count | No | FHIR _count — max results per page. | |
| patient_id | Yes | Patient resource id. |
Changes observed during successful MCP inspections.
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"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.
Add one secure layer between your agents and this server.