splose MCP by usefulapi

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

Annotations only supply destructiveHint=true; the description carries the rest: irreversible through this server, the reason's billable rate may create a cancellation charge, and the patient may be notified per practice settings. It also discloses the two underlying endpoints, so an agent knows the exact write 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?

Front-loaded WRITE marker, then consequences, then the group-appointment branch, then the safety gate. Every sentence conveys distinct operational information; nothing repeats the schema verbatim.

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

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

No output schema exists, yet the description covers effect (cancellation), side effects (fee, notification), scope (single vs group patient), precondition (confirm: true), and irreversibility. That is everything an agent needs to invoke this destructive tool safely.

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 real value by naming the upstream source for reasonId (splose_list_cancellation_reasons) and restating that omitting patient_id cancels the whole appointment, which frames the optional param's blast radius.

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?

Opens with an explicit verb+resource+cardinality ("WRITE: cancels ONE appointment") and names the required inputs. This clearly separates it from splose_update_appointment, splose_get_appointment, and splose_create_appointment without the agent needing to inspect schemas.

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?

Points to splose_list_cancellation_reasons for the required reasonId and gives the exact branching condition for patient_id (group appointments only). It states the confirm requirement and advises confirming with the user first. No explicit 'when not to use' (e.g. reschedule instead of cancel), so not quite 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?

Goes well past the destructiveHint annotation by disclosing real side effects: Splose may send the patient booking confirmations or reminders per practice settings, the appointment becomes invoiceable later, and duplicate calls book duplicates. These are exactly the consequences an agent needs before invoking a write.

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

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

Four short sentences, front-loaded with the WRITE marker and the core operation, then the side effects, then the prerequisite, then the idempotency warning and endpoint. Every sentence carries distinct information; nothing is repeated from 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 an 8-parameter write with no output schema, the description covers purpose, side effects, prerequisites and idempotency, which is nearly everything needed. The one gap is the return value — it never says whether the created appointment (and its id) comes back, which matters for chaining into splose_update_appointment or invoicing.

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 defines every field and its UTC semantics; the baseline is 3. The description adds real value by tying the id parameters to their concepts in a single sentence and making the singular cardinality explicit ('one patient with one practitioner, service and location').

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 ('books') and resource ('appointment') with explicit cardinality and entity bindings: one appointment, one patient, one practitioner, service and location, spanning start to end in UTC. The 'WRITE:' prefix and singular scope let an agent distinguish it immediately from splose_update_appointment and splose_list_appointments.

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

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

Gives an explicit prerequisite ('Check splose_find_free_slots first') naming the sibling tool and the condition that selects it, plus a non-idempotency warning that shapes retry behaviour. It stops short of a negative case (e.g., use splose_update_appointment to modify an existing booking rather than re-creating), so not a full when/when-not pair.

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

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

Annotations only supply destructiveHint=false, so the description carries real weight here: it declares this is a write, states the endpoint (POST /contacts), and explicitly warns 'Not idempotent: calling twice creates two contacts' — a behavioral trait no annotation exposes. It stops short of permissions/auth requirements or what the response returns.

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

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

Four short clauses, front-loaded with the write marker and cardinality, then requirements, then the idempotency warning. No filler — every phrase adds information an agent needs before calling.

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 18-parameter creation tool with no output schema and near-zero schema descriptions, the definition covers only its three required fields. An agent has no guidance on how to populate name vs firstName/lastName/companyName, when to use doctorType versus type, or limits like maxItems=5 on phoneNumbers, leaving most of the call surface unexplained.

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 only 11% across 18 parameters, so the description must compensate — and it barely does. It adds meaning only for `type` (Splose contact type, copy from existing) and restates that name/email are required; the 15 other properties (phoneNumbers array, doctorType enum, address fields, firstName/lastName split) get no explanation beyond their names.

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?

Opens with an explicit verb/resource pair ('WRITE: adds ONE contact') and enumerates the concrete roles it covers (GP, plan manager, referrer, payer), which sharply separates it from generic record-creation tools. 'ONE' also signals cardinality unambiguously.

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

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

Names the required fields and routes the agent to splose_list_contacts to discover valid `type` values, which is genuinely useful. However, it never addresses the obvious sibling confusion — when to create a contact versus splose_create_patient — and gives no preconditions or dedupe-first guidance despite admitting duplicates are possible.

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?

Strong disclosure beyond the thin annotations: write semantics, non-idempotency with the concrete consequence ("calling twice creates two patients"), downstream side effect on patient messaging via the practice's settings, and a health-data handling rule. The only gap is no statement of what the call returns or what permissions are needed.

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?

Five short, front-loaded clauses, each carrying distinct information: write scope, duplicate check, messaging side effect, idempotency, data-handling rule. No sentence is redundant.

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 28-param mutation with no output schema and minimal annotations, it covers purpose, ordering, side effects, and compliance well. It stops short of telling the agent whether the created patient's id is returned for chaining into splose_get_patient, and leaves most optional fields uncharacterised.

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?

With 28 parameters and only 36% schema description coverage, the description carries a heavy burden it mostly does not meet. It clarifies required names and explains communicationPreference's interaction with organisation settings, but the majority of fields (address block, Medicare/NDIS identifiers, phoneNumbers structure, invoiceRecipientId) get no added meaning.

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?

"WRITE: adds ONE new patient record (first and last name required)" gives a specific verb, resource, cardinality, and the required fields. This clearly separates it from splose_create_contact and from read-side siblings like splose_get_patient.

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

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

It names the alternative explicitly — "Search with splose_list_patients first to avoid a duplicate" — giving a concrete precondition before invocation. It also adds a domain constraint ("only enter what the user supplied") that governs what may be passed.

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 'Read-only. GET /free-slots' adds nothing. What does add value is the disclosure that results are returned per practitioner as start/end in UTC and that the window is capped at 7 days. It still doesn't say whether non-working hours, existing appointments, or service duration are factored in — the key behavioral question for a slot finder.

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

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

