drchrono

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

The leading 'DESTRUCTIVE:' label matches destructiveHint=true but merely restates the annotation, adding no new behavioral detail. It does contribute the API mapping (POST /appointments) and the required-field set, but says nothing about permissions, conflict handling, or what happens to the schedule record afterward.

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 most important signal (destructive write) first. Slight redundancy in re-listing required parameters that the schema already marks as required keeps it 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 create tool with no output schema, the definition covers the inputs and endpoint but omits anything about the returned appointment identifier, whether double-booking is rejected, or required scopes. Adequate but incomplete for a mutation on a scheduling system.

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 8 parameters including the ISO datetime format and duration-in-minutes semantics. The description's restatement of the five required fields adds no meaning 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 (creates) and resource (a new appointment on the schedule), which cleanly separates it from the cluster of list_*/get_* siblings. An agent can identify the tool's function and its write nature 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 description enumerates the prerequisites (doctor, patient, office, scheduled_time, duration), which implies when the tool is callable, but it never states when to use this over alternatives or what conditions should block a call (e.g., scheduling conflicts, missing patient). Usage is implied rather than guided.

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 signals the risk profile, and the "DESTRUCTIVE:" prefix is consistent with it. The description adds the transport details (POST /patients) and required field list, but those required fields and the date format are already fully documented in the schema, so the net new behavioral context is 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 dense clauses, no filler, and the destructive warning plus core action are front-loaded ahead of the input requirements and endpoint. Every sentence earns its place.

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

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

For a mutation tool with no output schema, the description omits what is returned (e.g., a new patient id/object), duplicate-patient behavior, and any permission requirements. It is adequate to invoke the tool but leaves meaningful gaps for a write operation.

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

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

Schema description coverage is 100% with required flags and a regex pattern for date_of_birth, so the schema already carries parameter meaning. The description's field list and "yyyy-mm-dd" note merely restate 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?

"Creates a new patient record" is a specific verb+resource that distinguishes it from the read-oriented siblings (list_patients, get_patient) and from create_appointment. It does not name a sibling explicitly, but the resource noun 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?

The description states required inputs and the underlying endpoint but gives no when-to-use guidance, no prerequisites (e.g., doctor id must exist), and no exclusions relative to alternatives. An agent gets no help deciding when this tool 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=true, so the safety profile is covered. The description adds the useful scope note that the full demographic record is returned and cites the underlying endpoint, but says nothing about permissions, rate limits, or error behavior for a missing id.

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, zero waste, with the core purpose front-loaded and the API endpoint tucked into a second sentence for reference.

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 no output schema, the description conveys the resource, the lookup key, and the scope of the returned data. What the demographic record contains is left unspecified, but an agent has enough to invoke 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% with a single required 'id' parameter already documented in the schema. The description's 'by id' merely echoes the schema, 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 ('Fetch') and resource ('a single patient's full demographic record') scoped to a single record by id, which implicitly distinguishes it from the list_patients sibling. It does not explicitly name an alternative sibling, 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 phrase 'a single patient's...record by id' implies the usage context (you have a known patient id), but there is no explicit statement of when to use this versus drchrono_list_patients or drchrono_create_patient. Usage is only inferable.

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

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

Annotations declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the paginated response shape ('Returns a page plus `next`/`previous`') and the underlying endpoint, which is valuable given there is 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 compact sentences: purpose first, then return/pagination and endpoint. No filler, nothing redundant, and the most important information is front-loaded.

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

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

For a read-only list tool with fully documented parameters, the description covers purpose, filtering dimensions, and pagination behavior. With no output schema, a slightly richer account of returned fields would help, 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 all four parameters (page, doctor, patient, page_size) are already documented in the schema with defaults and bounds. The description's mention of filtering by patient or doctor adds nothing beyond that. 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?

