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

The description adds the caveat that this is an approximation based on on-file data and not a real-time check, which is beyond the readOnlyHint annotation. It doesn't contradict annotations and provides context about the reliability of the result.

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

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

Two sentences, front-loaded with the main action, and the caveat is succinctly stated. No wasted words.

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

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

For a single-parameter read-only tool with no output schema, the description covers the essential purpose and the approximation caveat. It could mention what the response contains, but that's minor given the simplicity.

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?

The input schema already describes patientId as 'Tebra patient ID' with 100% coverage. The description does not add additional parameter semantics beyond what the schema provides, so it's at 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?

The description clearly states the verb 'check' and the resource 'insurance eligibility' for a Tebra patient, and specifies it examines on-file policies and authorization history. It distinguishes from a real-time check, but does not explicitly name a sibling tool, so it's clear but not fully differentiated.

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

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

The description notes it's an approximation based on on-file data, not a real-time payer eligibility check, which implies when to use it (quick check) and when not (real-time need). However, it does not name an alternative tool or provide explicit 'when not to use' guidance, so it's only implied.

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=false and destructiveHint=false, so 'Create' is consistent and no contradiction exists. The description adds the useful 'either endDate or duration' constraint, but it does not disclose side effects, permission requirements, or what the response contains. With annotations covering basic safety, this is adequate but not rich.

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 with zero filler: action first, required inputs second, optional inputs third. Every clause earns its place and the key creation constraint 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 13-parameter tool with no output schema, the description covers the essential required fields, the critical endDate/duration constraint, and optional categories. It does not mention the return value, which an agent may need to know, but this is a minor gap since the schema and annotations already carry significant detail.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by explicitly stating that either endDate or duration is required—something the schema leaves ambiguous since both are optional—and it groups the optional fields (reason, mode, status, notes), which aids selection.

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

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

Description states a specific verb and resource: 'Create a new patient appointment in Tebra.' This clearly distinguishes it from siblings like update_appointment and delete_appointment by emphasizing 'new' and listing creation-specific required fields.

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 clearly implies use when creating an appointment and lists the necessary inputs, but it does not explicitly contrast with alternatives such as update_appointment or delete_appointment, nor does it provide when-not-to-use guidance. It conveys context but leaves exclusion logic unstated.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds a useful clarification about the color format, but does not disclose other behavioral aspects such as potential duplicate handling, output/return behavior, or authentication requirements. There is no contradiction with 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?

The description is two sentences with no filler. It front-loads the purpose and includes only the most important non-obvious parameter detail (color format). Every word 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 simple creation tool with rich schema descriptions and annotations, the description covers what is needed. It lacks an explicit note about return values or unique constraints, but the verb 'Create' plus the schema and annotations give sufficient context for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by clarifying that color is a Tebra color code number, not hex, which goes beyond the schema's 'Optional Tebra color code (integer)'. The other parameters are adequately described in 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?

The description states a specific action ('Create') and resource ('appointment reason') with the key fields involved. It clearly differentiates from sibling create tools like tebra_create_appointment and tebra_create_patient by naming the unique resource.

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 when a new appointment reason is needed, but it does not explicitly state when to use this tool over alternatives or mention related tools like tebra_get_appointment_reasons for checking existing reasons. No exclusions or prerequisites are provided.

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

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

The description adds meaningful behavioral detail beyond the annotations: file type is inferred from the extension, documentLabel must be a CamelCase enum value, spaces are stripped automatically, and 'Other' is a safe fallback. This is useful context on top of the readOnlyHint/idempotentHint/destructiveHint 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?

The purpose statement is front-loaded in one precise sentence, and the follow-up sentence provides high-value enum guidance. The list of examples is long but directly necessary for correct invocation, and no sentence is wasted.

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

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

For an 8-parameter create operation with no output schema, the description plus schema cover everything needed to call the tool correctly: required parameters, accepted file types, base64 content format, label enum constraints, and practiceId auto-resolution behavior. No essential invocation detail 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?

The input schema already documents all eight parameters, so the baseline is 3. The description adds value by explaining documentLabel semantics (CamelCase, no spaces, enum examples, fallback to Other) and how fileName's extension determines the accepted file type, which goes beyond the schema descriptions.

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

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

The description uses a specific verb and resource: 'Upload a document to a patient record in Tebra' and specifies the mechanism (base64 content) and accepted file types (PDF, JPG, PNG, TIFF). This clearly differentiates it from the only close sibling (tebra_delete_document) and from patient/appointment creation 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?

The intended use is clear: when a document needs to be attached to a Tebra patient record. It does not explicitly discuss alternatives or when not to use the tool, but no close alternative exists among the siblings, and the guidance to use 'Other' when unsure helps the agent choose an appropriate label.

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=false, idempotentHint=false, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: each procedure becomes a service line with diagnosis mapping, the practice requirement on most accounts, and the return of the created encounter ID. It does not contradict 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 sentences with zero filler. The primary purpose is front-loaded, followed by the critical service-line behavior and the practice requirement, then the return value. 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 12-parameter tool with no output schema, the description covers the essential behavior: creation, service-line structure, diagnosis mapping, and practice requirement. It doesn't explicitly mention error conditions or default status, but the schema covers the 'Draft' default and enum options. The description is adequate for an agent 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 coverage is 100%, so all parameters are documented. The description adds meaning beyond the schema by explaining how diagnoses and procedures interact (encounter-level diagnoses applied per service line, per-procedure override) and the strong recommendation for practice identification. This helps the agent understand the intent behind parameter combinations.

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

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