Three compact sentences, front-loaded with the resource and scope, then the return shape, then transport. The only waste is 'Read-only. GET /free-slots,' which duplicates the readOnlyHint annotation.

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

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

With no output schema, the description carries the return-value burden and does so briefly (per-practitioner start/end in UTC). Combined with the 7-day window limit and required service/location/practitioner scoping, an agent has enough to invoke it correctly, though the slot-generation semantics remain unstated.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema, which sets the baseline at 3. The description reinforces the from/to pairing and the 7-day ceiling but adds no meaning for 'interval' or the 20-practitioner cap beyond what the schema states.

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 resource ('Bookable free slots') and its scoping inputs (practitioners, location, one service, from/to window), which is far more than a restatement of the name. It doesn't explicitly name how it differs from close siblings like splose_get_practitioner_availability or splose_list_busy_times, so it falls short of a 5.

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

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

Usage is only implied: 'Bookable free slots ... for one patient service' suggests the booking flow, and the 7-day window cap is a real constraint on use. But there is no explicit when-to-use/when-not guidance and no routing against the availability and busy-times siblings, which an agent would plausibly confuse this with.

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

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

readOnlyHint=true already establishes the safety profile, so the description's job is to add context — it does so by disclosing the returned fields (org, practitioner, expiry). It doesn't say what happens when the key is expired or invalid, which is the main behavioral risk for a credential-scoped call.

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

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

Three short fragments, return content stated first and the usage hint second — well front-loaded with zero filler. The clipped verbless phrasing is slightly terse but never ambiguous.

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 zero-parameter, read-only endpoint with no output schema, the description supplies enough: what identity is returned and that it reflects the API key's owner. Only the expired/invalid-key behavior is left implicit.

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 takes no parameters, so the baseline is 4; there is nothing for the description to compensate for.

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

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

The description names the resource returned (the organisation and owning practitioner plus key expiry) and the endpoint (GET /me), which clearly distinguishes it from sibling lookups like splose_get_practitioner or splose_list_practitioners. It is a noun-phrase rather than an explicit verb, but the intent 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?

'Good first call' tells the agent to use this at the start of a session to establish identity/tenancy and confirm credentials work. No exclusions or alternatives are named, but for a zero-parameter identity endpoint there is little sibling overlap to disambiguate.

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

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

readOnlyHint=true already covers the safety profile, and the description adds real value by enumerating what the payload includes: each patient's status, case, invoice and cancellation details. It does not address behavior for an invalid or non-existent id, which is a minor remaining gap.

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, with the returned-content summary front-loaded and the endpoint appended as terse confirmation. Every clause carries information.

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

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

With no output schema, the description must convey what comes back, and listing status/case/invoice/cancellation details does that adequately for a single-record read. Missing only error/empty-result behavior to be fully complete.

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

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

Only one parameter, and the schema documents it at 100% coverage ('Appointment id.'). The description adds nothing about its format or provenance beyond what the schema already says, so the baseline 3 applies.

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

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

States a specific retrieval action on a specific resource ('One appointment in full') and even names the underlying endpoint GET /appointments/{id}. The phrase 'One appointment' implicitly separates it from the list_* siblings, though no sibling is named explicitly.

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

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

Usage is only implied: fetch a single appointment when you already have its id. There is no explicit guidance about when to prefer this over splose_list_appointments or splose_get_case/get_invoice for related data, and no prerequisites or exclusions stated.

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

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

readOnlyHint already declares the safety profile. The description does add response-content context ('in full, with its appointment connections'), which matters since there is no output schema, but says nothing about errors, missing cases, or permission needs.

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

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

Two short sentences, front-loaded with the primary outcome, zero filler.

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

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

For a single-resource read with one required param and no output schema, the description tells the agent what comes back (full case plus appointment connections), which is the main ambiguity. Only edge-case behavior is omitted.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents case_id fully. The 'GET /cases/{id}' line confirms it is a path parameter, a marginal addition.

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

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

Names the resource (a case) and the scope (one, in full, fetches appointment connections), so it is distinguishable from the sibling splose_list_cases. The verb is only implied via 'GET /cases/{id}', which is slightly less direct than a plain 'Retrieve'.

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

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

There is no explicit guidance on when to use this versus splose_list_cases or how to obtain a case_id. The 'one vs list' contrast is only inferable from 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?

The only behavioral content is the REST path GET /contacts/{id}, which restates readOnlyHint=true rather than adding to it. Nothing is said about error behavior for missing IDs, permission requirements, or what 'in full' returns.

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 fragments, front-loaded and waste-free. It is arguably over-compressed, but conciseness itself is good.

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

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

For a one-parameter read-only lookup with annotations covering safety, the definition is minimally sufficient. However, with no output schema, the agent has no idea what 'in full' actually includes.

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 contact_id is fully documented in the schema itself. The description adds no syntax or meaning beyond that, making the baseline 3 correct.

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

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

States a specific verb+resource (get a contact) and clarifies scope with 'One contact in full', which distinguishes it from a bulk list. It never names the sibling splose_list_contacts, so differentiation is implied rather than explicit.

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

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

There is no when-to-use statement, no prerequisites, and no alternative named. The agent must infer from 'one contact' that list_contacts is the bulk alternative rather than being told.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real value by disclosing what the response contains (line items and payments) and the underlying GET endpoint. It does not cover not-found behavior or auth requirements, which keeps it at a moderate level.

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

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

Two short sentences: the payload first, the endpoint second. Nothing is wasted and the most decision-relevant information (full detail with line items and payments) 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?