Specific verb ('List') plus resource ('patient allergies') with the filterable dimensions named, so the agent immediately knows what it returns. It doesn't explicitly contrast itself with siblings like drchrono_list_medications or drchrono_list_problems, but the unique resource makes it distinguishable.

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 it is filterable by patient or doctor but gives no when-to-use context, prerequisites, or alternatives. There is no guidance on when a patient-scoped allergy listing is preferable to other clinical 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds real behavioral context beyond that: the mandatory date/since/date_range constraint and the paginated return shape (`next`/`previous`), which the annotation does not 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?

Short, front-loaded sentences that put the core action first and the key constraint second. The trailing 'DrChrono API: GET /appointments' line is largely redundant with the tool name and title, costing a point.

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 discloses the paginated return shape and the required date constraint, covering what an agent needs before calling. It omits page_size/page defaults and error behavior, leaving minor 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 coverage is 100%, so all eight parameters are already documented in the schema. The description restates the same constraint and filter names without adding format detail (e.g., what `since` accepts versus `date_range`), 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 and resource ('List appointments'), which cleanly separates it from create_appointment and the get_patient siblings. It does not explicitly name which sibling to use instead under what conditions, 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?

Gives the hard usage constraint (at least one of `date`, `since`, or `date_range` is required) plus the narrowing filters (doctor, patient, office), which tells an agent how to call it correctly. It stops short of stating when to prefer this over sibling list tools or what to do when results are empty.

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 real behavioral value by disclosing pagination behavior ('Returns a page plus next/previous') and the underlying DrChrono endpoint, which matters since there is no output schema. It does not mention auth or rate limits, but the pagination disclosure is a meaningful addition.

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-load the purpose and filters, followed by the return shape and endpoint. Every clause earns its place with no 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 zero-required, 100%-documented filter tool with no output schema, the description supplies the missing pagination contract and endpoint. It omits nothing an agent needs to call it correctly, though return-field detail is necessarily 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 coverage is 100%, so all six parameters including format patterns and defaults are fully documented in the schema. The description's filter list mirrors the params without adding 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 (List) and resource (clinical notes) and enumerates the filter dimensions, which distinguishes it from the many sibling list tools by resource alone. An agent can identify the tool's function 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 filter list implies when this tool is appropriate (retrieving notes scoped to a patient/date), but there is no explicit when-to-use vs alternatives or exclusion guidance. Usage must be inferred from the filter enumeration.

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 a safe read, so the bar is lower; the description nonetheless discloses the paging envelope ('Returns a page plus next/previous'), which matters because there is no output schema. It stops short of auth or rate-limit notes, but adds real context beyond the 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?

Three compact clauses with the resource and returned fields front-loaded, then the pagination behavior, then the endpoint. Zero filler or repetition.

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

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

For a two-parameter, zero-required list tool with no output schema, the description supplies the return fields and the next/previous paging contract, which is what an agent needs to page correctly. Nothing critical is missing, though filtering/sorting options are not mentioned.

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% – page and page_size are fully documented in the schema with defaults and max. The description adds no syntax or ordering detail beyond the schema, so baseline 3 is appropriate even though it references paged results.

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'), enumerates the returned fields, and cites the underlying endpoint GET /doctors. No sibling tool lists doctors, so the agent can place it unambiguously.

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 the returned fields (browse practice providers), but the description never states when to reach for this tool versus, say, get_patient, nor any prerequisite. No exclusions or alternatives are named, leaving context to inference.

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

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

readOnlyHint=true already establishes the safe-read profile, and the description adds genuinely new context: pagination semantics ('Returns a page plus next/previous') and the underlying DrChrono endpoint. It stops short of documenting rate limits or ordering guarantees, so a 4 rather than 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 short sentences, no filler, with the core purpose and filter set front-loaded. 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?

For a five-parameter, zero-required read tool with no output schema, the description covers purpose, filters, and pagination shape adequately. It could say slightly more about default page size or ordering, but nothing essential to 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%, so all five parameters (page, since, doctor, patient, page_size) are already documented in the schema; the description merely restates three of the filters. Baseline 3 is correct 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 (List) and resource (lab orders) and enumerates the filter dimensions, which cleanly separates it from siblings like drchrono_list_lab_results. It does not explicitly name a sibling to contrast against, 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?