The description clearly states the action: 'Create a new encounter (superbill) in Tebra with diagnoses and procedures.' It uses a specific verb and resource, and distinguishes itself from sibling tools like tebra_update_encounter_status or tebra_get_encounter by focusing on creation. The mention of 'superbill' adds domain specificity.

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 (when you need to create an encounter) but does not explicitly state when not to use it or mention alternatives. It gives parameter-level guidance (practiceName/practiceId strongly recommended) but lacks tool-selection context compared to sibling operations. No exclusions or alternative tool names are mentioned.

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

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

Annotations already indicate readOnlyHint=false (mutation) and idempotentHint=false. The description adds a key behavioral detail: the practice is required but defaults to the account's first practice if practiceName/practiceId are omitted. This goes beyond annotations and helps the agent understand a non-obvious default. No contradiction with 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 sentences, each purposeful. The first states the core function, the second highlights the practice requirement/default. No filler, and the most critical usage note 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?

The tool has 20 parameters and nested objects, and no output schema. The description does not mention what the tool returns (e.g., patient ID) or any post-creation behavior. Since there is no output schema, the description carries the burden of explaining the result, which it omits. This is a notable gap for a create 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%, so the schema already documents every parameter. The description adds no additional semantic detail beyond grouping parameters into categories; it does not clarify edge cases or relationships that the schema misses. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Create' and the resource 'new patient in Tebra', and enumerates the major data categories (demographics, address, insurance, guarantor). This distinguishes it from siblings like tebra_update_patient and tebra_get_patient, which are obviously different operations.

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 this is for creating new patients but does not explicitly state when to use it instead of alternatives such as tebra_update_patient or tebra_search_patients. It gives no 'when-not-to-use' guidance, leaving the agent to infer from the tool name and sibling context.

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

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

Annotations indicate non-idempotent, non-read-only behavior, and the description enriches this substantially by explaining the double-charge risk and the lack of an idempotency key. It also advises checking tebra_get_payments before resubmission, adding operational context beyond the structured metadata.

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

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

The description is compact and front-loaded with the core purpose, followed by essential caveats about retries and idempotency. Every sentence contributes value; there is no redundant or filler content.

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

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

Given the tool has 9 parameters and no output schema, the description covers the action, supported methods, failure handling, and duplicate mitigation. It doesn't describe the response format, which could be a minor gap for agents expecting to parse a created entity, but the critical operational details are well addressed.

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 9 parameters are already documented with descriptions. The description adds meaningful extra semantics, particularly around referenceNumber for duplicate detection and the optional linking to appointment/practice. This goes beyond the schema, providing practical guidance on how parameters relate to real-world usage.

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 clear, specific action: 'Create a new patient payment in Tebra' with a verb and resource, and explicitly lists the supported payment methods. It distinguishes itself from the sibling 'tebra_get_payments' by being the creation counterpart, making its purpose 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?

Provides explicit guidance on when to use the tool (creating a payment) and critical failure-handling instructions: not to retry after timeout/server error, and to check tebra_get_payments on unknown outcomes to avoid double-charging. It also recommends supplying referenceNumber for duplicate detection. It doesn't explicitly state when not to use it, but the context is clear for a creation operation.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds the stronger nuance 'irreversible' and the suggestion to use an alternative for history, which goes beyond the annotations. No contradiction.

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

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

Two sentences, front-loaded with the core action and the irreversible warning, followed by the alternative. Zero wasted words.

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

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

For a single-parameter delete with no output schema, the description covers the essential: action, irreversibility, and alternative. It does not detail error handling or return values, but those are minor given the tool's simplicity.

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%: appointmentId is described as 'Tebra appointment ID to delete', which is sufficient. The description adds no extra parameter details, but the schema already handles it. 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 (delete) + resource (appointment) + identifier (appointment ID). Clearly distinguishes from tebra_update_appointment_status by naming the alternative and its purpose. No ambiguity.

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

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

Explicitly says when to use (permanent deletion) and when not to (when history is needed), and names the alternative tool (tebra_update_appointment_status with Cancelled). Provides a clear decision rule.

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 flag destructiveHint=true, but the description adds the explicit consequence that deletion is irreversible, which is valuable cautionary context beyond the structured hint. It doesn't cover side effects or permissions, but the irreversibility warning is meaningful.

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 filler, and the key warning ('This is irreversible') is front-loaded. The description is as compact as it can be while remaining informative.

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-parameter deletion tool with strong annotations (destructiveHint, idempotentHint), the description together with the schema is largely complete. It omits output/error behavior, but that is a minor gap for such a simple operation.

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

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

Schema coverage is 100% and the schema already describes documentId as 'Tebra document ID to delete.' The description merely restates 'by document ID' and adds no format, validation, or sourcing details.

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

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

States a specific action (delete), a specific resource (document), and the key by which the document is targeted (document ID). It is also clearly distinct from siblings like tebra_delete_appointment and tebra_create_document.

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: call this when a specific Tebra document must be removed. However, it gives no explicit when-not-to-use guidance or mention of alternatives, leaving tool selection mostly 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 mark this as read-only, and the description adds meaningful behavior: it returns a page plus a continuation key, requires startKey from the prior response, and documents the default roster entry field set. This goes beyond the annotations and helps the agent predict the response shape even without an 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?