With no output schema, the description correctly compensates by naming the returned components. For a single-parameter read tool that is nearly enough; only error/empty-result behavior is left unstated.

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

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

Schema coverage is 100% and the single invoice_id parameter is fully typed with bounds, so the schema carries the burden. The description only echoes the path variable via 'GET /invoices/{id}' and adds no format or sourcing guidance beyond that, making baseline 3 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 names the resource (a single invoice) and its scope explicitly: 'in full with its line items and payments.' That distinguishes it from the sibling splose_list_invoices without naming it. It stops short of a clean verb-first phrasing, but the operation is unambiguous.

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

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

Usage is only implied: 'One invoice' plus the enriched payload suggests this is the detail-view counterpart to splose_list_invoices. There is no explicit routing guidance (e.g., 'list invoices first to obtain the id') and no stated preconditions, so the agent must infer when to call it.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds essentially nothing beyond that: "in full" hints at a complete representation but never says what fields are returned, what happens for an unknown or archived location, or whether permission scoping applies.

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

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

Two very short sentences with zero padding, and the core statement is front-loaded. It is under-specified rather than bloated, which the other dimensions already penalize.

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

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

For a one-parameter read tool with a fully described schema and a readOnlyHint annotation, the minimum needed to call it correctly is present. Still, the description offers no return-shape summary (there is no output schema) and no failure-mode context, leaving it only just adequate.

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

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

Schema coverage is 100% and the single parameter location_id is documented in the schema, so baseline 3 applies. "GET /locations/{id}" only confirms that the id in the path is the location_id — no additional format, range, or sourcing guidance.

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 fragment "One location in full" combined with the name and title makes the resource (a single location) and the single-record scope identifiable, and implicitly contrasts with splose_list_locations. However, it never states an explicit verb like "retrieve" and relies on the name to carry the action, so it sits at vague-but-inferable rather than specific.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the obvious alternative splose_list_locations for browsing multiple locations. The agent must infer everything from the tool name and the sibling list.

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

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

The readOnlyHint annotation already establishes that this is a safe read. The description adds meaningful context by flagging 'HEALTH DATA' and itemizing the sensitive fields returned, but it says nothing about access permissions, error/not-found behavior, or how the payload is shaped beyond the field list.

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

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

Two tight sentences with the scope front-loaded and no wasted framing. The dense field inventory is slightly list-like but earns its place because there is no output schema to describe the return values.

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-record fetch with one fully described parameter and no output schema, the description covers the key elements: what comes back, that it contains health data, and the underlying endpoint. It could be more complete by noting not-found behavior or access constraints, but nothing essential to calling it is missing.

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

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

Schema coverage is 100% for the single patient_id parameter, so the schema fully documents it. The description only echoes this via '{id}' and adds no format or constraint details beyond what the schema provides, making the baseline 3 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 resource and scope ('One patient in full') and enumerates exactly which fields are returned, which implicitly distinguishes it from splose_list_patients. It never names a sibling tool explicitly, so it stops short of full 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?

Usage is only implied by the endpoint reference 'GET /patients/{id}' and the singular 'One patient'. There is no explicit when-to-use guidance, no mention of when to prefer list_patients or search-style tools, and no note about behavior when the patient isn't found.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered by structured data. Beyond that the description adds only 'in full', which hints the complete payment record is returned rather than a summary — useful but thin, with no mention of error behavior for a missing/invalid id.

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

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

Two short fragments, zero filler, with the scope statement front-loaded. The telegraphic style borders on under-specification rather than verbosity, but nothing 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 a one-parameter read tool with readOnlyHint and a fully documented schema, most contract information is present. It is only adequate, however: nothing is said about what a payment record contains or how not-found cases surface, and there is no output schema to cover the return shape.

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?

There is a single parameter and schema description coverage is 100%, with the schema documenting 'Payment id' plus positivity and integer constraints. The description adds no format or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States the resource (one payment) and scope ('in full'), and the endpoint reference GET /payments/{id} confirms a single-record retrieval. That implicitly distinguishes it from splose_list_payments, but it never names the sibling or states the verb outright, so it falls short of a 5.

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

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

No guidance on when to use this versus splose_list_payments or splose_get_invoice, and no mention of prerequisites (e.g. needing a payment_id from a list call). The agent must infer usage from the name alone.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's main contribution is content disclosure — that provider numbers and connections are included in the response. It says nothing about error/404 behavior, whether missing sub-resources are omitted or null, or any rate/permission constraints.

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

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

Two short clauses with zero filler; the payload scope is front-loaded and the endpoint hint trails it. Nothing could be cut without losing information.

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

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

For a one-parameter read tool with a readOnly annotation and full schema coverage, the minimum is met and the payload hint partially substitutes for the absent output schema. It still does not describe the response shape or failure modes, which is the main remaining gap for a detail-fetch 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 single practitioner_id parameter is fully documented in the schema (100% coverage, integer, exclusiveMinimum 0), so the schema carries the load. The description adds no extra semantics about the identifier beyond restating the endpoint template.

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 resource and scope ('One practitioner in full') and enumerates the notable payload contents (provider numbers, connections), plus the underlying endpoint GET /practitioners/{id}. An agent can tell it is the single-record fetch rather than the list, though it never names splose_list_practitioners explicitly.

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

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

Usage is only implied: 'One practitioner' signals single-record detail retrieval versus listing, and the endpoint path reinforces that. There is no statement of when to prefer it over splose_list_practitioners or the related splose_get_practitioner_availability, and no prerequisites or not-found behavior 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?

With readOnlyHint already declaring a safe read, the description adds real value: the 100-day maximum window and the repeat semantics (weekly/fortnightly). It does not mention pagination or how large result sets are handled, which keeps it below a 5.

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

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

