NexHealth MCP by usefulapi

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

Annotations only supply destructiveHint=true; the description adds real behavioral context beyond that: it is a mutation that writes to the connected EHR/PMS, and it can optionally notify the patient — a side effect an agent should know about before invoking. It stops short of covering permissions, idempotency, or error behavior, but the added value over annotations is genuine.

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 clauses, front-loaded with the verb and the mutation warning, then the constraint, then the endpoint. No filler sentences and each clause carries actionable 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 write tool with no output schema, the description covers purpose, side effects, and the key parameter constraint. It would be stronger if it indicated what is returned (e.g., the created appointment id) or failure modes, but the essential booking information is present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by stating the cross-parameter constraint that end_time and appointment_type_id are alternatives, and by flagging the optional patient-notification side effect, which the schema only partially conveys.

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 ('BOOK a new appointment'), names the target system ('creates an appointment in the connected EHR/PMS'), and includes the underlying endpoint. This clearly distinguishes it from nexhealth_update_appointment, nexhealth_get_appointment, and nexhealth_list_appointments.

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 one useful invocation rule ('Provide either end_time or appointment_type_id'), which steers how to call it. However, it never says when to choose this tool over siblings such as nexhealth_update_appointment, nor does it mention prerequisites like needing to resolve location/provider/patient ids first. Usage is implied rather than explicitly framed.

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 destructiveHint=true, so the description's 'MUTATES DATA — writes to the connected EHR/PMS' and the 'POST /patients' endpoint add real context about what the write touches and how. It still omits auth requirements, duplicate handling, and whether creation is idempotent, which would matter for a mutating tool, but the added mutation scope goes beyond the annotation.

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

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

Four short, front-loaded fragments with no filler; the create/mutate intent leads. The trailing 'POST /patients' is an implementation detail an agent cannot act on, which is the only slightly wasted token.

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 10-parameter mutation tool with no output schema, the description covers intent and mutation scope but not the return shape (the new patient id the agent needs for the confirm step) or duplicate-prevention guidance. Adequate but with clear gaps for a write operation on clinical records.

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 required flags and format patterns (e.g., date_of_birth yyyy-mm-dd) already documented per parameter. The description adds no parameter-level detail beyond echoing the location scoping, so the schema carries the load and 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 ('CREATE a new patient record in a location'), which cleanly separates it from the read-oriented siblings nexhealth_get_patient and nexhealth_search_patients. The scope (a location) and the write nature are 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?

It gives a follow-up step ('GET the patient back to confirm'), which implies the intended workflow, but never says when to use this versus alternatives. Critically, it omits the standard precondition for patient creation — checking nexhealth_search_patients first to avoid duplicate records — leaving the agent to infer 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 declare readOnlyHint=true, so the safety profile is covered, but the description adds nothing behavioral beyond restating the HTTP route: no indication of what happens on a missing/invalid id, no auth or rate-limit context, no hint at the returned shape. For a read tool with generous annotation coverage the bar is low, yet the description contributes essentially no added 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 short sentences, the purpose front-loaded before the route, with no filler. Every clause 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?

A simple read tool whose annotations cover safety and whose schema fully documents both parameters, so little is required. However, with no output schema there is no description of what an appointment record contains or how errors surface, leaving a modest gap for an agent consuming the result.

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 'id' (path param) and 'subdomain' (defaults to NEXHEALTH_SUBDOMAIN) documented in the schema, so baseline 3 applies. The description adds no format or constraint detail beyond the schema.

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

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

States a specific verb (fetch) and resource (a single appointment by id), and the word 'single' distinguishes it from the sibling nexhealth_list_appointments. It stops short of naming that sibling explicitly, but an agent can tell what it does 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?

Usage is implied by 'by id' — you call it when you already have an appointment id — but there is no explicit when-to-use guidance and no mention of alternatives like list_appointments or search paths. Minimum viable routing information.

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, but the description adds essentially nothing beyond that — no 404/not-found behavior, no auth or subdomain-permission context, no pagination or expansion notes. Mentioning the REST route GET /patients/{id} is a restatement of the name rather than behavioral disclosure.

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 purpose, with no padding. The trailing 'GET /patients/{id}.' is largely redundant with the tool name and title, a minor cost.

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 single-record read with annotations covering the safety profile and a fully described schema, the essentials are present. However, with no output schema and no statement of what a fetched patient contains or how failures surface, completeness is only 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 description coverage is 100%, so both the id path param and the subdomain fallback are already documented in the schema. The description's 'by id' adds no format, range, or fallback detail beyond that, 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 (fetch) and resource (a single patient) with the lookup key (id), and 'single' plus 'by id' implicitly separates it from search_patients and list-style siblings. An agent can pick this tool apart from nexhealth_search_patients without opening either 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?

