Metriport MCP by usefulapi

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

Annotations only supply destructiveHint=true; the description adds substantive context beyond that by disclosing that the call writes PHI and triggers health-information-exchange queries, plus the concrete endpoint. It stops short of covering auth requirements, idempotency, or error behavior, but the key side effects are surfaced.

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?

A single tight sentence with the primary purpose front-loaded, followed by the endpoint and required-param note. Every clause carries information; 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 9-parameter mutation with no output schema, the description covers the operation, its side effects, and the endpoint, and the schema fully documents the inputs. The one notable gap is that, with no output schema present, it does not hint at what the call returns (e.g., a patient ID), leaving that to inference.

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 9 parameters (including the 6 required ones) are already documented in the schema. The description only restates that facilityId is required, adding no meaning beyond what the schema provides; 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 ('Creates a Patient in Metriport') and immediately distinguishes itself from the sibling get_/list_ tools by noting it writes PHI and initiates HIE queries. An agent can identify its role 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?

There is no explicit when-to-use/when-not guidance and no reference to alternatives (e.g., get_patient or any update path). The implied usage is registration of a new patient, but the agent must infer that from the verb alone.

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

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

Beyond the readOnlyHint annotation, the description discloses the underlying endpoint semantics and that the call is non-mutating (does not start a new query) and returns progress counts. It does not cover auth requirements, rate limits, or error/empty-result behavior, but that is a minor gap given the annotation already signals a safe read.

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

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