Usage is implied by the filter list (doctor, patient, since) but the description never states when to use this over drchrono_list_lab_results or any alternative, nor any prerequisites. Adequate but with a clear gap.

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 genuine behavioral context beyond that: pagination is present and the response carries 'next'/'previous' cursors, which an agent needs in order to page. It does not cover rate limits or auth, hence 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?

Three short sentences, zero filler, purpose stated first, then response shape, then endpoint. Every sentence carries information an agent uses.

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, but the description compensates by naming the return envelope (page plus next/previous). Filters and pagination params are fully covered by the schema. Only missing nuance is default ordering or empty-result behavior, which is minor for a read-only 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 each of the five parameters is already documented with id semantics, defaults and max page size. The description only restates the filter set without adding format or syntax detail, matching the baseline for schema-covered params.

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 lab results') plus its filterable dimensions, and names the DrChrono endpoint. An agent can distinguish it from the sibling drchrono_list_lab_orders 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 listing of filter dimensions implies the usage context, but there is no explicit when-to-use, when-not, or routing to alternatives such as drchrono_list_lab_orders. Usage is left to inference from the resource scope.

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 supply readOnlyHint=true; the description adds that pagination is in play ('Returns a page plus `next`/`previous`') and identifies the underlying endpoint (GET /line_items), which confirms the read-only, idempotent profile. It stops short of documenting rate limits or the shape of each line item, so it is helpful but not exhaustive.

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

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

Two tight sentences front-load the resource and filters, then cover return/pagination and the backing endpoint. There is no filler and nothing an agent must wade through.

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 notes the page/next/previous return shape, and the 100%-covered input schema carries parameter detail. Nothing critical is missing for correct invocation, though the actual fields of a line item remain unspecified.

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, patient, appointment, and service_date. The description restates four of the six filters and adds no format or syntax detail beyond the schema, which matches the baseline 3 for a fully documented 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?

Names a specific verb and resource ('List billing line items (charges/procedures)') and enumerates the filter dimensions, so an agent immediately knows this returns charge/procedure records rather than any other sibling resource. It is clearly distinguishable from drchrono_list_appointments, drchrono_list_patient_payments, and the other list_* siblings.

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 by listing the filters available ('filterable by appointment, doctor, patient, or service date'), but it never says when to reach for this tool versus alternatives like list_patient_payments, nor does it state any exclusions or prerequisites. Usage is inferable but not 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 safety is covered. The description adds genuinely useful behavioral context beyond that: it discloses pagination semantics ("Returns a page plus `next`/`previous`") and identifies the underlying DrChrono endpoint, which helps an agent plan multi-page retrieval.

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: the core operation and filters come first, followed by return-shape and endpoint details. Every clause earns its place with no 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 low-complexity read-only list tool with full schema coverage and a declared readOnlyHint, the description covers purpose, filters, and pagination/return shape. The absence of an output schema is mitigated by the "page plus next/previous" note, leaving little an agent would need that isn't 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 all four parameters (page, doctor, patient, page_size) are already documented in the schema, including defaults and max values. The description's "filterable by patient or doctor" restates this without adding format or edge-case detail, so the baseline 3 applies.

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

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

States a specific verb and resource ("List patient medications") and its filter dimensions, which cleanly separates it from siblings like drchrono_list_allergies, drchrono_list_problems, and drchrono_list_lab_orders. 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?

The phrase "filterable by patient or doctor" implies when the tool is useful (retrieving a specific patient's or doctor's medications), but there is no explicit when-to-use/when-not guidance or reference to an alternative tool. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral value beyond that by disclosing the paginated return shape ('a page plus next/previous') and the underlying endpoint, but says nothing about auth requirements, rate limits, or result ordering.

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 the purpose stated first. The trailing API/endpoint note is marginally useful for transparency but is the least load-bearing sentence for an agent that only needs to invoke the 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?