Three short sentences, front-loaded with what the tool returns, followed by the key constraint and the routing to the alternative. No wasted 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?

No output schema exists, and the description compensates by sketching the returned fields (start/end time, repeat cadence). Complete enough to call correctly, though pagination and volume behavior are unaddressed.

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 four parameters are already documented, including the 100-day constraint on endDate. The description reinforces the window but adds no syntax or format detail beyond the schema, making the baseline 3 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 resource (practitioner working-hours availability) with scope (per date and location) and explicitly names the sibling splose_find_free_slots as the different, bookable-slots tool. An agent can disambiguate without opening either schema.

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

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

Explicitly says this is the roster, not the open slots, and directs the agent to splose_find_free_slots for bookable times. That is a clear when-to-use-this-vs-alternative statement.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds useful return-content context ('in full, including provider-travel pricing') and confirms the underlying GET, but says nothing about error behavior for a missing id or response shape beyond the pricing hint.

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

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

Two short sentences, front-loaded with what the tool returns, followed by the endpoint mapping. Nothing redundant or padded.

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

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

For a single-parameter read tool with no output schema, the description is nearly sufficient: it discloses scope, the resource identity, and part of the payload (provider-travel pricing). A brief note on missing-id behavior would close the remaining gap.

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

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

Schema coverage is 100% with a single documented 'service_id' property, so the schema already does the work. The endpoint notation '/services/{id}' lightly reinforces that the id path maps to the parameter, but adds no new constraints or format guidance.

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 service') plus scope ('one service in full'), which implicitly distinguishes it from the sibling splose_list_services. The endpoint path reinforces that this is single-resource retrieval, but no sibling is named explicitly.

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

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

Usage is only implied: the singular 'one service' plus a required service_id signals 'use when you already know the id, not for enumeration.' No explicit statement of when to prefer this over splose_list_services or what happens on an unknown id.

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

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

Annotations already declare readOnlyHint=true, so safety needs no explanation. The description adds genuinely new context annotations cannot carry: results are ordered by id, timestamps are UTC, and each row carries the per-patient status plus cancellation reason and invoice id. It omits default page size and the archived-record default, which keeps it short of a 5.

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

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

Three short fragments: ordering and returned fields first, filtering second, endpoint last. Every clause carries information and nothing is repeated from the schema verbatim.

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 takes on the job of naming the returned fields and ordering, which is what an agent needs to decide whether to call it. It stops short only on pagination behavior and the archived-inclusion default, which are partly recoverable from the schema.

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

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

Schema description coverage is 100%, so all twelve parameters are already documented, making 3 the baseline. The description adds a little by naming the meaningful filter axes and enumerating status values, but silently drops update_gt, status_update_gt/lt, include_archived and the id_gt/id_lt paging semantics, so it neither adds nor compensates much.

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

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

States a specific verb and resource ('List appointments'), plus id-ordered pagination and the fields returned, which is well beyond a bare title restatement. It does not, however, distinguish itself from splose_get_appointment or splose_find_free_slots, so an agent must infer the boundary from the sibling names alone.

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?

Listing the filter dimensions ('time window, patient, practitioner or status') implies when to reach for this tool instead of a single-record fetch, but usage is only implied. There is no explicit when-not, no pointer to splose_get_appointment for a single record, and no guidance on using id_gt/id_lt for paging.

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

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

readOnlyHint=true already establishes the safe-read profile, so the description does not need to restate that. It adds the field set and the endpoint, but says nothing about pagination behavior or result ordering even though the schema exposes id_gt/id_lt cursors. Useful context beyond annotations, but modest.

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

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

Two tight sentences, resource definition front-loaded and endpoint appended. Zero wasted wording and nothing to trim.

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?

Safety is covered by annotations, parameters are fully specified in schema, and the description enumerates returned fields in lieu of an output schema. Combined, an agent has everything needed to call it, with only pagination/ordering behavior left implicit.

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

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

Schema description coverage is 100%, so all nine parameters (including the pagination cursors and filters) are already well documented. The description adds no parameter semantics beyond what the schema provides, which is the correct baseline-3 outcome.

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 resource (blocked-out time in practitioner calendars, with leave/admin examples) and enumerates the fields returned, plus the underlying endpoint. It is clearly a list/read operation and the 'blocked-out' framing distinguishes it conceptually from sibling availability tools, though it doesn't name those siblings explicitly.

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

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

No guidance on when to use this versus splose_get_practitioner_availability or splose_find_free_slots, which are the obvious neighbors. Usage is only implied by the resource description; there are no exclusions or selection criteria.

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

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

readOnlyHint=true already declares this is a safe read, so the description's burden is lighter. It adds the endpoint and the purpose (supplying ids for cancellation), but says nothing about pagination behavior, archived records, or typical result size beyond what the schema already documents.

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 fragments with no filler, and the purpose is front-loaded ahead of the endpoint reference. Slightly telegraphic, but every clause carries information.

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

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

For a simple, zero-required-parameter list tool with annotations covering safety and a fully described schema, this is nearly complete. The only gap is any practical note about paging or archived inclusion, which is minor and partly covered by the schema.

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

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

Schema description coverage is 100%, and each of the five pagination/filter parameters is well documented in the schema itself. The description adds no parameter guidance (e.g., typical use of include_archived or paging via next_id_gt), so baseline 3 applies.

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

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

States a specific verb+resource (list cancellation reasons, with ids) and ties it to the cancel flow, which distinguishes it from the many other list_* siblings. The API endpoint reference adds precision, though the phrasing is fragmentary rather than a complete sentence.

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 clause 'needed to cancel an appointment' implies the tool is a prerequisite lookup for splose_cancel_appointment, which is useful context. However, it never explicitly says when to use this versus alternatives, nor any exclusions or ordering steps.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds a useful sensitivity flag ('HEALTH/FUNDING DATA'), which is genuine context beyond the annotations, but says nothing about default result size, pagination flow, or what ordering to expect.

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?