Three tight sentences front-load the core purpose, then explain pagination, and then describe the default field set and how to extend it. There is no filler, repetition, or content that belongs only in the schema.

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 bulk-read tool with full parameter documentation, readOnlyHint, and no output schema, this description is complete. It covers the return shape, pagination mechanism, default fields, and how to request additional fields, leaving no critical gap for an agent deciding to call it.

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 are already documented with their own descriptions. The description reinforces startKey and fields usage but does not add significant new semantic detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with 'Get all patients in bulk with pagination,' which gives a specific verb, resource, and scope. It clearly distinguishes this from sibling tools like tebra_get_patient and tebra_search_patients by emphasizing bulk retrieval of all patients rather than a single record or a filtered search.

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

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

The description gives clear operational context: use it for bulk patient retrieval, follow pagination with startKey, and pass fields for additional columns. It does not explicitly name alternatives or state when not to use it, but the bulk-vs-single distinction is strongly implied by the wording.

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

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

Annotations already declare readOnlyHint=true, and the description does not contradict this. It adds details about the response content (recurrence rules, group data, resource slots) but does not disclose additional behavioral traits such as authentication requirements, rate limits, or side effects. Since the annotations cover the read-only aspect, a 3 is appropriate for adding only marginal behavioral 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?

A single sentence that front-loads the verb and resource, then packs the key inclusion details. There is zero waste; every word adds value.

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-resource tool with two well-documented parameters and no output schema, the description fully covers what the agent needs to call it correctly: it specifies the identifier and the type of data returned. 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%: both parameters (appointmentId and fields) have descriptions in the schema. The tool description does not add extra parameter-level meaning beyond what the schema already provides, so the baseline of 3 applies. The fields parameter's PHI warning is already in the schema description, not the tool description.

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

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

The description uses a specific verb ('Get') with a clear resource ('full detail for a single appointment by ID') and enumerates the included content (recurrence rules, group data, resource slots), distinguishing it from sibling tools like tebra_get_appointments that list appointments. It is immediately clear what the tool does and how it differs from a list operation.

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: this tool is for retrieving the full detail of a single appointment by ID, while tebra_get_appointments likely handles listing. It provides clear context for when to use it but does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context by stating that it returns all reasons and listing what those returns contain, going beyond the schema without contradicting 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?

The description is three short sentences with no filler. The core action is front-loaded, the return values are listed immediately after, and the practical dependency on appointments is stated last. 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 read-only lookup with one optional parameter and no output schema, the description is complete: it tells the agent what the tool returns, why it is needed, and the only decision point (which practice). No critical information is missing for correct invocation.

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

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

Schema coverage is 100%, with the sole parameter practiceId already described as defaulting to the account's first practice. The description adds no new parameter-level meaning, so the baseline score of 3 is appropriate given that the schema handles semantic documentation.

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

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

The description clearly identifies a specific resource (appointment reasons configured in the practice) and a specific action (Get all), then enumerates the returned fields (IDs, names, default durations, color codes). This fully distinguishes the tool from its siblings, such as create_appointment_reason and get_appointments, without ambiguity.

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 explicitly states that this tool is 'Needed to create appointments with a reason,' giving an agent a clear context for when to invoke it. It does not list alternatives or exclusions, but for a simple read-only lookup this is sufficient practical 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?

The readOnlyHint and openWorldHint annotations already establish that this is a safe read operation. The description adds one useful behavioral nuance—the provider filtering workaround—but does not disclose other behavior such as result format, paging, or limits. This is acceptable but not rich.

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 with no wasted words. The primary purpose and date-range scope come first, followed by the filter capabilities and the most important parameter nuance. 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 read-only list tool with a fully self-documenting schema, the description is sufficient for correct invocation: it names the scope, the available filters, and the provider-filtering caveat. The lack of an output schema and any mention of response shape is a minor gap, but not critical given the strong schema and annotation 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 the schema already documents all 17 parameters. The description summarizes filter categories and restates the resourceName/provider guidance already present in the schema, but adds little new parameter-level meaning beyond that.

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

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

The description clearly states the verb and resource: getting appointments from Tebra within a date range, with filtering options. It is easy to distinguish from a detail-fetch tool, though it does not explicitly name sibling tools like tebra_get_appointment_detail, 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 description gives clear usage context: use this to retrieve date-filtered appointment lists with multiple filter dimensions. It also provides a useful provider-filtering rule (use resourceName with provider full name because the WSDL has no provider ID filter). It does not explicitly state when not to use it or name alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to restate safety. The description adds valuable behavioral context beyond the annotations, notably the server-side 60-day limit on posting-date ranges menus, and it explains what kind of charge details the result contains. No contradiction with annotations exists.

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

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

The description is three sentences long, front-loads the core purpose in the first sentence, and gives a concise summary of outputs and a key limitation. There is no filler, repetition of schema properties, or unnecessary detail that would burden an agent selecting or invoking 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 filtered-list tool with 19 optional parameters, the description covers the core inputs, the output shape, and an important server-side constraint. There is no output schema, but the description names the key returned groups (payer, adjudication, adjustment reasons, amounts, balances). Pagination and default field-set behavior are not described, but the annotations and schema already mitigate most 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 the schema already documents all 19 parameters with meaningful descriptions. The tool description mostly summarizes filter categories that the schema already names individually, adding little new parameter-level meaning; the 60-day caveat is also already present in the posting-date parameter descriptions.

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

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