For a read-only list tool with zero required parameters and no output schema, the description supplies what matters: what is returned and that results are paginated. Authentication and page-size limits are left implicit, but nothing critical to correct invocation 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, page_size, and show_archived are already fully documented with defaults in the schema. The description adds no parameter meaning beyond that, which lands at the baseline for high-coverage schemas.

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'), scoping the result to a single resource type. No sibling tool overlaps with it, so an agent can select it unambiguously 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 the unambiguous resource name, but the description never states when to call this versus alternatives, nor any prerequisites. Since no sibling lists offices, the lack of explicit routing guidance is a minor gap rather than a misleading one.

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 goes beyond that by disclosing the pagination return shape ('a page plus `next`/`previous`'), which is meaningful since there is no output schema, and by mapping to the underlying DrChrono endpoint. It does not mention auth requirements or rate limits, but the annotation bar is already met.

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 purpose and filter scope, then the return shape, then the API mapping. No filler or redundancy; each sentence carries distinct 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?

All five optional parameters are documented in the schema, and the description compensates for the absence of an output schema by describing the paginated return with next/previous. It is complete for a read-only list tool, though it could note ordering or default page_size behavior for full coverage.

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. The description restates the same filters (doctor, patient, since) without adding format, syntax, or interaction details 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?

The description states a specific verb and resource ('List patient payments (billing)') and immediately scopes it with the available filter dimensions. An agent can distinguish this from siblings like drchrono_list_line_items or drchrono_list_patients without opening the schema, especially with the '(billing)' qualifier.

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

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

The description names the filter options (doctor, patient, last-modified time), which implies when the tool is useful, but it offers no explicit when/when-not guidance or named alternatives among the many list_* siblings. Usage 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?

readOnlyHint=true already establishes the safety profile, so the description's job is lighter. It still adds real value beyond the annotations: it discloses the paginated return shape ('page of patients plus next/previous URLs') and the underlying endpoint (GET /patients), which the annotations do not cover.

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 waste, front-loaded with what the tool does before the return shape and endpoint. The endpoint reference is compact and earns its place by grounding the tool in the DrChrono API.

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 shape and pagination links, and it covers the filter surface. It is nearly complete, though it omits default page size behavior and sorting, which schema notes only partially cover.

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 with formats (ISO timestamp for since, yyyy-mm-dd pattern for date_of_birth, max 250 for page_size). The description only restates the filter categories and adds no format or semantics 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+resource ('List/search patients in the practice') and enumerates the filterable dimensions, so the agent knows exactly what the tool retrieves. It differentiates from the sibling get_patient only implicitly through 'list/search', and never names an alternative, 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 word 'search' implies broad, filtered retrieval, which is adequate context, but there is no explicit when-to-use guidance, no statement about when to prefer drchrono_get_patient for a single record, and no prerequisites. Usage is left to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context by disclosing the paginated return shape ('a page plus next/previous') and the underlying API call, which goes beyond what the annotations and schema alone 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?

Three short sentences, front-loaded with the core purpose, followed by return format and API endpoint. No sentence is wasted and the structure is easy to scan.

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?

There is no output schema, but the description compensates by mentioning the paginated return shape and the endpoint. Combined with a fully documented input schema, it is complete enough for an agent to call correctly, though it could say slightly more about defaults or ordering.

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 semantics. The description only restates that filtering is possible by patient or doctor and adds no syntax, format, or default details 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?

Specifies a clear verb ('List') and resource ('problem-list entries (diagnoses)'), with the parenthetical synonym disambiguating it from sibling list tools like list_allergies or list_medications. An agent can identify exactly what this tool returns 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?

States the filtering options ('filterable by patient or doctor'), which gives clear context for when to use it. However, it does not name alternative tools or explicit when-not-to-use conditions, so it stops short of full routing guidance.

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