Elation Health MCP by usefulapi

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered structurally. The description adds real value beyond that by enumerating the returned fields (telehealth and billing details, service location, etc.), which matters because there is no output schema. It does not mention error behavior or permissions, keeping 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?

A single front-loaded sentence that leads with the operation and then the payload, plus the endpoint reference. The field enumeration is long but informative for a tool with no output schema, so little is wasted; minor redundancy with the title.

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

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

For a one-parameter read tool with no output schema, the description supplies the missing return-shape information by listing the fields returned and cites the underlying endpoint. It omits failure/not-found behavior, which prevents a 5, but an agent has enough 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 description coverage is 100% for the single parameter ('Elation appointment id.', integer, positive), so the schema fully documents it. The description's 'by id' phrasing adds no syntax, format, or sourcing detail beyond the schema, matching the baseline 3.

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

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

States a precise verb+resource ('Get one appointment by id') and enumerates the data returned (scheduled date, status, patient, physician, billing, etc.). The word 'one' implicitly distinguishes it from the sibling elationhealth_list_appointments, so an agent can route correctly without opening the schema.

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

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

The 'by id' framing implies the tool is for retrieval when a specific appointment_id is already known, which is the necessary precondition. However, it never explicitly says to use list_appointments to discover ids or states when this tool is preferable, so guidance 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real context the annotations do not: this returns PHI, and the SSN is redacted — a meaningful behavioral disclosure for an agent handling patient data. It does not cover error behavior for a missing/invalid id, which keeps it from 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?

A single dense sentence pairing the field inventory with the PHI/SSN caveat, then the upstream endpoint. Front-loaded, zero 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?

With no output schema, the description carries the burden of telling an agent what returns, and it does so by enumerating the chart-header fields plus the SSN redaction. Complete enough to call correctly; only absence of missing-id/error behavior 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% and the single patient_id param is documented in the schema with its origin (elationhealth_list_patients) and type. The description adds no syntax or constraint detail beyond the schema, so the baseline of 3 applies.

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

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

Specific verb ('Get') + resource ('one patient chart header') + retrieval key ('by id'), and it enumerates exactly which fields come back. An agent can distinguish this from elationhealth_list_patients purely by the 'one ... by id' framing without opening the schema.

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

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

The 'by id' framing and the param note pointing to elationhealth_list_patients imply the correct usage context, but the description never explicitly states when to use this versus the sibling list/other get tools. Usage is inferable, not 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?

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so safety is covered. The description adds two genuinely useful behavioral facts beyond that: the response contains PHI (privacy/redaction handling) and includes the full note body, which may be large. It stops short of describing not-found or error behavior.

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 zero filler, front-loading the identity of the tool and the returned payload before the API mapping. Nothing could be removed 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 single-record get with full schema coverage and rich annotations, nothing critical is missing: the description compensates for the absent output schema by naming the returned fields, and flags the PHI/full-body scope. 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?

Single parameter with 100% schema description coverage; the schema already documents it as an Elation visit note id sourced from elationhealth_list_visit_notes. The description's 'by id' adds no format or constraint detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one visit note by id') and enumerates exactly what comes back: visit date, type, physician, signed state and the full note body. The 'one ... by id' framing cleanly separates it from the sibling elationhealth_list_visit_notes.

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

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

Usage is only implied: fetch a single note when you already have its id. There is no explicit when-to-use, no when-not-to-use, and no named alternative; the only link to the sibling tool lives in the schema's parameter description rather than the tool description.

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, idempotentHint, and no destructive behavior, so the safety profile is covered. The description adds genuine context beyond that: it flags the response as PHI (sensitive data handling) and discloses the underlying Elation GET endpoint, which helps an agent reason about freshness and scope.

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

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

A single compact sentence with the return payload front-loaded and the endpoint as a trailing technical note. No filler, no redundancy, and the most decision-relevant information comes first.

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

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

