metriport

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

Annotations already mark destructiveHint=true. The description adds valuable behavioral context: it writes PHI and initiates health-information-exchange queries, going beyond what annotations provide. However, no mention of auth, rate limits, or reversibility.

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

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

Two sentences, front-loaded with purpose and side effects. No extraneous information. Every sentence is necessary and concise.

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

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

Given 9 parameters with full schema coverage and no output schema, the description adequately conveys the tool's purpose and side effects. It could be improved by hinting at the return value (e.g., created patient object), but the existing content covers the essential context.

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 baseline is 3. The description only mentions facilityId as a required query param, which is already in the schema. No additional meaning or context is added for parameters.

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

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

The description clearly states the verb 'Creates' and the resource 'Patient', and specifies side effects (writes PHI, initiates health-information-exchange queries). It distinguishes from sibling tools, which are all read/query/list operations, making it 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 implied by the tool's unique create function, but there is no explicit guidance on when to use vs alternatives or when not to use. The description lacks exclusion criteria or context for preferring this tool over others.

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

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

The description discloses that the tool is read-only ('returns current status without starting a new query') and provides endpoint details (POST /medical/v1/document/query). This adds value beyond the readOnlyHint annotation, clarifying no side effects and what counts are returned (download + FHIR conversion).

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

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

The description is two sentences, tightly written with no wasted words. The first sentence defines the action, the second adds operational detail. It is well front-loaded and concise.

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

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

For a status-checking tool with no output schema, the description gives adequate information: it checks progress of a document query and returns counts. It could be more complete by detailing the structure of the status response, but it is sufficient for an agent to understand the tool's utility.

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 clear description for patientId. The description adds minimal extra meaning by emphasizing 'only patientId (no facilityId)', which reinforces the parameter but does not significantly expand on schema information.

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

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

The description clearly states the purpose: 'Check the progress/status of a Patient's document query'. It uses a specific verb ('check') and resource (status of document query), and distinguishes itself from sibling tools like start_document_query or 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?

The description provides explicit context: it returns status without starting a new query, and requires only patientId (no facilityId). This indirectly tells the agent when to use it (to check an existing query) and when not to (to start a new one). However, it does not explicitly list alternative tools for starting queries.

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

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

Annotations already indicate read-only. The description adds 'temporary' and conversion context but omits details on URL expiration, rate limits, 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?

Two efficient sentences: the first explains the core action, the second provides the HTTP method and path. No unnecessary words.

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

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

Fairly complete for two params and annotations, but lacks description of the return value (e.g., whether it returns just the URL or a JSON object), leaving a gap for agent invocation.

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?

Full schema coverage; description adds meaning by linking fileName to metriport_list_documents and specifying conversionType applies to XML/CDA files, supplementing the 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 clearly states the tool gets a temporary, downloadable URL by file name with optional conversion, distinguishing it from sibling tools that focus on listing or querying.

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

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

The description implies usage after listing documents but does not explicitly state when to use this tool versus alternatives like metriport_list_documents or when not to use it.

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 provide readOnlyHint=true. The description adds the specific API endpoint but does not disclose additional behavior such as authorization needs or error conditions.

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

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

Two concise sentences, front-loaded with the purpose. No redundant information; every sentence serves a clear role.

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

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

The description is adequate for a simple read operation with full schema coverage. However, it lacks any indication of the return value structure, which would be helpful given no output 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 coverage is 100%, and the description repeats the parameter's type and usage from the schema without adding new meaning. Baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Get'), the resource ('Facility'), and the identifier ('Metriport ID'). It distinguishes from sibling 'metriport_list_facilities' which lists all facilities.

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 use when you need a specific facility by ID, but it does not explicitly state when to use this versus listing facilities or 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?

Annotations already declare readOnlyHint=true, so description adds no extra behavioral insight. Merely restates the endpoint, which is common knowledge for API-aware agents.

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 front-loaded core purpose. The API endpoint line is slightly redundant but not harmful. Could be merged without loss.

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?