The description clearly states a specific verb and resource: 'Get charges from Tebra', and lists both the available filter dimensions and the returned charge details. It is distinguishable from sibling tools like tebra_get_payments and tebra_get_transactions because it explicitly targets 'charges', though it does not name or contrast those alternatives.

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 tool's use is implied by the description: an agent can tell it is meant for retrieving charge records using various filterscombinations and seeing payer/adjudication details. However, there is no explicit guidance about when to choose this over related tools such as get_payments or get_transactions, and no stated exclusions or alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds the list of returned fields, which provides context about the response content but not about any side effects or edge-case behaviors. It does not contradict the annotations and offers modest additional 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?

The description is a single, front-loaded sentence that states the purpose and key outputs without redundancy. Every word earns its place, making it highly efficient and easy to parse.

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 getter with two parameters and no output schema, the description is mostly complete. It lists several key fields but not exhaustively, and does not mention error behavior (e.g., 404 on missing ID). However, the fields parameter allows custom selection, mitigating the need for a full field list. The annotations cover safety, so the definition is adequate for an agent 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 coverage is 100%, with both parameters well-described: encounterId is simply a Tebra ID, and fields includes dotted-path guidance and a PHI warning. The description's mention of the default field set adds a small amount of context beyond the schema but does not significantly enhance parameter understanding.

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 uses a specific verb (Get), names the resource (encounter details), and lists the key returned fields (patient, providers, status, service dates, place of service, service line IDs). This clearly distinguishes it from sibling tools like get_charges or get_appointment_detail, which target different 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?

The description implies usage when you need encounter details by ID, but it does not explicitly mention alternatives or conditions for not using this tool. There is no guidance on choosing between this and related tools like tebra_get_appointment_detail, so the usage context 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?

The annotations already declare readOnlyHint and openWorldHint, covering the safety profile. The description adds that it returns the complete set of registered vendors with IDs, but it does not describe response shape, pagination, or potential scale. This is acceptable but not rich.

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 with no wasted words. Every element—action, scope, qualification ('registered'), and output ('with their IDs')—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 zero-parameter, read-only list tool, this is nearly complete: annotations handle safety, and the description states scope and key return content. The main gap is the lack of an output schema and no mention of the exact list shape or pagination, but that is a minor omission for such a simple 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?

The tool has zero parameters and an empty schema, so there is little to document. The description's 'all registered' usefully reinforces that no filtering parameters exist and the result is the complete vendor collection, adding meaning beyond the empty 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?

The description uses a specific verb ('Get') and a clear resource ('all registered external vendors in Tebra') while also indicating the key output ('with their IDs'). It is immediately distinguishable from sibling tools like tebra_register_external_vendor.

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 'all registered external vendors' gives clear context: this tool is for retrieving the full vendor list. It does not explicitly name alternative tools or exclusion conditions, but there is no competing list tool for external vendors among the siblings, so the guidance is adequate.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true; the description adds a genuinely non-obvious data-visibility quirk: 'Insurance policy and group numbers are omitted unless named in fields'. This materially affects what the agent receives. It does not disclose error behavior or identifier-precedence semantics, but for a read-only fetch the disclosure is strong.

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 sentences, front-loaded with the action and identifier alternatives, then return contents, then the sensitive-data caveat. Every sentence earns its place with no filler or repetition of schema text.

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

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

For a read-only fetch with four well-documented parameters, the description covers return content categories and the fields caveat, and the annotations carry the safety profile. The main gap is the identifier requirement: required is empty and the description does not state that exactly one of patientId/externalId should be supplied or what happens if both are passed.

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 adds meaning by tying the fields parameter to the insurance/group-number omission behavior and by framing externalVendorId as optionally scoping the externalId lookup. It stops short of explaining precedence if both patientId and externalId are supplied, which the required:[] schema leaves ambiguous.

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 a full patient record from Tebra' by patientId or externalId. The scope phrase 'full patient record' plus the listed contents (demographics, contact, cases, insurance, authorizations) distinguishes it from subset siblings like tebra_get_patient_authorizations and from search/bulk tools. Clear and actionable without needing to open the schema.

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

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

The lookup methods ('by patient ID, or by external system ID') imply when the tool applies, but there is no explicit when-to-use vs alternatives such as tebra_search_patients (when no ID is known) or tebra_get_patient_authorizations (authorizations only). No exclusions or alternative routing are given, so usage context 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 mark this as read-only and open-world, and the description adds meaningful behavioral context beyond them: it returns computed status values (active/exhausted/expired/pending), payer contact info, and an expiring-soon warning. This helps set expectations without contradicting 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?

Two sentences with no filler. The first sentence front-loads the core action and scope; the second concisely enumerates the useful returned fields. 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 one simple parameter, no output schema, and read-only annotations, the description covers the key return aspects: auth number, visit counts, dates, computed status, payer contact info, and expiring-soon warning. It does not mention pagination or error behavior, but for a straightforward read-only lookup this is 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 coverage is 100% and the single parameter, patientId, is already described as 'Tebra patient ID'. The description does not add further detail about the parameter, but none is needed given the schema's completeness.

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

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

