DrChrono MCP by usefulapi

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

The annotations already declare destructiveHint=true, and the description's "DESTRUCTIVE" label largely restates that. It adds the API mapping (POST /appointments) and the required payload shape, but discloses nothing about auth requirements, double-booking/conflict behavior, or side effects like notifications.

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 destructive warning, then requirements, then endpoint. Every sentence carries information and nothing is padded.

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

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

For a destructive create tool with no output schema, the essentials (required fields, endpoint) are present, but the description omits what the call returns (e.g., the new appointment id) and how scheduling conflicts or invalid doctor/office ids are handled, leaving meaningful gaps.

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 eight parameters with types and formats. The description's restatement of the five required fields and the ISO datetime/minutes notes duplicates the schema rather than adding new semantics, 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 (creates) and resource (appointment on the schedule), which cleanly separates it from the list_appointments sibling. An agent can identify the operation 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?

It enumerates the required inputs (doctor, patient, office, scheduled_time, duration), which acts as an implicit precondition for calling it, but it never states when to use this versus alternatives such as checking existing appointments first, nor any exclusions.

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

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

The destructiveHint=true annotation already declares this is a mutating operation, and 'DESTRUCTIVE: creates a new patient record' restates that rather than adding to it. The POST /patients endpoint reference is mildly useful for traceability, but traits like duplicate-patient handling, failure behavior, or required permissions are unaddressed, so the annotation remains the primary source of behavioral signal.

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 with the destructive warning front-loaded, which is the right ordering for a write tool. Listing the required fields arguably duplicates the schema's required array, costing a bit of density, but nothing is padded.

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

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

For a 7-parameter mutation tool with no output schema and only a destructiveHint annotation, the definition covers required inputs and date format but leaves the agent uninformed about what is returned (e.g., a new patient id), whether duplicates are rejected, and what authorization is needed. Adequate but with real gaps.

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 repeats the five required fields and the yyyy-mm-dd format, which the schema (including a regex pattern) already documents more precisely, so it adds no meaning 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 — 'creates a new patient record' — which cleanly separates it from siblings like drchrono_get_patient and drchrono_list_patients. It stops short of explicitly naming those alternatives, so it is clear but not fully sibling-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 description says nothing about when to use this tool versus the read siblings, nor any prerequisite such as the doctor id needing to exist first. The only implied guidance is that five fields must be supplied, which is already a schema concern rather than usage guidance.

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 underlying endpoint (GET /patients/{id}), which is mildly useful context, but says nothing about auth requirements, 404 behavior for bad ids, or rate limits.

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 operation and scope front-loaded; every clause carries information and nothing is padded.

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

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