'By id' implies usage only when a patient id is already known, which is a reasonable cue, but the description never names the alternative (nexhealth_search_patients) or states a when-not condition. Usage is inferred 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.

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds the underlying HTTP operation (GET /appointments) and the fact that the window frames the result set, but says nothing about pagination defaults, ordering, timezone handling, or result shape beyond what the 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?

Two compact sentences with the purpose and scope front-loaded and no padding. The trailing 'GET /appointments' is mildly redundant given the tool name, but it is the only thing keeping this from a 5.

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 read tool with no output schema, the description covers purpose, scope, and filters but omits anything about pagination behavior, default ordering, or whether the date window is required in practice. Adequate to call, incomplete for an agent that must reason about results.

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 one of the 9 parameters (start, end, page, per_page, include, subdomain, and the three id filters) is already documented in the schema. The description only restates the filter set at a high level, adding no syntax, defaults, or interaction rules (e.g. whether start/end are effectively mandatory).

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 appointments') plus the scoping dimension (date/time window) and the optional filter axes. That is enough for an agent to separate it from the singular nexhealth_get_appointment and from nexhealth_list_appointment_slots without opening either 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 description establishes context ('in a date/time window, optionally filtered by location, patient, or provider') but never says when to prefer this over nexhealth_get_appointment or nexhealth_list_appointment_slots, and gives no exclusions or prerequisites. Usage is implied rather than directed.

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, so the description only needs to add context. It adds that results are bookable start times rather than raw availability, plus the GET endpoint, but says nothing about result limits, pagination, or how tight a date range should be to stay performant.

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, no filler, and the functional purpose is front-loaded ahead of the endpoint reference. Nothing could be cut without losing 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 read-only slot-search tool with fully documented parameters and no output schema, the description covers what the tool returns in broad terms (bookable start times across providers/locations). It leaves unstated whether pids/lids are required for meaningful results and what the response structure looks like, but those gaps are modest.

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 seven parameters (days, lids, pids, subdomain, start_date, slot_length, overlapping_operatory_slots) are already documented in the schema. The description only echoes the date-range concept and adds no semantics beyond it; 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?

Uses a specific verb ('Find') plus resource ('bookable appointment start times') and states the scoping axes (providers/locations, date range). 'Bookable' implicitly distinguishes it from nexhealth_list_appointments (existing booked appointments), but the description never names that sibling, so the differentiation is left to inference.

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 only usage signal is 'High-value for scheduling,' which hints at intent but names no alternative and gives no when-not condition. Nothing tells the agent to call this before nexhealth_book_appointment, or how it relates to nexhealth_list_appointment_types or nexhealth_list_operatories.

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 only the HTTP verb/path (GET /appointment_types) and the institution/location scope, but says nothing about pagination behavior, auth requirements, or whether defaults are applied.

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 purpose front-loaded and no filler. The trailing 'GET /appointment_types.' is mild redundancy given the resource is already stated, but nothing is bloated.

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

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

For a simple read-only list tool with fully documented parameters and annotation-covered safety, this is close to sufficient. However, with no output schema, the description does not hint at the returned shape or pagination semantics, leaving those 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 four parameters (page, per_page, subdomain, location_id) are already documented in the schema. The description only restates the institution/location scoping, adding no syntax or default-behavior 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 (List) and resource (appointment types) scoped to an institution/location, which distinguishes it from sibling tools like nexhealth_list_appointments and nexhealth_list_appointment_slots. It does not explicitly name a sibling it differs from, but the resource 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?