The description clearly states the verb ('Get') and resource ('insurance authorizations for a Tebra patient'), and adds scope ('across all cases and policies'). It does not explicitly distinguish itself from sibling tools like tebra_check_insurance_eligibility, so it stops 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 intended use is implied by the description: an agent should call this when it needs a patient's insurance authorizations and their status. However, there is no explicit guidance about when not to use it or which alternative tool to choose, such as eligibility checking.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds the note about the Tebra WSDL lacking a patient ID filter, which is a useful external constraint. However, it does not describe return format, pagination, or how filters interact (AND/OR). With annotations covering the safety profile, a 3 is appropriate.

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

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

The description is concise—two sentences plus a note—with no fluff. It front-loads the core action and filter categories. It could be slightly more structured, but it is efficient and readable. The note about the WSDL limitation is a valuable addition without excessive length.

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 tool with 14 optional parameters and no output schema, the description is incomplete. It does not explain whether it returns a single payment or a list, how filters combine, or any default behavior (e.g., date range default). It also does not mention response structure or error conditions. Given the complexity, more contextual detail is needed for an agent 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%, so all 14 parameters have descriptions in the schema. The tool description summarizes some filters (post-date range, payer, batch, appointment, reference-number) but omits others like amount, paymentId, practiceName, and created/last-modified dates. Since the schema does the heavy lifting, the description adds minimal additional meaning beyond the schema, warranting a 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?

The description clearly states the verb 'Get' and the resource 'payments', and lists specific filters (post-date range, payer, batch, appointment, reference-number). It also adds a useful note about the missing patient ID filter. However, it does not explicitly differentiate from sibling tools like tebra_get_charges or tebra_get_transactions, though 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 description provides no guidance on when to use this tool versus alternatives. It does not mention any exclusions or scenarios where another tool would be more appropriate. The only hint is the patient ID filter limitation, but it does not point to a substitute. An agent is left to infer usage from the name and filters.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds scope ('all practices associated with the Tebra account') and return-field context, but does not discuss potential pagination, rate limits, or open-world caveats. This is acceptable but not rich.

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

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

The description is one clean sentence that front-loads the action and scope, then lists the returned data fields. Every word contributes value and there is no redundant 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 parameterless read-only list tool, this is complete: it states what is returned, the scope ('all practices associated with the Tebra account'), and the key output fields. No output schema exists, but the description fills that gap adequately.

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?

The input schema has zero parameters and 100% description coverage, so there is nothing for the description to explain. The baseline of 4 for parameterless tools applies, and the description appropriately focuses on outputs instead.

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 uses a specific verb and resource: 'Get all practices associated with the Tebra account.' It also enumerates the returned fields (practice IDs, names, NPI, tax ID, contact info), making the tool's purpose unmistakable and distinguishing it from sibling getters like providers or service locations.

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 clear usage: call this tool when you need the account's practice-level identifiers or contact information. It provides enough context for an agent to select it over other getters, and there are no competing practice-related siblings, though it does not explicitly state exclusions or alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description is consistent with that ('Get', 'Returns'). It adds useful context by scoping to codes 'configured in the Tebra practice' and by naming the returned fields, 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?

The description is two tight sentences with no filler. It front-loads the core purpose, then covers filtering and return contents efficiently.

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 lookup tool with three optional filters and no output schema, the description covers purpose, scope, filters, and return fields. It does not mention pagination or limits, but the annotations already cover the read-only and open-world safety profile.

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?

The input schema already documents all three optional parameters with 100% coverage. The description paraphrases those same filters (CPT code, active status, customer-specific) but adds no deeper semantics such as matching behavior, defaults, or interaction between filters.

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

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

The description clearly identifies a specific resource ('procedure codes configured in the Tebra practice') and a specific action ('Get'), and adds meaningful detail about filters and returned fields. This distinguishes it from sibling tools like charges, appointments, or payments.

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 is given about when to use this tool versus alternatives, and no exclusions or prerequisites are mentioned. Sibling tools like tebra_get_charges and tebra_get_transactions exist, but the description does not explain how procedure codes fit into that selection space.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety and non-exhaustive nature of the result set. The description adds context about returned fields and filter options, but it does not disclose pagination behavior, whether results are limited, or how filters match (exact vs partial). Given the annotation coverage, this is adequate but not extensive.

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 with no filler: the first states the core operation and output, the second covers the filters and use case. Information is front-loaded and every word 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 read-only lookup tool with five optional parameters and no output schema, the description provides the key facts: what is returned, what filters exist, and why to use it. It could be more complete by explicitly stating the response shape (e.g., list vs single object), but the 'Get providers with...' phrasing and readOnlyHint make the expectation reasonably clear.

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 optional parameters are already documented with their names and filters. The description restates the filter capabilities ('full name, practice, department, or provider type') but adds no detail beyond the schema about matching semantics or value formats. Baseline 3 applies because the schema carries the load.

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

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

The description states a specific verb and resource — 'Get providers' — and enumerates the returned fields: IDs, names, specialties, NPI, and active status. This clearly distinguishes it from sibling getter tools like tebra_get_practices or tebra_get_service_locations by naming the exact resource and its purpose.

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

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