Adequate for a simple read-only tool with 2 required params and no output schema. Does not explain return URL characteristics or prerequisites, but sufficient for straightforward invocation.

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

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

Schema covers 100% of parameters with descriptions. Tool description paraphrases conversionType but adds no meaning beyond 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?

Description clearly states verb 'Get', resource 'URL to Patient's medical record summary', and format options (pdf/html). Distinguishes from siblings like metriport_get_document_url by targeting medical record summary specifically.

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

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

No guidance on when to use this tool versus alternatives, no prerequisites or conditions mentioned. Sibling list suggests many query tools, but description provides no selection criteria.

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; description adds the HTTP method (GET) and endpoint path, which reinforces read-only behavior and provides API 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?

Two sentences: first states purpose and scope, second gives API reference. No unnecessary words, highly efficient.

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

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

Adequately covers purpose and identifier for a simple get-by-ID tool. Lacks return format or error info, but given no output schema and low complexity, it's 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 coverage is 100% with a clear description of 'id' as 'The Metriport Patient ID.' The tool description repeats this without adding new meaning, 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?

Clearly states verb 'Get' and resource 'a single Patient' via its Metriport ID. Distinguishes from sibling tools like metriport_list_patients and metriport_create_patient.

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

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

Implies use when you have a specific Metriport ID, but no explicit guidance on when to prefer this over listing or other tools. Sibling list_patients is a clear alternative but not 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 declare readOnlyHint=true, and the description confirms 'Get the status', consistent with read-only behavior. The description also provides the HTTP endpoint, adding transparency. No contradictions.

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

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

Two succinct sentences: first states purpose, second provides API reference. No wasted words; front-loaded with key information.

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

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

Given no output schema and a single parameter, the description could mention the output format (e.g., returns list of queries with status). However, for a simple read-only list, it is minimally adequate.

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

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

Schema coverage is 100% for the single parameter 'id', and the description does not add additional meaning beyond what the schema provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool lists status of patient's consolidated FHIR queries, specifying verb 'Get the status' and resource 'consolidated-data (FHIR) queries'. It distinguishes from sibling tools like metriport_get_document_query_status (document-level) and metriport_start_consolidated_query (initiation).

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 explicit guidance on when to use this tool versus alternatives. The description implies it is for checking status of consolidated queries, but lacks direct instruction, leaving the agent to infer from 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 include readOnlyHint=true, consistent with the description's 'list' action. The description adds value by mentioning optional filtering but does not disclose pagination or what the response looks like. Given annotations cover the read-only nature, the description is adequate 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?

Two concise sentences: first states the core function and optional filters, second provides the API endpoint. No redundancy or unnecessary words. The front-loading is effective.

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

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

The tool has 4 parameters with full schema descriptions but no output schema. The description implies the response is a list of document references but does not specify structure or mention pagination. Given the tool's simplicity and the presence of sibling tools for related actions, the description is nearly complete for a list operation.

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

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

Schema coverage is 100% with descriptions for each parameter. The description groups the parameters conceptually (date range and content search) and highlights their optionality, adding context beyond the schema. This helps the agent understand how to combine filters effectively.

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

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

The description clearly states the verb 'list', the resource 'document references currently available for a Patient', and optional filters (date range and content search). It also includes the API endpoint, which distinguishes it from sibling tools like 'metriport_start_document_query' that perform different actions.

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

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

The description does not provide guidance on when to use this tool versus alternatives. For instance, it does not clarify that this tool lists already available documents, while 'metriport_start_document_query' is for initiating a query to fetch new documents. Without such guidance, an agent may misuse the tool.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is clear. Description adds the scope 'under your Metriport Organization' but no additional behavioral traits (e.g., pagination, throttling). Acceptable given annotation coverage.

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: one for functional description, one for endpoint reference. No fluff, 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?

For a simple list operation with no parameters and no output schema, the description fully covers what the tool does and what it returns. No gaps identified.

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

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

No parameters exist, and schema description coverage is 100%. Baseline of 4 applies as description need not add parameter details.

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

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