With no output schema, the description usefully enumerates the returned fields and marks the data as PHI, and annotations plus the schema cover safety and paging. A brief note on paging semantics or expected volumes would make it fully self-contained, but nothing essential for a correct call 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% – limit, cursor, offset, and patient are all documented in the schema, including default and max values and the source of the patient id. The description adds no parameter-level detail beyond the displayed 'GET /allergies/?patient=' endpoint, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('List one patient's allergies') and enumerates what is returned (allergen name, reaction, severity, status, start date). The resource is clearly distinct from siblings like list_medications, list_problems, and list_vitals, so an agent can disambiguate without opening a 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 single-patient scoping ('one patient's allergies') implies when the tool applies, and the endpoint string hints at the required patient filter. However, there is no explicit when-to-use vs. alternatives guidance, no note about related siblings, and no prerequisites stated in prose (the patient-id provenance lives only in the schema).

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuine value by enumerating the record fields returned (scheduled date, duration, status, reason, patient, physician, service location) and mapping to the upstream API (GET /appointments/), but says nothing about pagination defaults, rate limits, or auth.

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

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

Three short sentences, front-loaded with the core capability followed by the returned fields and endpoint note. Every sentence carries information, though the trailing 'Elation: GET /appointments/.' is only marginally useful to an agent choosing a tool.

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 compensates well by listing the fields each record carries, and the 100%-covered input schema handles parameter details. It is nearly complete for a read-only list tool; only pagination behavior expectations (cursor vs offset default) are left entirely to the schema.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters with types, ranges and formats. The description restates four filter dimensions (date range, patient, physician, practice) but adds no format or interaction guidance beyond the schema, so it sits at the baseline.

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 and calendar time slots') and enumerates the filter dimensions and returned fields, so the scope is unambiguous. It does not explicitly differentiate itself from siblings like elationhealth_get_appointment or elationhealth_list_appointment_types, but the list-vs-single distinction is inferable.

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 through 'filterable by date range, patient, physician and practice,' which tells an agent how to narrow results, but never states when to prefer this tool over elationhealth_get_appointment or when a filter is required. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the meaning of the returned records (visit reasons with default duration) and names the backing endpoint, but says nothing about authorization scope or pagination behavior beyond the 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?

Two compact sentences, purpose front-loaded and the endpoint reference kept at the tail. No filler or 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 a simple read-only list endpoint with full schema coverage and no output schema, the description is nearly sufficient. Only minor gaps remain, such as whether results are inherently scoped to the caller's practice.

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 name, limit, cursor, offset, and practice all documented in the schema itself. The description adds no parameter syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the appointment types') and even explains what an appointment type is ('visit reasons with default duration'). It does not explicitly contrast with siblings like list_appointments, though the resource distinction is self-evident.

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: this is a catalog lookup for scheduling/visit-reason context, and the endpoint reference signals a fetch operation. There is no explicit when-to-use or when-not-to-use guidance relative to list_appointments or get_appointment.

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 cover readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds useful context beyond them: it flags PHI sensitivity, discloses that both current and discontinued entries appear by default, and gives the underlying endpoint. It stops short of describing pagination mechanics or return format.

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?

Front-loads the verb and resource, then the returned fields. The field enumeration is somewhat long but each item earns its place as return-value documentation given the absence of an output schema. The trailing endpoint is compact.

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 list tool with full annotation coverage and complete schema descriptions, this is nearly complete. The field enumeration substitutes for the missing output schema, so an agent knows roughly what comes back. Minor gaps remain around pagination/return structure.

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 the schema already documents all six parameters, establishing a baseline of 3. The description adds value by explaining the default filtering behavior ('both appear unless you filter'), which contextualizes the permanent and discontinued flags beyond their 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?