The description gives a clear usage context: 'Used to resolve provider names to IDs for appointments and encounters.' This tells an agent when to reach for this tool, though it does not explicitly state when not to use it or name alternatives like tebra_get_practices.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds the contextual fact that it is required for appointment/encounter creation, but does not disclose additional behavioral traits such as pagination, sorting, result limits, or the format of returned data. Given that annotations carry the safety profile, the description adds modest value but is not rich in behavior. It does not contradict 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?

The description is compact: one sentence for the core purpose, one for the usage context, and one for the optional filters. It front-loads the most important information and has zero fluff. Every sentence contributes meaning, and it 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?

For a read-only lookup tool with three optional filters and no output schema, the description covers the essential context: what it returns (service locations), why it is needed (for appointments/encounters), and how to narrow results. It does not mention return format, pagination, or field details, but given the tool's simplicity and the annotations covering safety, these omissions are minor. The 'required for' context is particularly valuable for an agent planning multi-step workflows.

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?

The input schema has 100% coverage with each parameter individually described (practiceId, practiceName, serviceLocationId). The description only mentions filtering 'by practice or location ID,' which omits practiceName and slightly mischaracterizes it as an ID filter (it is a name filter). Since the schema fully documents the parameters, the description adds little beyond what is already present, and the slight inaccuracy prevents a higher score.

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 ('Get') and a clear resource ('service locations') and clarifies they are offices/facilities. It also ties the tool to a concrete downstream need ('Required for creating appointments and encounters'), which immediately distinguishes it from sibling tools like tebra_get_appointments or tebra_get_practices. The purpose is unambiguous and well-scoped.

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 explicitly says the tool is 'Required for creating appointments and encounters,' giving a strong contextual trigger for when to call it. It also mentions optional filters, implying usage scenarios. However, it does not explicitly state when NOT to use it or name alternative tools for other reference data (e.g., providers, procedures), though the context makes that fairly clear. It's a solid usage guideline with no 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only and non-exhaustive nature is covered. The description adds meaningful behavior context: results are account-specific, broken down per endpoint, and expressed in milliseconds. No contradiction with annotations exists.

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 deliver the full definition and the intended use case in a front-loaded manner. Every word earns its place, and there is no repetition of schema fields or annotations.

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

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

For a zero-parameter read-only utility, the description adequately conveys what is returned (per-endpoint throttle intervals in milliseconds) and why an agent would use it. There is no output schema, but the open-ended nature of the result is reasonably inferable; a sample response would be a nice enhancement, not a necessity.

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?

The tool has zero parameters and no required inputs, so there is no parameter documentation burden for the description to carry. The mention that throttles are enforced 'for this account' usefully clarifies that the response is account-scoped without needing any caller-supplied arguments.

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: it returns the per-endpoint API throttle intervals in milliseconds that Tebra enforces for the current account. This clearly distinguishes it from sibling tools that operate on charges, appointments, patients, or documents. The resource and scope are unambiguous.

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

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

The phrase 'useful for monitoring API usage limits' gives a clear practical context for when to call this tool. It does not name explicit alternatives or when-not conditions, but no sibling tool appears to be a competing throttles endpoint, so the guidance is sufficient.

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 and openWorldHint, so the description only needs to add context beyond those. It adds the return shape (patient, claim, insurance) but does not disclose pagination, result volume, or PHI handling beyond what appears in the fields parameter schema. No contradictions with 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?

The description is two short sentences with no filler. The core action and filter scope are front-loaded, and the return summary is included without repeating schema-level parameter details.

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 correctly provides a high-level return summary. Combined with fully documented parameters and safety-carrying annotations, it is largely complete for a retrieval tool, though it could optionally mention pagination or large-result-set behavior for a financial transaction query.

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 all 14 parameters have individual descriptions. The tool description only restates filter categories (date range, type, payer, procedure code, practice) and adds no syntax or semantic detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly names a concrete resource (financial transactions from Tebra) and a retrieval verb, and summarizes the returned data (patient, claim, insurance). It is clear what the tool does, but it does not explicitly distinguish it from financial siblings like tebra_get_charges or tebra_get_payments.

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 when the agent needs transaction-level financial records with optional filters, but it provides no explicit when-to-use/when-not-to-use guidance and names no alternatives. Given the sibling list contains other financial record tools, 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?

The annotations already indicate readOnlyHint=false and idempotentHint=false, so the agent knows it's a mutating, non-idempotent operation. The description adds that it returns the vendor ID, which is useful for subsequent calls. However, it doesn't mention any side effects, such as duplicate handling or state changes beyond registration, which would be valuable given the lack of idempotency.

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

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

The description is concise at two sentences, with the purpose front-loaded in the first sentence and the return value in the second. Every word adds value, and there is no redundancy with the schema or annotations.

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

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

For a simple one-parameter tool with full schema coverage and no output schema, the description adequately covers the primary purpose and return value. The reference to tebra_update_patient_external_id provides necessary context for the agent's workflow. Minor gap: it doesn't mention whether the vendor name must be unique or how to handle errors, but these are not critical for correct invocation.

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

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

The schema description coverage is 100%, so the single parameter 'vendorName' is already well-documented. The description adds a bit of context by noting the purpose is 'for external ID mapping', but it does not provide additional semantics like formatting constraints or examples beyond the schema. A baseline of 3 is appropriate.

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

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