Clearly states it lists all facilities under the Metriport Organization, including specific fields (id, name, npi, address). Distinguishes from sibling tools like 'get_facility' by indicating it returns a list.

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 explicit guidance on when to use this tool versus alternatives like 'metriport_get_facility'. Description only provides functional definition without usage 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?

The description adds that it's a GET endpoint ('Medical API: GET /medical/v1/patient'). Annotations already declare readOnlyHint=true, so no contradiction. The description does not cover other behavioral aspects like pagination, response limits, or authentication requirements beyond what annotations imply.

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

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

The description is a single sentence with no wasted words. It front-loads the core action ('List Patients') and immediately provides the optional filter and API endpoint. Very efficient.

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

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

Given the tool's simplicity (1 optional param, read-only, no output schema), the description is largely complete. It explains the filtering capability. However, it does not address potential pagination or how results are returned, which could be useful for a list operation.

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

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

Schema coverage is 100% (facilityId described). The description reiterates the optional filter but adds no new semantic meaning beyond the schema description (e.g., format, allowed values, or behavior when omitted). Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: listing all patients or filtering by facility ID. It specifies the verb 'list', the resource 'Patients', and provides a scope distinction ('all' vs. 'at a given Facility'). This is specific and distinguishes from siblings like 'metriport_get_patient' (single patient) and 'metriport_create_patient'.

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

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

The description implies usage: use with optional facilityId to filter, or omit for all. However, it does not explicitly state when to choose this over alternatives like 'metriport_get_patient' or when not to use it (e.g., for complex queries needing pagination). No exclusions or alternatives are named.

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?

Behavioral traits are disclosed: asynchronous, returns requestId, uses webhook. The annotation (destructiveHint: true) is consistent and the description adds context (POST endpoint, async nature). No contradiction, but lacks details on idempotency or side effects.

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, includes the endpoint path, no redundant words. Every sentence earns its place.

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

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

Given 6 params and no output schema, the description covers key behavioral aspects (async, requestId) necessary for use. However, it doesn't explain how to retrieve the query results or what 'consolidated' means, which could be useful for completeness.

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 baseline is 3. The description adds no extra parameter meaning beyond what the schema already provides. For example, it doesn't explain the purpose of 'resources' or 'metadata' further.

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

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

The description clearly states the action ('Starts'), the resource ('consolidated-data (FHIR) query'), and the target (patient). It distinguishes from sibling tools like 'metriport_start_document_query' by specifying it's a consolidated query and mentioning asynchronous delivery.

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 hints at when to use this tool (for consolidated FHIR queries) and that it's async with webhook delivery, but does not explicitly state alternatives or when not to use it versus something like 'metriport_list_consolidated_queries'.

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

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

The description adds context about the asynchronous return and requestId, but it contradicts the annotations which mark destructiveHint: true. A retrieval action is not typically destructive, creating confusion. The description does not disclose any side effects or additional behavioral traits beyond what annotations provide.

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

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

The description is concise (two sentences) and front-loaded with the core purpose. The inclusion of the API endpoint string is useful for developers but slightly redundant. No unnecessary words.

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

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

Given the absence of an output schema, the description adequately explains that the tool returns a requestId and that results are asynchronous. It pairs well with sibling tools like get_document_query_status. However, it does not mention error handling or webhook details, which might be needed for full context.

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 all three parameters. The description reiterates that patientId and facilityId are required, but adds no new semantic meaning or usage nuances beyond the schema. The metadata parameter is mentioned in the schema but not elaborated in the description.

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

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

The description clearly states the action ('Starts a document query') and the resource ('retrieves the patient's medical documents from connected HIE networks'). It distinguishes from siblings by noting the asynchronous nature and return of a requestId, which contrasts with synchronous tools like list_documents or get_document_query_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?

The description indicates that results arrive asynchronously and a requestId is returned, implying that one should later check status using a sibling tool like get_document_query_status. However, it does not explicitly state when to use this tool versus alternatives such as start_consolidated_query or list_documents, nor does it provide exclusions or prerequisites.

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