Two sentences, front-loaded with the core purpose before the API-level clarification. The endpoint path detail is somewhat verbose but it is what justifies the 'does not start a query' behavior, so it largely 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 single-parameter, read-only status check with no output schema, the description covers purpose, non-mutating behavior, and the shape of what is returned (counts). An agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the single patientId parameter is already documented in the schema, so the baseline is 3. The description adds only a marginal note that no facilityId is required, which clarifies the parameter's scope slightly.

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 (check status/progress) on a specific resource (Patient's document query) and even enumerates what the status reports (download + FHIR conversion counts). This cleanly separates it from start_document_query, which initiates rather than 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?

Explicitly disambiguates use: POSTing with only patientId 'returns current status without starting a new query', which tells the agent this is the read-only counterpart to start_document_query. It doesn't name the sibling tool by name, but the when-not condition is unambiguous.

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 safe-read profile, and the description adds genuinely new behavioral detail: the URL is temporary, and XML/CDA files can be converted to html or pdf. It omits expiry duration and any auth requirements on the returned URL, so it is helpful but not exhaustive.

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?

One front-loaded sentence carries the purpose, input, and optional conversion behavior. The trailing "Medical API: GET /medical/v1/document/download-url" is mildly redundant with the tool's title but aids endpoint alignment.

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 adequately characterizes the return value (a temporary download URL). For a 2-parameter read tool with readOnlyHint coverage, the missing details are minor: expiry window and any auth needed to fetch the URL.

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 parameters are already documented in the schema. The description's mention of optional XML/CDA-to-html/pdf conversion largely restates the conversionType schema text; no syntax, defaults, or format constraints are added beyond it.

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 (get), a precise resource (temporary downloadable URL for a document), and the lookup key (file name). This is clearly distinguishable from sibling list_documents, which enumerates files rather than producing a download link.

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 names the prerequisite source for the required input ("file name ... from metriport_list_documents"), which routes the agent correctly. It stops short of stating when-not to use it or naming a direct alternative, so it lands at clear-context without exclusions.

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

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

The readOnlyHint annotation already establishes this as a safe, non-mutating read. The description adds the underlying API endpoint mapping, which aids traceability, but says nothing about failure behavior (e.g., unknown/404 IDs) or response characteristics beyond what the annotation already covers.

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 short sentences, front-loaded with the action and resource, followed by the endpoint reference. 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 trivial single-parameter read tool with full schema coverage and a readOnlyHint, the description is nearly sufficient. The only gap is the absence of an output shape hint, and since no output schema exists, a brief note on the returned facility object would have fully closed the loop.

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

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

Schema description coverage is 100% for the single 'id' parameter, so the schema already explains it as 'The Metriport Facility ID.' The description restates the same idea ('by its Metriport ID') without adding format, source, or lookup guidance, 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 and resource ('Get a single Facility') and adds the HTTP route, which makes the intent unambiguous. The word 'single' implicitly contrasts with the sibling metriport_list_facilities, but no sibling is named, so differentiation is inferred rather than explicit.

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?

'by its Metriport ID' implies the caller must already have an ID, which is a reasonable usage cue, and the single-vs-list framing hints at when to prefer this over metriport_list_facilities. However, there is no explicit when-to-use statement or guidance on what to do when the ID is unknown.

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, but the description adds genuinely useful return semantics beyond the annotation: the tool yields a URL rather than the document itself. It does not cover URL expiry, auth scope, or whether retrieval is synchronous, which keeps 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?

Two tight sentences with the purpose and output type front-loaded. The trailing REST route is mildly redundant given the tool name, but it is compact and does not bury the essential information.

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

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

For a two-parameter, read-only tool with no output schema, the description supplies the missing return-value information (a URL) that an agent needs to chain the call. It omits lifecycle details like URL expiration or regeneration requirements, 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% with both parameters documented and one enum, so the schema fully carries parameter meaning. The description only restates the pdf/html format choice, adding no new detail such as defaults or rendering trade-offs; 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 states a specific verb and resource — retrieving a URL to a Patient's medical record summary rendered as pdf or html — and distinguishes it from siblings like metriport_get_document_url by naming the distinct artifact (medical record summary). It even pins the underlying REST route, so the agent knows exactly what is being fetched.

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 artifact requested, but there is no explicit statement of when to prefer this over metriport_get_document_url or metriport_list_documents, nor any prerequisite (e.g., whether the summary must be generated first). The agent must infer the selection context.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds value by disclosing the payload content (demographics + facility IDs) and the backing REST endpoint, but says nothing about error behavior (e.g., unknown ID) or what happens if the patient does not exist.

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 tight sentences, zero filler, with the verb+resource+identifier front-loaded; the endpoint path is a compact secondary detail.

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

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

For a one-parameter read with no output schema, the description gives just enough return context ('demographics + facility IDs') and pins the operation to a documented endpoint. It lacks only a note on failure/lookup behavior, which keeps it from a 5.

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

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

Schema description coverage is 100% for the single 'id' parameter, so the schema already documents the Metriport Patient ID. The description restates rather than enriches this (no format, prefix, or example), 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 ('Get') and resource ('a single Patient') and clarifies the identifier is a Metriport ID. The word 'single' implicitly separates it from metriport_list_patients, but no sibling is named explicitly, 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?

Usage is implied: fetch one patient when you already hold a Metriport Patient ID. There is no explicit when-to-use/when-not guidance and no pointer to metriport_list_patients for lookup-by-name, leaving the agent to infer the routing.

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 description carries less burden. It adds the REST endpoint mapping, but says nothing about what a query status can be, whether results are paginated, or how many queries are returned — the behavior of a polling endpoint is left implicit.

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 short sentences, with the functional purpose front-loaded and the endpoint mapping relegated to second position. Nothing is padded, though the raw URL adds only marginal value beyond the prose.

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 should convey what comes back — a status list, its possible states, or at least that it may be empty before a query is started. The name/purpose mismatch ('list' vs 'get the status') also goes unaddressed, leaving a small interpretive gap for a status-polling 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?

There is a single parameter (id) with full schema description coverage ('The Metriport Patient ID'), so the schema already does the work. The description restates the resource hierarchy via the URL path but adds no new semantic detail about the id parameter.

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

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

States a specific verb and resource — retrieving the status of a patient's consolidated-data (FHIR) queries — and pins it to a concrete endpoint (GET /medical/v1/patient/{id}/consolidated/query). It does not, however, differentiate itself from the close sibling metriport_get_document_query_status or explain how 'list' in the name relates to 'get the status'.

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

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

There is no statement of when to use this versus metriport_start_consolidated_query (start vs poll), nor versus metriport_get_document_query_status. The agent must infer that this is the polling/status counterpart to the start tool from the name alone.

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 annotation already establishes this is a safe read, so the description only needs to add beyond that. It usefully clarifies that the result is document *references*, not document contents, and cites the underlying endpoint, but says nothing about pagination, result limits, or auth/scope 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?

One sentence with the core action front-loaded, followed by a compact endpoint reference. The parenthetical filter list is genuinely informative rather than filler; little is wasted.

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 listing tool with no output schema, the description is nearly complete: it identifies the required patient scope, the optional filters, and the fact that references rather than contents are returned. Only pagination/response-shape behavior 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 all four parameters (including the date patterns and the 3-char minimum for content) are already documented structurally. The description only restates the date-range and content-search filter categories, adding no syntax or default information 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 (List) and resource (document references for a Patient), plus the scope of optional filters. It is distinguishable from the document-query siblings (start_document_query, get_document_query_status, get_document_url) by resource, though it does not name any 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?

The phrase 'currently available for a Patient' and the optional date/content filters imply when to use it, but there is no explicit guidance on when to prefer this over get_document_url (to retrieve the actual file) or the query-status siblings. Usage context is implied rather than 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 no behavioral context beyond that — no pagination behavior for a 'list all' call, no rate limits, no ordering guarantees, and no auth note. The API path is a mapping, not a behavioral trait.

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?

One compact sentence plus an endpoint reference, with the scope and output fields front-loaded. Every element is short, though the endpoint string is arguably redundant for an agent.

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 parameters and no output schema, the description usefully enumerates the returned fields (id, name, npi, address), which substitutes for a missing output schema. It stops short of covering pagination or volume expectations for an unfiltered organization-wide list.

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

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

The tool takes zero parameters, so the baseline is 4. The parenthetical field list describes return values rather than inputs and therefore adds nothing to parameter understanding.

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 (List) plus resource (Facilities) with explicit scope (under your Metriport Organization) and the fields returned. It is distinguishable from metriport_get_facility only by the plural 'List all', so sibling differentiation is implied rather than stated.

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 guidance, no preconditions, and no mention of the sibling metriport_get_facility that would be the alternative for fetching a single facility. The agent must infer usage from the name alone.

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 safe-read profile is covered. The description adds the underlying REST mapping (GET /medical/v1/patient), which is useful context, but says nothing about pagination, result caps, or ordering — notable gaps for a list endpoint with 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?

One tight sentence front-loads the behavioral rule (default = all, filter = facility) with the API path appended as supporting detail. 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?

For a single-optional-param read tool with no output schema and annotations covering safety, the description covers the essential decision (filter or not). The only real omission is any hint about result size/pagination behavior, which a listing tool's consumer would benefit from.

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 fully documented there ('Optional Facility ID to filter by. Omit to list all patients.'). The description restates the same filter behavior without adding format, type, or edge-case 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?

The description gives a specific verb ('List') plus resource ('Patients') and nails down the scope: all patients, or only those at one Facility when facilityId is supplied. That scope distinction implicitly separates it from the singular sibling metriport_get_patient, though 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?

It states the condition that widens or narrows the result ('only those at a given Facility if facilityId is supplied'), which implies the filter contract. There is no explicit when-to-use/when-not guidance and no reference to alternative tools such as metriport_get_patient or metriport_create_patient.

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 carry destructiveHint=true and a title, so the description does the heavy lifting: it discloses that the call returns a requestId and that the bundle arrives asynchronously via webhook, which is essential for correct orchestration. It still does not say what triggers the destructiveHint (e.g. whether requests can be re-run or cancelled), leaving one annotation unexplained.

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

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

Two sentences, front-loaded with the action and immediately followed by the async contract. The trailing endpoint path is marginally redundant with the tool name but is still useful for agents reasoning about the Medical API surface.

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 6 parameters, no output schema, and an async delivery model, the description covers the critical unknowns: the return shape (requestId) and how results arrive (webhook). Gaps remain around follow-up retrieval and any permissions or rate limits, but nothing an agent needs to fire the call correctly 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 description coverage is 100%, with id, dateFrom/dateTo, metadata, resources, and conversionType all documented in the schema, so the baseline is 3. The description adds nothing parameter-specific beyond tying metadata implicitly to the webhook, so it does not exceed the schema's contribution.

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 ('Starts a consolidated-data (FHIR) query for the patient') and names the concrete endpoint, so the agent knows exactly what operation runs. It does not explicitly contrast with the sibling metriport_start_document_query, so the boundary between 'consolidated' and 'document' queries must be inferred.

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 the mechanics but never states when to choose this over metriport_start_document_query, nor what to do afterward. The only implicit guidance is that delivery is asynchronous, hinting the agent should follow up via list_consolidated_queries or a webhook, but that routing is left to inference.

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 supply only destructiveHint=true, so the description carries most of the burden. It usefully discloses the async return contract (requestId, results delivered later), which goes beyond the annotation, but says nothing about why the call is destructive, what external HIE side effects occur, or whether authorization/consent is required.

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?

A single dense paragraph that front-loads the core action, then the async behavior, then the REST mapping. Nothing is wasted, though the trailing endpoint/param clause is somewhat 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?

With no output schema, the description correctly explains the return (a requestId with asynchronous results). For a 3-param tool with full schema coverage and an annotation, this is nearly complete; only the downstream status-check path and side-effect/permission context are 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 description coverage is 100%, so patientId, facilityId, and metadata are already documented in the schema. The description only restates that patientId and facilityId are required query params, adding no syntax or format detail beyond the structured fields, 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 gives a specific verb+resource ("starts a document query") and clarifies the scope as retrieving medical documents from connected HIE networks, which separates it from siblings like metriport_list_documents or metriport_start_consolidated_query. It does not explicitly name a sibling for contrast, 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?

It states that results arrive asynchronously via a requestId, which implies the follow-up use of metriport_get_document_query_status, but never says so explicitly or states when not to use this tool. Usage is inferable rather than spelled out.

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