There is no explicit when-to-use guidance, no prerequisites, and no alternatives named. The agent can infer this is a lookup of configured types (e.g., before booking), but nothing in the text states that condition.

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, so the bar is lower, but the description adds essentially nothing beyond the endpoint string. It doesn't mention pagination behavior, what the coverages include, or that patient_id is technically optional yet presumably required in practice.

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 purpose front-loaded and no padding. The trailing 'GET /insurance_coverages' is low-value REST trivia but costs almost nothing.

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 documentation, the description is minimally adequate. With no output schema, it could have said something about what a coverage record contains or how results are paged, but nothing essential to invoking it 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 page, per_page, subdomain, and patient_id are all already documented in the schema. The description adds no additional meaning; baseline 3 applies when the schema carries the load.

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: listing a patient's insurance coverages. This distinguishes it reasonably well from the sibling nexhealth_list_insurance_plans, though it does not explicitly explain the difference between a 'coverage' and a 'plan'.

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 guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The neighboring list_insurance_plans tool begs for a disambiguating sentence, which is absent.

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 read operation, and 'GET /insurance_plans' reinforces that. The description adds the institution-level scoping context but says nothing about pagination behavior, result volume, or auth/subdomain requirements beyond what the schema states.

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 resource and its scoping constraint front-loaded; nothing is wasted. The trailing HTTP verb/path is compact and confirms read semantics.

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 no output schema and full parameter documentation, the description covers what is needed to call it correctly. The remaining gap is the lack of differentiation from nexhealth_list_insurance_coverages, which matters given how similar the sibling names are.

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 page, per_page, subdomain and location_id are all documented in the schema; baseline 3 applies. The description's 'optionally scoped to a location' maps to location_id but adds no syntax, format, or default-behavior 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 ('List insurance plans') plus the scope ('known to the institution, optionally scoped to a location'). It does not, however, distinguish itself from the closely named sibling nexhealth_list_insurance_coverages, leaving the agent to guess which one holds plans vs. coverages.

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 a straightforward enumeration with an optional location filter, but gives no explicit when-to-use or when-not-to-use guidance, and no routing to alternatives such as nexhealth_list_insurance_coverages or nexhealth_list_locations. The only usage hint is that location scoping is optional.

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 GET endpoint and the returned field set but says nothing about pagination, result limits, or whether an empty list is possible; with annotations carrying the safety story, this is adequate but thin.

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

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

Three short, front-loaded sentences: purpose, tactical guidance, endpoint. No filler and nothing buried.

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

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

For a simple read-only list tool with no output schema, the description covers purpose, return fields, and call ordering well enough to invoke correctly. The only real gap is pagination/result-set size behavior, which is minor for a locations listing.

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 subdomain parameter is fully documented there, so baseline 3 applies. The description's phrase 'for an institution' loosely links the subdomain to the institution concept, but adds no format or fallback 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 ('List the practice locations'), names the scope ('for an institution'), and previews the returned fields (id, name, address). This distinguishes it from sibling list tools such as list_providers or list_operatories without needing to open 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?

Explicitly frames the call as a discovery step ('Good first call to discover location_ids for other tools'), which tells the agent when to reach for it. No exclusions or explicit alternatives are named, but the intended ordering relative to other tools is clear.

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's 'GET /operatories' simply restates that it is a read. It adds no behavioral context such as pagination, ordering, or what happens with an invalid location_id. With annotations carrying the safety profile, the description contributes almost nothing new.

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 clauses plus an endpoint reference, with the resource and its scope front-loaded. Nothing is padded, though the trailing 'GET /operatories' is close to redundant given the annotations.

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, no-required-param read tool with annotations covering safety, this is minimally adequate. However, there is no output schema, so the description could reasonably say what is returned (a list of operatories) or whether results are paginated, and it does not.

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 subdomain and location_id are already documented in the schema. The description's 'for an institution' and 'scoped to a location' loosely map to those two params but add no format or edge-case detail beyond them; 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) and resource (operatories), and helpfully glosses the domain term as 'chairs/rooms' for an agent that may not know NexHealth vocabulary. It does not differentiate itself from the adjacent list_* siblings (e.g. list_locations), but the resource 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?

'optionally scoped to a location' implies when to pass location_id, which is the only usage decision this tool has. No alternatives are named and no prerequisites (e.g. needing a valid subdomain) are stated, so guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the GET endpoint, which lightly reinforces read-only intent, but says nothing about pagination defaults, result volume, or return shape.

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 very short sentences, front-loaded with the resource and scope; the endpoint tag is compact and no sentence 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?

A simple read-only list tool with full schema param coverage and read-only annotations; the description is adequate. Minor gap: no mention of pagination behavior even though page/per_page exist, but the schema documents them.

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 page, per_page, subdomain, and patient_id are fully documented in the schema. The description only echoes the patient scoping already covered by patient_id, adding no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('List clinical procedures') and adds the scoping dimension ('optionally scoped to a patient'), plus the underlying endpoint. It does not explicitly differentiate from siblings like nexhealth_list_appointments, though the resource noun makes the distinction 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?