It is a single compact sentence plus endpoint and sensitivity marker, front-loaded with the resource definition. The 'GET /cases' fragment is marginally redundant with the tool name but costs little.

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 field enumeration is doing real work in telling the agent what a case record contains. However, for a 10-parameter paginated list tool it omits result ordering, page size, and how next_id_gt is meant to chain, leaving gaps an agent must discover by trial.

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 each of the 10 filters is well documented in-schema, including the id_gt/id_lt paging pair and the two enums. The description's mentions of tracking type, open flag, and dates mirror the schema rather than adding syntax or format detail, so baseline 3 applies.

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

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

The description states the resource (cases, defined as funding referrals and plans) and enumerates the salient fields returned, plus the underlying endpoint GET /cases. It is clearly a list/browse operation, distinguishable from the singular splose_get_case sibling, though it never explicitly says 'list all cases'.

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

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

There is no statement of when to use this versus splose_get_case or the other list endpoints, and no prerequisites or exclusions. The 'HEALTH/FUNDING DATA' marker hints at sensitivity but gives no actionable guidance on how to proceed.

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

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

readOnlyHint=true already establishes the safety profile. The description adds useful context by disclosing the returned fields (name, type, email, address, phones, related patient/invoice/case ids), but it omits pagination behavior, default ordering/limits, and how filters are applied. It is consistent 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 tight sentences. The contact subtypes and returned fields are front-loaded and every element earns its place; the trailing 'GET /contacts' is minimal but harmless.

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

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

With no output schema, the description usefully enumerates the return fields, and the schema fully covers all nine optional parameters. Remaining gaps (pagination defaults, ordering, page size) are handled or implied by the schema's id_gt/id_lt documentation, so the description is adequate for the tool's complexity.

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

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

Schema description coverage is 100%, so all nine filters (email, firstname, lastname, phoneNumber, id_gt/id_lt, update_gt/update_lt, include_archived) are fully documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific resource (contacts) and enumerates the subtypes (GPs, plan managers, referrers, invoice recipients) plus the fields returned. The list-vs-get distinction against siblings like splose_get_contact is obvious from the name/title, so no explicit sibling callout is needed.

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 no when-to-use vs alternatives guidance: nothing says when to use this rather than splose_get_contact for a single record or how to leverage filters. There are no exclusions or prerequisites 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?

readOnlyHint=true already establishes the safe-read profile, so the description's marginal burden is low. It does add real value by enumerating what comes back (items and allocations are nested-ish data the agent wouldn't otherwise expect) and naming the backing endpoint, but says nothing about paging, ordering, result limits, or default filters.

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 terse fragments, zero filler, with the payload contents front-loaded. The trailing 'GET /credit-notes' is close to noise for an agent that never constructs URLs, and the fragment style omits an explicit verb, but density is good.

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 field enumeration usefully sketches the response shape, which is the right instinct. But for an 8-parameter, zero-required list tool, it omits what an agent actually needs to call it well: pagination flow, whether results are filtered by default, and ordering.

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

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

Schema description coverage is 100%, so all eight filters (id_gt/id_lt cursor paging, invoiceId, patientId, update_gt/update_lt, sentStatus, practitionerId) are already documented. The description adds no filtering semantics beyond the schema, which is the expected baseline when the schema does the work.

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 enumerates the fields a credit note carries and appends the endpoint, so it's clear this is a credit-note read, but it never states the verb or scope in prose — the agent relies on the title 'List credit notes'. It also doesn't distinguish this from list_invoices or get_invoice, the nearest siblings in a 33-tool set.

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

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

There is no when-to-use guidance at all: nothing says whether to reach for this versus splose_list_invoices or splose_get_invoice, and no mention of paging through results despite pagination parameters existing. The agent must infer usage purely from the name.

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

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

The readOnlyHint annotation already declares this is a safe read, so the description's remaining job is scoping and return behavior. It adds the endpoint and the shape of returned records, but says nothing about pagination, ordering, or whether the list is account-scoped versus global, which matters for a list endpoint.

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

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

Two short sentences, front-loaded with the resource and what it returns. The trailing 'GET /custom-field/' adds little for an agent but costs almost nothing.

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

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

No output schema exists, so the description usefully compensates by naming the fields in each record (id, name, type, required, options). Missing only secondary details like pagination or result ordering.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no filtering inputs are available, matching an empty schema, and adds no misleading parameter claims.

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

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

States a specific verb+resource: the custom fields defined for patients, and enumerates the returned attributes (id, name, type, required flag, options). An agent can tell this apart from patient-listing tools like splose_list_patients, though it never explicitly contrasts with them.

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

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

Usage is only implied by the tool's name and the 'GET /custom-field/' endpoint reference. There is no explicit statement of when to call this (e.g. to discover field ids/options before reading or writing patient custom field values) and no named alternative for other field data.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds real value beyond that by disclosing the returned field set and the three possible status values, which matters because there is no output schema. It stops short of describing default ordering, whether archived records are excluded by default, or pagination behavior.

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

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