The description states a specific action ('Register a new external vendor') with a clear resource ('in Tebra') and a specific purpose ('for external ID mapping'). It also names the downstream use ('Returns the vendor ID to use with tebra_update_patient_external_id'), which clearly distinguishes it from siblings like tebra_get_external_vendors.

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 when to use it (before calling tebra_update_patient_external_id), and the mention of the sibling tool provides context. However, it does not explicitly state when NOT to use it or when to prefer alternatives, such as tebra_get_external_vendors for listing existing vendors.

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?

Even with readOnlyHint=true and openWorldHint=true in annotations, the description adds useful behavioral context: it states the returned data categories (demographics, MRN, contact info, insurance) and explicitly warns that MRN and external ID are not server-side filters. This goes beyond the annotations and helps an agent avoid an invalid lookup path.

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

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

The description is three sentences, front-loaded with the core purpose den, then filters, then return-value summary, then an important caveat. Every sentence earns its place, and the caveat is positioned last without burying the main action.

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 19-parameter search tool with no output schema, the description covers the essential invocation facts: what can be filtered, what is returned, and the limitation around MRN/external ID. It omits details like pagination, default result limits, or sorting, which would be useful, but the core selection and invocation guidance is sufficient.

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?

The input schema already covers all 19 parameters with descriptions, so the baseline is a 3. The description adds meaningful grouping semantics: query is a backward-compatible alias for fullName, filters can be combined, and MRN/external ID are not server-side filters. This is non-obvious context that genuinely helps parameter selection.

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 opens with a clear verb and resource: "Search for patients in Tebra with flexible filters." It goes beyond a generic search by enumerating the filter dimensions (name, firstName, lastName, DOB range, insurance, practice) and clarifying what the tool returns. It also implicitly separates itself from the sibling tebra_get_patient by excluding MRN/external ID server-side filters.

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

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

The description gives actionable guidance: use query/fullName for name searches, or combine specific filters for broader lookups. It explicitly names an alternative (tebra_get_patient) for external ID lookup)Skip saying when not to use this tool relative to tebra_get_all_patients or tebra_create_patient, but the search-vs-specific-lookup distinction is clear.

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

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

Annotations indicate readOnlyHint=false (mutation) and destructiveHint=false, but the description confirms the mutation intent and importantly clarifies that changes are limited to primary status, not renaming or payer scenario. This adds beyond 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?

One concise sentence with clear action, parameter reference, and an exclusions note. Front-loaded with the purpose and usage.

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 single parameter, full schema coverage, and no output schema, the description provides sufficient guidance: what it does, how to find the ID, and what it can't do. Minor gap: no mention of idempotency or potential side effects, but annotations cover idempotentHint.

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

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

Schema coverage is 100%, and the description reinforces the parameter's purpose ('to promote to primary') but adds minimal extra meaning beyond the schema's own description. Baseline 3 applies.

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

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

Clearly states the verb 'promote' with the resource 'existing patient case' and specifies the operation is by case ID. Distinguishes it from other tools like tebra_update_patient by focusing on setting primary status.

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

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

Explicitly instructs how to find case IDs via tebra_get_patient, providing a concrete usage path. Also lists exclusions (cannot rename or change payer scenario), which helps the agent avoid misusing the tool.

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

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

Annotations already indicate the tool is not read-only and not destructive. The description adds the partial-update behavior ('Only provided fields will be changed') and the dependency between startDate and endDate/duration, which are not covered by annotations. This adds useful behavioral context without contradiction.

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 with no filler. The purpose, partial-update behavior, parameter dependency, and sibling preference are all front-loaded and clearly separated. 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 tool with 12 parameters but full schema coverage and no output schema, the description covers the essential usage nuances: partial updates, the startDate dependency, and the status-only alternative. It does not explain return values, but that is not required without an output schema. It is sufficient for an agent 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%, so all parameters are already documented. The description adds the key rule that changing startDate requires endDate or duration, which is not in the schema. This extra guidance raises the value beyond the baseline for high coverage.

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

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

Clearly states the tool updates an existing appointment in Tebra and distinguishes itself from the sibling tebra_update_appointment_status by explicitly preferring that tool for status-only changes. The verb 'update' and resource 'appointment' are specific and 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?

Provides explicit guidance: when changing startDate, also provide endDate or duration, and when only changing status, prefer a different tool. This directly tells an agent when to use this tool versus an alternative.

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

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

Annotations already provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds the behavioral scope 'only the status' and 'lighter', which clarifies that this operation does not modify other appointment fields. No contradiction with annotations, and the added context is meaningful.

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

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

The description is a single, compact sentence that front-loads the core purpose ('Update only the status') and then adds the sibling contrast. Every word earns its place, with no 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?