For a simple one-parameter read tool with full schema coverage and a readOnly annotation, this is nearly sufficient; 'full demographic record' hints at the payload. No output schema exists, yet the description doesn't sketch the return shape or error cases, which is the only 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% and the single parameter is fully documented as an integer patient id. The description's 'by id' adds no format or constraint 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 (Fetch), resource (a single patient's full demographic record), and scope qualifier ('single', 'by id'), which cleanly separates it from the sibling list_patients. An agent can pick this over the list variants 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 'single patient ... by id' phrasing makes the usage context clear: call this when you already have a patient id and want one record rather than a listing. It never explicitly names list_patients as the alternative or states exclusions, so it stops short of full when/when-not guidance.

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?

Annotation readOnlyHint=true already establishes the safe-read profile, and the description adds genuinely new behavior: results are paginated with next/previous links, which matters because there is no output schema. It stops short of stating defaults or max page size (those live in the schema), so a 4 rather than 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?

Three short clauses covering purpose, filtering, and return shape, with the core action front-loaded. Every sentence earns its place and there is 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 read-only list tool with full schema coverage and an annotation carrying the safety profile, the description supplies the remaining gap (pagination/next-previous return shape). It is essentially complete, though it omits default page size and ordering, which an agent might want.

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 page, page_size, doctor, and patient with defaults and bounds. The description's "filterable by patient or doctor" restates the schema rather than adding format or constraint 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 patient allergies") and names the DrChrono endpoint, which makes it unmistakable against list siblings like list_medications or list_problems. It does not explicitly contrast itself with those siblings, so it falls just short of a 5.

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

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

The description mentions that results are filterable by patient or doctor, which hints at usage, but gives no when-to-use/when-not guidance and never names an alternative tool for retrieving allergy data by another route. Nothing tells the agent when this list is the right call versus a more targeted fetch.

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 establish readOnlyHint=true, and the description adds genuinely useful behavior beyond that: the mandatory date/since/date_range constraint and the fact that results are paged with `next`/`previous` links. It omits rate limits or default page-size behavior, but the paging disclosure is real added value.

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-loaded with the purpose, then the hard constraint, then optional filters and return shape – four tight sentences with no filler. Slight redundancy in restating the date/since/date_range rule that the schema already carries.

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 steps in to explain the paged return envelope (`next`/`previous`), and it covers the required-parameter rule and all filtering dimensions. Only minor gaps remain (default page size, ordering), which are low-stakes for a read-list tool.

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

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

Schema description coverage is 100%, so formats, defaults, and the exclusivity rule are already fully documented in the schema. The description reiterates the one-of-three requirement but contributes no syntax or edge-case meaning beyond it, 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?

Clear verb+resource: 'List appointments', reinforced by the underlying endpoint GET /appointments. It is distinguishable from the other list_* siblings by resource, though it does not explicitly contrast itself with any of them.

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 surfaces the key selection constraint imposed by the API – that one of `date`, `since`, or `date_range` must be supplied – and lists the optional narrowing filters (doctor, patient, office). It stops short of naming an alternative tool or explaining when a different listing approach would be preferable.

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?

With readOnlyHint=true already covering the safety profile, the description still adds real behavioral detail: the response is paginated and includes `next`/`previous` links, and it discloses the underlying DrChrono endpoint (GET /clinical_notes). It does not cover rate limits or auth scope, but the added context is solid.

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 tightly written sentences: capability and filters first, pagination/endpoint second. 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?

No output schema exists, and the description partially compensates by describing the paged return shape and next/previous links. Combined with full schema coverage for all 6 params, an agent has enough to invoke it correctly, though filter-combination semantics remain unstated.

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 each of the 6 parameters is already documented with format and defaults. The description restates the filterable dimensions but adds no format or interaction detail (e.g., whether patient and date_range can combine), 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?

Clear specific verb+resource ('List clinical notes') with an enumeration of the filter dimensions (patient, date, date range, last-modified). It does not need to name a sibling since no other tool targets clinical notes, but it also does not explicitly differentiate itself from the other list_* 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?

It states what can be filtered but gives no guidance on when to choose this tool over siblings or on prerequisites (e.g., whether a patient id is needed for meaningful results). Usage is only implied by the filter list.

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 cover the safety profile (readOnlyHint=true), so the bar is lower, and the description still adds the pagination envelope ('page plus next/previous'), the returned fields, and the backing endpoint GET /doctors. It stops short of noting auth requirements or default/max page sizes.

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: purpose and returned fields first, then pagination behavior, then the API mapping. Every sentence carries information an agent can act on.

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 supplies the return shape (id, name, specialty) and the pagination contract, which is everything needed to call and page through a read-only list endpoint. Nothing material is missing for a tool of this complexity.

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 page and page_size fully documented including defaults and the max-250 bound, so the description need not repeat them. It adds nothing about parameter semantics beyond the schema, which is the expected baseline here.

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 providers/doctors in the practice') and enumerates the returned fields (id, name, specialty). The resource is unmistakably distinct from every sibling, which all target different entities (appointments, patients, offices, etc.).

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 resource rather than stated: an agent can infer this is the lookup for doctor IDs needed by other calls. No explicit when/when-not guidance or reference to an alternative tool is provided, though no sibling lists the same resource.

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 readOnlyHint=true; the description adds real value beyond that by disclosing the paginated return shape (`next`/`previous`) and the upstream API mapping, which tells the agent the result is paginated. It still omits auth/permission requirements, so not 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 compact sentences, with the core purpose front-loaded and no filler; every clause carries 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?

With no output schema, the description usefully supplies the return structure (page plus next/previous) for a 5-param read tool. It lacks guidance on rate limits or authentication, but the essentials for correct invocation are 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 coverage is 100%, so the baseline is 3. The description's filter list maps clearly onto the schema params and glosses `since` as 'last-modified time', but adds little syntax or format detail beyond what the schema already documents.

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 lab orders') and enumerates the filter dimensions, so an agent knows exactly what it does. It does not, however, distinguish itself from the close sibling drchrono_list_lab_results, so it falls short of a 5.

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

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

The description implies the tool is for filtered listing but gives no when-to-use guidance and never mentions when to prefer a sibling such as drchrono_list_lab_results. The agent is left to infer routing.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine context beyond that: it discloses the paginated return shape ("Returns a page plus `next`/`previous`") and the underlying endpoint, which helps an agent understand behavior not captured in annotations.

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 zero waste: purpose and filters first, return shape second, API reference last. Front-loaded and 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 usefully compensates by describing the return envelope (page plus next/previous). Combined with a fully documented schema, an agent has enough to call it correctly, though return field details are absent.

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

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

Schema description coverage is 100%, so every parameter (page, order, doctor, patient, page_size) is already documented in the schema. The description restates the filter parameters but adds no syntax, format, or constraint beyond what the schema provides, 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?

The description names a specific verb and resource ("List lab results") and enumerates the filter dimensions (doctor, patient, lab order), which clearly separates it from drchrono_list_lab_orders. It stops short of explicitly calling out that sibling distinction, so it is clear but not maximally 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?

It states the available filters, which implies when the tool is useful (retrieving lab results by those dimensions), but gives no explicit when-to-use/when-not-to-use guidance or named alternatives among the many sibling list tools.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real behavioral context beyond that: results are paged and include `next`/`previous` links, and it names the underlying endpoint (GET /line_items). It stops short of stating default page size or ordering, but it goes past 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?

Two tight sentences: purpose and filterability first, then return shape and endpoint. Nothing redundant 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?

With no output schema, the description carries return-shape information and does so (page plus next/previous). Combined with full schema coverage this is nearly complete; a note on default page size or result ordering 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 all six parameters are already documented in the schema. The description only echoes the filterable dimensions without adding format or syntax 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 (List) and resource (billing line items), and disambiguates the resource by glossing it as charges/procedures. No sibling covers line items, so the name plus this gloss cleanly distinguishes it from the appointment/patient/medication listers.

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 lists the filter dimensions (appointment, doctor, patient, service date), which implies when it is useful, but it offers no when-not guidance or explicit alternatives to route against. 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?

readOnlyHint=true already covers the safety profile, but the description adds useful behavior beyond annotations: it discloses the paginated return shape ('a page plus next/previous') and the underlying API endpoint. This is meaningful context for a list tool with no output schema.

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

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

Two short sentences, front-loaded with the core purpose and pagination behavior. Nothing is redundant or padded.

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

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

With no output schema, the description partially compensates by describing the pagination envelope, and all four params are covered by the schema plus a readOnly annotation. It stops short of describing what a medication record contains, leaving a small gap for a data-listing tool.

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

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

Schema description coverage is 100%, so page, page_size, patient and doctor are already documented. The description restates that patient/doctor act as filters but adds no syntax, format, or default 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 patient medications') plus the filter scope (by patient or doctor). The resource is unambiguous and clearly distinct from siblings like list_allergies or list_appointments, though it doesn't explicitly contrast itself with any of them.

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

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

The description explains what can be filtered but gives no guidance on when to use this tool versus alternatives (e.g. get_patient, list_patients) or when-not to use it. Usage is only inferable from the tool 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 only declare readOnlyHint=true; the description adds the pagination contract ('returns a page plus next/previous') and pins the underlying endpoint (GET /offices). That is real behavioral context beyond the annotations. It does not mention auth or rate limits, 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?

Two sentences, zero filler, with the core purpose front-loaded and the return shape and endpoint following. 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?

No output schema exists, so the description usefully communicates the return shape (page plus next/previous) while the schema fully covers inputs. For a simple read-only list tool this is close to complete, missing only archived-handling or auth caveats.

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 defaults and bounds spelled out for page, page_size, and show_archived. The description adds nothing about the parameters, 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 offices/locations') plus the underlying API call. An agent can immediately tell this is a read of the office/location directory and distinguish it from the many list_* siblings covering other resources.

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 versus alternatives, no prerequisites, and no note on how pagination parameters should be driven. Usage is only implied by the name. There is no sibling tool that lists offices, so the omission is less costly, but the description still provides nothing.

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 genuinely new behavioral context beyond that: results are paginated and the response carries `next`/`previous` cursors, plus the underlying endpoint. It doesn't mention auth scopes or rate limits, but for a read-only list this is solid 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 plus an endpoint reference; the core purpose and filters are front-loaded and nothing is padded. Every clause carries information the agent can use.

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 present, the description responsibly sketches the return shape (a page plus next/previous) and confirms all five parameters map to documented filters. The only shortfall is the absence of any note on total counts or error/empty-result behavior.

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 (page, since, doctor, patient, page_size) is already documented in the schema. The description restates the filterable fields at a high level without adding format or semantics 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 ("List patient payments") and adds a domain qualifier ("billing") that pins down what kind of records these are. No sibling tool overlaps, but the description never explicitly contrasts itself with other list tools such as list_line_items or list_patients, so it stops short of full sibling differentiation.

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 filter dimensions (doctor, patient, last-modified time) imply the situations in which the tool is useful, but there is no explicit when-to-use/when-not-to-use guidance and no mention of when to page through results versus narrowing by filter. 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 genuinely useful behavior beyond that: paginated return with `next`/`previous` URLs, and the underlying REST endpoint (GET /patients), which helps an agent reason about page traversal.

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 tight sentences with the purpose and filters front-loaded, followed by return shape. The trailing 'DrChrono API: GET /patients' is mildly redundant but adds traceability; nothing else 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?

With no output schema, the description compensates by describing the return ('a page of patients plus next/previous URLs'), and the schema fully documents all 8 optional parameters. An agent has enough to call it correctly, though pagination defaults (max 250) live only in 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 every parameter (page, page_size, since, doctor, gender, first_name, last_name, date_of_birth) is already documented with formats and bounds. The description only restates the filter set at a high level and adds no syntax or semantic detail beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('List/search patients') plus scope ('in the practice') and enumerates the filter dimensions. It's clearly the collection endpoint as opposed to drchrono_get_patient, though it never names the sibling explicitly to lock that distinction in.

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 'List/search... filterable by...' and the pagination note, so an agent can infer it's for bulk/retrieval rather than creating or fetching one patient. But there is no explicit when-to-use vs drchrono_get_patient or drchrono_create_patient, and no exclusions or 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 the safety profile is covered. The description adds value beyond that by disclosing the return shape ('Returns a page plus next/previous'), which matters because there is no output schema. Auth/rate-limit context is absent but not critical here.

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 compact sentences, front-loaded with the core verb+resource, then return shape, then API mapping. Every sentence earns its place with zero 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 read-only paginated list tool with full schema coverage and annotations covering safety, the description supplies enough: resource meaning, filter dimensions, and pagination return shape despite no output schema. It stops short of noting default sort or whether filters combine, but nothing essential 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 the schema fully documents page, page_size, doctor, and patient. The description only restates the patient/doctor filtering that the schema already carries, adding no syntax or format 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 (problem-list entries/diagnoses), and usefully disambiguates the resource with the parenthetical '(diagnoses)'. It does not explicitly distinguish itself from the many sibling list_* tools, but the resource name is self-evidently distinct enough for routing.

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 notes it is 'filterable by patient or doctor', which implies usage context, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many sibling list tools. 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.