Two short sentences with no filler: the field inventory comes first, then the actionable status hint and endpoint. The phrasing is telegraphic rather than fully grammatical, but nothing is wasted 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 nine-parameter, zero-required list tool with no output schema, the description does the important extra work of naming the returned fields and status values. Remaining gaps (default sort order, archived exclusion defaults, paging flow) are partly absorbed by the schema's id_gt/id_lt descriptions, so the definition is close to complete.

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 nine filters (id_gt/id_lt paging, update_gt/update_lt, patientId, locationId, practitionerId, include_archived, status) are already documented in the schema. The description adds semantics only for status by tying 'Awaiting Payment' to amounts owed; the other eight parameters gain nothing from the description, so 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 enumerates exactly what a list-invoices call returns (number, dates, patient, totals, status, line items, payment ids) and names the endpoint GET /invoices, so the verb+resource is unambiguous. It does not, however, distinguish itself from the sibling splose_get_invoice (single invoice) or splose_list_payments, leaving that differentiation to the name alone.

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?

One explicit usage rule is given: 'Use status=Awaiting Payment for what is owed.' That is a genuine when-to-use hint, but there is no guidance on when to prefer splose_get_invoice, splose_list_payments, or how paging should be driven, so most selection decisions remain inferred from the tool name.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description's main added value is disclosing what comes back (title, address, phone, email, timezone, booking flag, service ids). It does not mention pagination behavior, the archived-exclusion default, or ordering, which are relevant to a list operation.

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

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

Two compact fragments that front-load the resource and then the payload fields, with the endpoint as a trailing anchor. No filler, though the field list is dense and slightly run-on.

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

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

For a parameterless-required, fully schema-documented list tool with readOnlyHint and no output schema, the description covers resource, returned fields and endpoint, which is enough to call it correctly. A brief note on paging/archived defaults would make it complete.

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

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

Schema description coverage is 100%, so all six parameters (id_gt/id_lt paging, title filter, update_gt/update_lt, include_archived) are already documented in the schema. The description adds no syntax or semantics beyond that, so the baseline 3 applies.

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

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

The description names the resource (practice locations) and enumerates the fields it exposes, and the endpoint line (GET /locations) confirms a read of the collection. Combined with the name splose_list_locations, an agent can distinguish it from the singular splose_get_location. It stops short of an explicit 'list all' scope statement, so a 4 rather than a 5.

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

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

Usage is only implied: the plural resource plus GET endpoint suggests 'use this to enumerate locations', and the presence of splose_get_location in the sibling set implies this is the bulk alternative. There is no explicit when-to-use/when-not or statement that filtering/pagination is handled by the id_gt/id_lt/update_gt parameters.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered externally. The description adds one genuinely useful behavioral note — 'The form content is included' — which warns the agent about heavier payloads, and it enumerates the possible status values. It says nothing about ordering, pagination, or result size, so it adds only modest value beyond the annotation.

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

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

Two short sentences plus an endpoint reference — front-loaded with the resource and the returned fields, with zero filler. Slightly terse rather than padded, which is the right failure mode here.

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

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

With no output schema, the description carries the return-shape burden and does so by listing the key fields and noting that form content is included. Combined with a fully documented 7-parameter schema and a readOnly annotation, an agent has enough to call it correctly; only ordering/default-result-set details are unstated.

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

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

Schema description coverage is 100% and all 7 filter parameters are documented in the schema with precise semantics (id_gt/id_lt paging, patientId, templateId, update date bounds, include_archived default false). The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific resource ('Forms sent to patients') and enumerates the fields returned (title, status, patient, appointment, template, submission time), plus the underlying endpoint GET /patient-forms, which makes the read scope unmistakable. It does not need to differentiate from siblings since no other listed tool returns patient forms, but it also doesn't say so explicitly.

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

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

There is no guidance on when to use this tool versus alternatives, no mention of prerequisites or auth, and no exclusions. The only implied usage comes from the schema's filter parameters (patientId, templateId, update dates), which the description never references.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds real context beyond that — a short-row projection (id, name, email, birthdate, phones, tags, alert, archived), id ordering, and a health-data handling caveat. It stops short of describing pagination mechanics or result caps, which the schema carries instead.

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

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

Four compact clauses with zero waste: purpose and shape first, the sibling redirect second, the privacy gating third, the endpoint last. Front-loading is correct and 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?

With 12 optional parameters and no output schema, the description fills the biggest gap by enumerating the returned row fields and their ordering — an agent knows what it gets back. Combined with the get_patient redirect and the privacy rule, 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% — every one of the 12 filters is documented inline, including pagination via id_gt/id_lt and the include_archived default. The description adds only the word 'filtered' and does not explain individual parameters, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('List patients (clients) of the practice'), plus scope details: filtered, id-ordered, short rows with a named field projection. It also explicitly contrasts itself with splose_get_patient for full records, so an agent can distinguish it from the closest sibling without opening a schema.

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

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

Names the alternative ('Use splose_get_patient for the full record') and the condition that selects it, and adds an explicit gating rule: 'only look people up when the user asks.' Both when-to-use and a when-not restraint are present, which is rare.

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

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

readOnlyHint=true already establishes this is a safe read, so the bar is lower. The description adds that results are id-bearing and feed payment recording, but says nothing about ordering, whether archived methods appear by default, or result volume — though the include_archived and cursor params partially cover those in the schema.

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

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

Two short clauses: what the resource is and why you'd call it, followed by the endpoint. Nothing is wasted and the useful context 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 trivial read-only list tool with fully documented params and no output schema, the description covers purpose and downstream use adequately. Adding return-shape or ordering detail would round it out, but the agent can call it correctly as written.

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 each of the five params (id_gt/id_lt/update_gt/update_lt/include_archived) is documented in-schema, including pagination intent. The description contributes no additional parameter meaning, so the baseline of 3 applies.

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

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

States the specific resource (payment methods), enumerates example values (cash, card, bank transfer), and says the returned ids are what's needed to record a payment, which separates it from splose_list_payments. It never names a sibling tool explicitly, so differentiation is implied rather than stated.

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?

"needed to record a payment" is a real workflow cue pointing at splose_record_payment, so usage context is implied rather than spelled out. There is no explicit when-not guidance and nothing about paging through results or when to prefer another lookup.

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

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