States a specific verb (List) and resource (medication documents) scoped to one patient, and enumerates the fields returned. It is trivially distinguishable from siblings like list_allergies, list_problems, and list_vitals.

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 clarifies the default result set ('current and discontinued entries both appear unless you filter'), which tells the agent when filtering is needed. However, it does not name alternative tools or explicit when-not conditions, so guidance is clear but not routing-level.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds a PHI sensitivity marker and the raw Elation endpoint, which is modest extra value but says nothing about pagination behavior or response size beyond what the schema's limit/cursor/offset fields already convey.

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: purpose and scope first, underscores the PHI nature and the concrete note types in the same breath. No filler, no restatement of the title, and the endpoint reference is compressed into one short clause.

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, single-filter list tool with all four parameters documented and safety annotations present, the definition covers what an agent needs to select and call it. The only gaps are what a note record contains (no output schema exists) and explicit paging guidance in prose, both minor since the schema carries the paging contract.

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 every parameter (limit, cursor, offset, patient) is documented in the schema itself, including paging semantics and the provenance of the patient id. The description only echoes the patient filter via the endpoint string, adding 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 a specific verb and resource ('List one patient's non-visit notes') and immediately scopes it as 'free-text chart notes outside a visit,' which cleanly separates it from the sibling elationhealth_list_visit_notes and elationhealth_get_visit_note. The concrete examples (phone calls, administrative notes) make the resource unambiguous without opening the schema.

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

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

The 'outside a visit' qualifier gives clear context for when this tool applies versus its visit-note siblings, and it is patient-scoped. It stops short of an explicit exclusion sentence such as 'for notes attached to an encounter, use list_visit_notes instead,' so the routing 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 readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely useful behavior beyond that: name matching is exact and case-insensitive with no partial names, and SSN is redacted, which an agent needs to know before querying.

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?

Front-loads purpose, then matching semantics, then the PHI redaction note, with a trailing API endpoint reference. Every sentence carries information; only the raw endpoint reference is marginal.

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 zero required parameters, full schema coverage, and annotations covering the safety profile, the description supplies the extra context (matching rules, redaction) needed to query correctly. Pagination mechanics live in the schema, so their absence from the description is acceptable.

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 nine parameters are already documented in the schema. The description's note about exact, case-insensitive name matching largely restates the schema's own wording for first_name/last_name, so it adds little beyond the baseline.

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 (patient charts/PHI) and enumerates the returned fields, which clearly frames this as a patient lookup/list operation. It does not explicitly differentiate from the sibling elationhealth_get_patient, though the plural/search framing makes the distinction inferable.

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 (search the practice's patient charts) but there is no explicit when-to-use guidance or reference to alternatives such as elationhealth_get_patient for single-record retrieval. No exclusions or prerequisites are 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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds the underlying endpoint (GET /physicians/) and the returned field set, which is modest extra context but says nothing about auth requirements, rate limits, or paging behavior 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?

A single compact sentence with the resource up front, followed by a short endpoint reference. The dense field enumeration earns its place in the absence of an output schema; nothing is padded.

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

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

With no output schema, the description usefully enumerates the returned fields, and paging is thoroughly specified in the input schema. For a read-only list endpoint with full annotation coverage, what remains unsaid is minor.

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 (npi, limit, cursor, offset, last_name, first_name) is already documented in the schema, including defaults and paging semantics. The description's field list does not add meaning about how those parameters behave, 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 ('List the practice's physicians'), clarifies the synonym 'providers', and enumerates the fields returned, so the agent knows exactly what comes back. It reads clearly against the sibling list_* tools (patients, appointments, practices) without needing an explicit contrast.

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 when-to-use guidance, no mention of when to prefer this over another endpoint, and no note on whether the filters (npi, first_name, last_name) should be combined or when to page. Usage is only implied by the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: results are limited to the API key's authorization scope, and it enumerates the returned entity fields. Pagination behavior is left to the schema rather than described.

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 front-loaded sentence names the resource, its scope and its returned fields with zero filler. The trailing endpoint reference is compact and non-redundant enough not to detract.

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, but the description compensates by listing the returned fields, and annotations cover safety while the schema covers paging. An agent has enough to call it correctly; only pagination flow details are left implicit, which the schema already handles.

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 limit, cursor and offset each fully documented (defaults, max, paging semantics), so the schema carries the parameter burden. The description adds no parameter-level meaning beyond that. Baseline 3 is appropriate when the schema does the heavy lifting.

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+resource ("List the practices") and adds the crucial scope qualifier "this API key can access," which no sibling shares. It also enumerates the fields returned, so an agent knows exactly what it gets. No other sibling tool lists practices, so it 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?

Usage is implied by the name and scope: fetch the practices available to the caller. There is no explicit when-to-use statement or routing to alternatives (e.g., elationhealth_list_physicians, which overlaps with the "physicians" field). No exclusions are given, so the agent must infer when this is the right call.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context by flagging the payload as PHI (a sensitivity/compliance consideration) and exposing the underlying Elation endpoint. It still omits auth requirements and rate limits, so it stops 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 core purpose and payload fields front-loaded, followed by the endpoint as a terse reference. No filler. The endpoint fragment is slightly cryptic 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?

With a fully described 5-parameter schema and complete annotations, the remaining gap was return values, and the description lists the problem fields (including ICD-9/10/SNOMED and status values), covering that in the absence of an output schema. Pagination mechanics are left entirely to the schema, which is acceptable but not ideal.

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 limit, cursor, offset, status, and patient are all documented in the schema itself. The description's mention of status values (Active, Controlled, Resolved) merely restates the enum and adds no syntax or semantic detail 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?

States a specific verb ('List') and resource ('one patient's problem list') and enumerates the returned fields (description, ICD codes, status, dates, synopsis). This clearly separates it from sibling list tools such as list_allergies, list_medications, and list_vitals.

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?

Scope ('one patient's problem list') implies the usage context, and the endpoint hint (GET /problems/?patient=) reinforces it, but there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives for problem data. The required patient id source is documented only in the schema, not the description.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful context that results contain PHI and what the note body looks like, but omits pagination behavior and the 'last change' filter it mentions has no corresponding parameter in the 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?

Three dense sentences, front-loaded with the core purpose and returned fields before the filter note and endpoint detail. Slight redundancy with the title's 'List a patient's visit notes' phrasing, but no wasted sentences.

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 read tool with no output schema, the description usefully summarizes the returned payload (dates, physician, signed state, structured note body) and the PHI nature of the data. Pagination options (limit/cursor/offset) are left entirely to the schema, which is acceptable but a minor 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%, so all eight parameters are already documented in the schema; baseline 3 applies. The description's date-filter mention roughly mirrors from_signed_date/to_signed_date but adds no syntax, defaults, or constraints beyond the schema, and the 'last change' reference maps to nothing.

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 names a specific verb and resource (list one patient's visit notes) and enumerates the returned fields (visit date, type, physician, signed state, note body). It implicitly distinguishes itself from elationhealth_get_visit_note and elationhealth_list_non_visit_notes by scoping to one patient's visit notes, but never names those siblings 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 that results can be filtered by signed date or last change, which hints at usage, but gives no explicit when-to-use guidance or contrast against get_visit_note (single note) or list_non_visit_notes. 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the PHI sensitivity flag and notes that chart dates accompany each reading, which is useful but limited extra 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 dense sentences with the resource and returned fields front-loaded; no filler. The trailing raw endpoint fragment ('Elation: GET /vitals/?patient=') is slightly redundant with the schema but not harmful.

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

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

With no output schema, the description usefully enumerates the returned measurement types and mentions chart dates; pagination semantics live in the fully documented schema. A brief note on ordering or response shape would close the 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?

Schema description coverage is 100%, so limit, cursor, offset, patient and visit_note are all documented in the schema. The description only reinforces the patient scoping and does not add format or interaction detail beyond the schema's baseline.

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 (one patient's vital signs) and enumerates the exact measurements returned (height, weight, BMI, blood pressure, etc.), which cleanly separates it from siblings like list_allergies and list_medications.

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 'one patient's' implies the tool is patient-scoped and that a patient id is required, but there is no explicit when-to-use guidance, no mention of when to prefer a sibling such as get_visit_note, and no stated prerequisites.

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