The phrase 'optionally scoped to a patient' implies the filtering use case, but there is no explicit when-to-use vs when-not guidance and no named alternative tool. Usage is inferable 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 the safety profile is covered. The description adds the endpoint ('GET /providers') and the scoping model, but says nothing about pagination behavior or result limits even though page/per_page 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, front-loaded with the resource and scope, ending with the underlying endpoint. Every clause earns its place 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?

For a simple read-only list endpoint with full schema coverage and annotations already conveying safety, the description covers what the agent needs. It lacks only pagination semantics and the return shape, minor gaps that do not block correct 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 description coverage is 100%, so all four parameters (page, per_page, subdomain, location_id) are already documented. The description only echoes the location scoping, adding no new syntax or defaults 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 ('List practitioners (providers) for an institution') and clarifies optional location scoping, which cleanly separates it from siblings like nexhealth_list_locations or nexhealth_list_operatories. It stops short of explicitly naming those siblings, so it is clear but not fully differentiated.

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 'for an institution, optionally scoped to a location' implies the appropriate usage context, but there is no explicit when-to-use/when-not guidance and no reference to alternative listing tools in the sibling set.

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 as a safe read, so the bar is lower; the description usefully adds that search is location-scoped and surfaces the underlying GET /patients endpoint. It does not disclose pagination behavior, the default handling of inactive patients, or how multiple filters combine.

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

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

Three short, front-loaded sentences with no filler; the location-context constraint appears before the endpoint reference. The trailing "GET /patients" is marginally useful rather than padding.

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 10-parameter tool with no output schema, the description covers the core search semantics but omits pagination expectations, inactive-patient defaults, and whether filters are ANDed. Adequate but leaves gaps an agent must infer from 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 the schema already documents all 10 parameters including pagination, sort, subdomain, and inactive. The description only echoes the filter fields (name, email, phone, DOB) without adding syntax or combination 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 (Search) and resource (patients) plus the searchable fields and the location scoping constraint, which separates it from the single-record get_patient. It does not explicitly name siblings, but the scope 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?

"Patient search is always in a location context" implies the required context but gives no explicit when-to-use vs get_patient (single lookup) or list_appointments guidance, and no exclusion conditions.

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 non-mutating read, so the bar is lower. The description adds the useful framing that this checks whether the Synchronizer is up to date, but does not disclose what a degraded/errored state looks like or how failures surface.

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 compact sentences, purpose front-loaded, with the endpoint appended as a short reference. Little waste; the raw "GET /sync_status" adds marginal value but does not bloat the text.

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-reporting tool with no output schema, the description says nothing about what the response contains (sync timestamps, last-synced time, error flags), which is the information an agent most needs. Annotations cover the safety profile, so this is the main remaining 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?

Only one optional parameter (subdomain) and schema description coverage is 100%, so the schema already documents the default-to-env-var behavior. The description adds no additional parameter meaning, which is acceptable at this coverage level.

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 ("Report") and a precise resource ("data-sync health for the practice's EHR/PMS integration"), even naming the concrete artifact (the Synchronizer). This is trivially distinguishable from every sibling, all of which are appointment/patient CRUD tools.

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 nature of a status endpoint, and the parenthetical "is the Synchronizer up to date?" clarifies intent. However, it never states when to call this versus other diagnostics, nor any preconditions (e.g., integration must be connected), so it stays at implied usage.

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; the description reinforces that with 'MUTATES DATA' and adds that this happens in a connected EHR/PMS, which is genuine extra context. It does not disclose reversibility, permission requirements, or how the cancel/confirm flags interact, so it stays near the annotation baseline.

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

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

Extremely tight and front-loaded, with the mutation warning prominent. The trailing 'PATCH /appointments/{id}' largely restates the id path param already in the schema, a minor redundancy.

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

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

For an 8-parameter destructive mutation with no output schema, the description covers the risk well but says nothing about the response (e.g., whether the updated appointment is returned) or whether updates are partial. All parameters are documented in the schema, so the gap is modest but real.

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 in the schema, including the cancelled/confirmed/start_time semantics. The description's operation list loosely maps to those fields but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States specific verbs (update/reschedule/cancel/confirm) on a specific resource ('existing appointment by id') and even maps to the PATCH endpoint. 'Existing appointment' implicitly differentiates it from book_appointment and get_appointment in the sibling 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?

Usage is implied by 'existing appointment' (versus booking a new one), but there is no explicit statement of when to use this over book_appointment or get_appointment, nor prerequisites such as needing a valid id first.

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