readOnlyHint=true already declares the safety profile, and 'GET /payments' merely restates it. The one piece of real added value is the response field enumeration (including credit allocations and settled invoices), which matters because there is no output schema. It does not disclose default filtering, ordering, or volume/rate behavior.

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

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

Two short fragments, zero padding, resource and contents front-loaded. It is slightly telegraphic — a bare noun phrase with no verb — but nothing is wasted.

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

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

With seven params, no required fields, no output schema and no annotations beyond readOnlyHint, the description should at minimum explain filtering defaults and how to page. It partially compensates for the missing output schema by listing returned fields, but leaves the caller to derive the paging contract entirely from schema text.

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% — every one of the seven optional parameters (id_gt/id_lt paging, patientId, update_gt/update_lt, locationId, include_archived) is documented in the schema. The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

The description enumerates what a payment record contains (number, amount, date, patient, location, method, invoices, credit allocations) and names the endpoint GET /payments, which implies a collection read. However it never states the verb (list/retrieve) and gives no differentiation from splose_get_payment or the payment-related siblings like splose_list_invoices and splose_list_payment_methods. An agent can guess the resource but must infer the operation from the name/title.

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

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

There is no guidance on when to use this vs splose_get_payment (single record) or splose_list_invoices. No exclusions, no mention of whether archived payments appear by default despite include_archived existing, and no mention of pagination workflow at the tool level.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered; the description adds the returned field set and the underlying endpoint, which is useful context. It says nothing about pagination (id_gt/id_lt cursors), default exclusion of archived records, or result ordering — all behaviors the agent must know to page correctly.

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

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

Two compact statements with no wasted wording, and the resource definition leads. The fragment style ('Practitioners (staff): …') omits an explicit verb, but the endpoint reference compensates.

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 attribute enumeration is a genuinely useful stand-in for the return shape, and the 10 parameters are fully covered by the schema. However, nothing is said about pagination cursors, the archived-record default, or filtering capability — gaps that matter for a list tool with this many inputs.

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

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

Schema description coverage is 100%, so every parameter is already documented, and the description adds no parameter-level meaning beyond what the schema states. The enumerated attributes describe output fields, not input filters, so the baseline 3 applies.

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

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

Names the specific resource (practitioners/staff), enumerates the attributes returned (name, email, profession, role, active flag, online-booking, timezone, location/service connections), and anchors to GET /practitioners. This distinguishes it from the singular splose_get_practitioner, though the description never states the 'list all' scope or that the result set is filterable.

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

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

There is no statement of when to use this versus splose_get_practitioner (single record) or splose_get_practitioner_availability. The schema exposes filters (email, isActive, roleName, firstname/lastname, update ranges, include_archived) but the description never signals that filtering or pagination is possible, so the agent must open the schema to discover it.

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

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

readOnlyHint=true already establishes the safe-read profile, so the description's contribution is the field enumeration and the GET /services endpoint. It omits pagination behavior, the archived-exclusion default, and whether the catalogue is truncated, which are behavioral facts an agent would want for an unpaginated-looking list call.

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

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

Two compact fragments with no filler, and the resource scope is front-loaded before the endpoint detail. The terseness borders on under-specification, which keeps it off a 5.

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

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

With no output schema, enumerating returned fields is genuinely useful. But for a 9-parameter list endpoint the description never covers filtering, cursor paging, or include_archived semantics, leaving the agent to rely entirely on the schema.

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

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

Schema description coverage is 100%, so code, name, type, tag, date and id cursor parameters are already documented. The description adds no filtering or paging semantics beyond listing fields, so this sits at the baseline.

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

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

The noun phrase 'The service catalogue: ...' plus 'GET /services.' makes the resource and retrieval nature inferable, but no explicit verb is given and nothing distinguishes it from the sibling splose_get_service. An agent must infer this is a bulk listing rather than a single-record fetch.

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

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

There is no when-to-use direction at all: no statement that this returns many services, no mention of using filters to narrow, and no routing to splose_get_service for a single record. Usage is only implied by the word 'catalogue'.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the useful fact that these are non-appointment billable/NDIS activities and lists the returned fields, but it says nothing about pagination behavior (id_gt/id_lt cursors, next_id_gt), archived-object handling, or result ordering.

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

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

A single compact sentence with the distinguishing trait ('Non-appointment billable activities') front-loaded, followed by the field inventory and endpoint. Nothing is redundant or padded.

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

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

With no output schema, the field list is genuinely helpful in telling an agent what a record looks like. However, for a paged list tool with cursor parameters, the description omits how to page through results and how include_archived affects output, leaving gaps an agent would hit in practice.

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

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

Schema description coverage is 100%, so all 8 filters (id cursors, start/update ranges, patientId, include_archived) are already documented in the schema. The description's field list describes output attributes rather than filter semantics and adds no format or interaction detail beyond the schema, so baseline 3 applies.

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

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

The description identifies the resource precisely ('Non-appointment billable activities (NDIS support activities)') and implicitly the list operation via the GET endpoint, and it enumerates the fields (patient, practitioner, service, item code, quantity, price, invoice id). It distinguishes the resource from appointments by calling it 'non-appointment', though it never says 'list' or contrasts with sibling list tools like list_invoices.

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

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

No guidance on when to use this vs. splose_list_invoices, splose_list_appointments, or splose_get_invoice, and no stated prerequisites or exclusions. The trailing 'GET /support-activities' is an implementation detail, not usage direction.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuine value by enumerating the returned fields (patient, practitioner, location, wanted services, preferred days/time, tags, active flag) — important since there is no output schema. It says nothing, however, about result volume, default filtering (e.g. are archived/closed entries returned by default), or ordering, which matters for a 13-param list tool.

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

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