Given the low complexity (2 params, no nested objects), full schema coverage, and strong annotations, the description is nearly complete for an agent to select and invoke the tool. The only minor gap is that it doesn't describe the return value or response behavior, but that is not critical for this simple update 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%, so both parameters are already fully documented in the schema, including the complete enum for appointmentStatus. The description only repeats a few example values and does not add new semantic details, matching the baseline for high schema coverage.

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 ('Update only the status of an appointment') and gives concrete example statuses. It also distinguishes itself from the sibling tebra_update_appointment by calling itself 'Lighter than' that tool, so an agent can immediately tell what this tool does and what it does not do.

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 explicitly names the alternative tebra_update_appointment and specifies the intended use case: 'use for check-in/check-out workflows.' This gives clear when-to-use guidance and implies when NOT to use it (when more than status needs updating).

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and idempotent (idempotentHint=true). The description adds crucial behavioral context: Approved triggers billing, Rejected returns to Draft, Unpayable closes the encounter, and the UI displays Submitted encounters under 'Review'. This goes beyond annotations to inform the agent of side effects and a UI quirk, with no contradiction.

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

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

Two concise sentences with no filler. The main action and workflow are stated upfront, followed by a useful UI note. Every clause adds value, and the structure is easy to parse.

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 covers the essential aspects: what it does, the valid status transitions, and their consequences. It also includes a UI nuance. All parameters are documented in the schema, and the description integrates them into the workflow. The only minor gap is not explicitly contrasting with similar update tools, but that is not critical for an agent to use 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 each parameter documented. The description enriches the 'status' parameter by explaining the workflow implications of each enum value, which is not in the schema. It also clarifies that practiceId/practiceName are optional and useful for multi-practice accounts, though this is already in the schema. Overall, the description adds meaningful semantics 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?

The description opens with a specific verb and resource ('Update the status of an encounter in Tebra') and immediately explains the billing workflow it drives. It goes beyond a generic 'update' by enumerating the valid state transitions and their consequences, making the tool's purpose unmistakable and distinct from other update tools like tebra_update_appointment_status.

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

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

The description clearly conveys when to use the tool: to move encounters through the billing workflow. It explains the order (Draft → Submitted → Approved/Rejected → Unpayable) and the side effects of each transition. It does not explicitly state when NOT to use it or name alternatives, but the context is strong enough for an agent to infer the appropriate use case.

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=false, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral detail beyond the annotations: only provided fields are changed, and omitted practiceName/practiceId falls back to the account's first practice. No contradiction with 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?

The description is two tight sentences with the core update semantics front-loaded and no filler. Every sentence adds value, and the practice fallback nuance 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?

The schema covers all parameters and annotations cover the safety profile. The description handles the update semantics and the practice requirement nuance. The only minor omission is return behavior, but for an update operation without an output schema this is not critical.

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 all 15 parameters individually documented. The description adds useful context for practiceName/practiceId resolution, but the schema already carries the parameter semantics. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Update an existing patient in Tebra.' It also clarifies partial update semantics with 'Only provided fields will be changed,' which distinguishes it from create_patient and get_patient. The purpose 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 implies its usage context: updating an existing patient, and it explains the practice defaulting behavior. However, it does not explicitly say when to use this tool versus alternatives like create_patient for new patients or search_patients to resolve patient IDs. Usage is inferable but not directly 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?

Annotations declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, which align with the 'Set or update' action. The description adds behavioral context about the prerequisite of vendor registration, which is beyond what annotations provide. However, it doesn't disclose potential side effects (e.g., overwriting an existing ID) or error conditions, but with annotations covering the safety profile, a 3 is appropriate.

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 with zero fluff. The primary action and purpose are front-loaded, followed immediately by the critical prerequisite. Every word 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 tool with 4 parameters (2 required) and no output schema, the description covers the core function, the prerequisite, and the source of a key parameter. It doesn't discuss error handling or what happens if the vendor is not registered, but those are less critical given the clarity provided. The description is sufficient for an agent to call the tool correctly in the intended flow.

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 adds value by specifying that externalVendorId is a 'numeric ID' and connecting it to the registration step, which clarifies the expected format and source beyond the schema's generic description. This extra guidance merits a 4.

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

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

The description clearly states the action ('Set or update'), the resource ('patient external ID'), and the purpose ('linking the patient to an external system'). It also distinguishes this tool from other update tools by focusing on external IDs. The verb+resource combination is specific and 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 provides a clear prerequisite: 'Register the vendor first with tebra_register_external_vendor and pass its numeric ID as externalVendorId.' This gives explicit context on how to prepare for using the tool. It doesn't explicitly state when not to use it, but the prerequisite and focus on external IDs effectively differentiate it from sibling update 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 the read-only nature is covered. The description adds the specific detail of retrieving customer ID and authorization flag, which is useful but does not disclose additional behavioral aspects like error handling or side effects. With annotations covering safety, a 3 is appropriate.

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 with no wasted words. The main purpose is front-loaded, and the health-check usage is stated clearly. Perfectly concise and structured.

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-parameter, read-only health-check tool with annotations covering safety, the description fully explains what it does and when to use it. No output schema is needed, and nothing critical 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?

The tool has zero parameters, and schema coverage is 100% (vacuously). The description does not need to explain parameters, and the baseline for zero-parameter tools is 4. No additional parameter semantics are required.

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

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

The description clearly states the verb 'validate' and the resource (Tebra API credentials), and specifies that it retrieves the customer ID and authorization flag. This is distinct from all sibling tools which perform CRUD or other operations.

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 explicitly says 'Use as a health check,' which gives a clear context for when to invoke this tool. It does not mention alternatives or exclusions, but given the unique purpose, no alternative is needed. Slight lack of explicit 'when not to use' but sufficient for a health check.

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