Two compact fragments, front-loading the returned fields before the endpoint. No filler; each clause carries information. The 'GET /waitlists' tail is mildly redundant with the tool name but confirms the HTTP method.

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 field enumeration compensates usefully for return-value documentation, and all 13 parameters are covered by the schema. Still missing: default result behavior (does it return closed/archived entries?), pagination expectations, and any note that this is a clinic-wide list rather than a per-patient lookup, which leaves gaps for a high-parameter list tool.

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

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

Schema description coverage is 100%, so every one of the 13 parameters (pagination cursors, isActive, patientId, date ranges, include_archived, etc.) is already documented in the schema. The description mentions only the fields of a waitlist entry and the 'active flag', adding no filter semantics beyond the schema. Baseline 3 applies.

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

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

The description names the resource (waitlist entries) and the endpoint (GET /waitlists), and lists the fields each entry carries, so an agent can infer this is a read of waitlist records. However, it never states the action or scope in words ('list all waitlist entries'), relying on the field enumeration and the URL to convey purpose. It is adequate but vague as a purpose statement.

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

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

There is no guidance on when to use this versus alternatives (e.g. checking whether a patient is already waiting, or following up on closed entries), nor any prerequisites or exclusions. The agent must infer usage entirely from the tool name and the isActive parameter description.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false; the description reinforces this in plain language ('Marking twice has the same effect') and adds the underlying POST endpoints, which is useful context an agent cannot get from annotations. It omits failure behavior (e.g., arriving a cancelled appointment), so not a 5.

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

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

Three short sentences, front-loaded with the WRITE marker and the core action, followed by the edge case and then idempotency in descending priority. No filler.

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

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

For a two-parameter write with no output schema, the definition covers scope, group handling, idempotency, and the underlying endpoint. Missing only error/precondition behavior (already arrived, cancelled appointment, invalid patient for a non-group appointment).

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 documents patient_id as 'Group appointments only: the patient who arrived.' The description's group-appointment sentence largely restates that, adding only the implication that omitting patient_id targets the whole single appointment.

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 ('marks the patient of ONE appointment as arrived (check-in)') and flags the operation class with a leading 'WRITE:' tag. The capitalized 'ONE' plus the group-appointment note make the scope unambiguous versus sibling mutation tools like splose_update_appointment or splose_cancel_appointment.

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

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

Gives a concrete conditional: for a group appointment, pass patient_id to mark just that patient. It does not explicitly route the agent away from splose_update_appointment when the goal is a status change, and no preconditions (e.g., appointment must not be cancelled) are stated, so it stops short of full when/when-not guidance.

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

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

Only destructiveHint=true is supplied, so the description carries real weight and it does: it discloses non-idempotency ('calling twice records two payments'), irreversibility ('this server cannot delete a payment'), the amount ceiling relative to the balance owed, and the underlying POST /payments call. These are exactly the risky traits an agent must know before mutating financial data.

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

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

Front-loaded with the WRITE/MONEY tag and the core action, then warnings in descending urgency; no sentence is filler. The heavy semicolon-and-parenthetical packing makes it slightly harder to scan than it could be, but nothing 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 a 7-parameter financial mutation with no output schema, it covers risk (irreversible, non-idempotent), prerequisites (balance check, id sources), and the effect on the invoice and patient account. It does not say what is returned (e.g., a payment id) for later reference, which is a small remaining gap.

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

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

Schema coverage is 100%, so 3 is the floor, and the description genuinely adds semantics beyond it: amount must not exceed what is owed, and ids must be sourced from splose_get_invoice / splose_list_payment_methods. It does not cover paymentDate format or the locationId/patientId relationship, so it falls short of a 5.

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?

Starts with an explicit verb+resource marker ('WRITE, MONEY: records ONE payment received... against ONE invoice') and bounds the scope with 'ONE'. It also carves out what it is not ('does NOT charge anyone's card'), so an agent can distinguish it from splose_get_invoice and splose_list_payments without reading 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?

Gives concrete prerequisites and sequencing: check the outstanding balance via splose_get_invoice, source ids from splose_get_invoice and splose_list_payment_methods, confirm with the user, then pass confirm: true. It also states the negative case (no card charging) and the non-idempotency rule, which is exactly the when/what-not guidance an agent needs.

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?

Adds a side effect the annotations do not cover: Splose may notify the patient of the change per practice settings — a real-world consequence an agent should weigh before calling. Idempotency is restated from idempotentHint=true (no extra credit), and destructiveHint=true is left unexplained: the description never says what is lost or whether a reschedule is reversible.

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-loaded with the WRITE marker and the scope constraint, closing with the underlying endpoint. No filler, and the operationally important instruction (partial fields) arrives before the caveat.

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?

Annotations already carry idempotency and destructiveness, and there is no output schema to explain, so the remaining need is modest and mostly met. The gaps are what destructiveHint=true means in practice and what the call returns (updated appointment vs. no content), neither of which the description addresses.

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, but the description adds the partial-update contract ('only the fields to change'), which the schema does not state and which changes how the 8 properties should be populated. Field-level types/formats (UTC timestamps, integer ids) are correctly left to 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?

Opens with an explicit 'WRITE' verb tag, then names the resource and the exact mutable fields (time, service, location, practitioner, case, patient) scoped to ONE existing appointment. The 'ONE existing' phrasing plus the enumerated reschedule fields cleanly separates it from splose_create_appointment and splose_cancel_appointment without needing their schemas.

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?

'Send only the fields to change' is a concrete invocation rule that materially shapes the call. It stops short of naming alternatives or exclusion cases (e.g. use splose_cancel_appointment to cancel rather than blanking fields), so it is clear context rather than full when/when-not guidance.

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