IntakeQ MCP by usefulapi

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

Annotations only supply destructiveHint=true, so the description carries extra weight and delivers: it discloses upsert behavior (tag created if absent) and idempotency (re-adding is a no-op), which clarifies the mutation semantics beyond the annotation. It still omits anything about permissions or error cases, keeping it short of a 5.

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

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

Three short sentences, front-loaded with the action, followed by the two behavioral caveats and the endpoint. Nothing is redundant and no sentence could be dropped 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 two-parameter mutation with no output schema, the definition covers what the tool does, its side effect, and its idempotency, which is enough to call it correctly. Minor gaps remain around the shape of a successful response and auth requirements, but neither is essential here.

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

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

Schema description coverage is 100%, so both parameters (client_id, tag) are already documented in the schema. The description adds no syntax, format, or constraint detail beyond it, matching the baseline for a fully documented schema.

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

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

Names a specific verb (add) and resource (tag on a client), and the HTTP call (POST /clientTags) pins down exactly what is invoked. It does not need to disambiguate from siblings since none of the listed tools touch tags, so explicit sibling routing is absent but not required.

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: an agent can infer this is the tool for attaching tags to an existing client. There is no statement of when to use it versus e.g. saving a client, nor any prerequisite (such as the client needing to exist first).

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 destructiveHint=true, but the description adds real information beyond that: the change affects the client's booking and cannot be undone through the API. It does not disclose secondary effects such as client notifications, refunds, or cancellation-fee behavior, which a destructive operation would ideally mention.

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 action, followed by the critical irreversibility warning and the API mapping. Every sentence carries distinct information with no padding.

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

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

With only two parameters, full schema coverage, no output schema, and destructiveHint already present, the description covers what an agent needs to call it safely. Missing only peripheral detail such as whether the client is notified or whether cancellation fees apply.

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 both parameters (appointment_id required, reason optional) are documented in the schema. The description only restates that the reason is optional, adding no extra semantics such as supported formats or examples, so the baseline of 3 applies.

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

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

States a specific verb (Cancel) plus resource (an appointment), and the irreversibility note makes clear this is distinct from intakeq_update_appointment, which modifies rather than terminates a booking. An agent can select it without opening the schema.

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

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

Gives clear contextual guidance: this is irreversible via the API and the recovery path is to book a new appointment. It does not explicitly contrast with intakeq_update_appointment or state when cancellation is appropriate, so it falls short of the full when/when-not bar.

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 only destructiveHint=true and a title in annotations, the description adds genuine behavioral context: all fields are mandatory, Status is restricted to two values, and client email notification is only legal when Status=Confirmed. It does not mention downstream side effects such as reminder scheduling or what happens on duplicate booking, so it stops short of full disclosure.

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

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

Five short sentences, densely front-loaded, with the prerequisite source listed before the constraint rules. No filler or restatement of the title.

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

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

For an 8-required-parameter mutation with no output schema, it covers ID sourcing, enum constraints and the conditional email rule. It omits any hint of the returned object (e.g. new appointment id) or error behaviour on conflicts, which would make it fully self-sufficient.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds cross-parameter meaning the schema cannot express: the conditional dependency between Status and SendClientEmailNotification, and where the ID parameters are obtained. UtcDateTime format is left entirely 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?

'Book an appointment in the PracticeQ scheduler' gives a specific verb (book/create) and resource, and the endpoint line (POST /appointments) confirms the operation. It is clearly distinguishable from siblings like intakeq_update_appointment and intakeq_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?

It explicitly routes the agent to intakeq_get_booking_settings as the source for PractitionerId, ServiceId and LocationId, which is a real prerequisite instruction. However, it never states when to prefer this over intakeq_update_appointment or what to do when the appointment already exists, so exclusions are absent.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds useful context by naming the fields returned and citing the backing endpoint (GET /appointments/{id}), but it says nothing about behavior for a missing/invalid id, error handling, or auth requirements, so it goes only modestly beyond the annotations.

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

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

A single dense sentence with the core operation and return scope front-loaded, followed by an endpoint citation. Nothing is padded, though the trailing API-path reference is slightly more for implementers than for tool selection.

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

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

With no output schema, the description compensates well by enumerating the returned fields (client, practitioner, status, price, telehealth link, cancellation details). It does not describe response shape or error cases, but for a simple one-parameter read it is nearly sufficient.

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

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

There is a single parameter documented at 100% schema coverage, so the schema already carries the semantics of appointment_id. The description adds no format, source, or constraint detail beyond it, which is the expected baseline for a fully documented single-param schema.

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

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

States a specific verb (fetch) and resource (one appointment), then enumerates the returned facets, which clearly distinguishes it from intakeq_list_appointments. An agent can identify the operation without opening the schema.

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

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

Usage is only implied: it is evident this is the single-record counterpart to intakeq_list_appointments, but the description never says when to prefer it over the list tool or over related single-item tools like intakeq_get_invoice. No prerequisites or exclusions are stated.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuine value beyond that by disclosing the returned data shape (locations, services with duration and price, practitioners) and the underlying REST endpoint 'GET /appointments/settings'. It does not mention auth or pagination, but for a parameterless read this is solid.

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

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

One sentence plus an endpoint reference, front-loaded with the returned collections and ending with the concrete purpose (ids for appointment creation). Nothing is padded or repeated.

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 available, the description correctly carries the burden of describing the return payload and does so at a useful level of granularity. It could go slightly further on response structure or pagination, but an agent has enough to call and use it correctly.

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

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

The tool takes zero parameters, so the schema baseline of 4 applies and there is nothing for the description to disambiguate. The mention that the response contains ids is helpful framing rather than parameter detail.

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

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

States a specific verb (List) and enumerates the exact resources returned — locations, services with duration and price, and practitioners — then ties it to the downstream goal of creating an appointment. This clearly distinguishes it from siblings like intakeq_list_practitioners, which returns only one of these collections.

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

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

The phrase 'the ids you need to create an appointment' gives explicit context for when to reach for this tool (setup/discovery prior to intakeq_create_appointment). It stops short of naming the alternative or stating exclusions, but the intended moment of use is unambiguous.

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=true annotation already establishes this as a safe, non-mutating read, so the bar is lower. The description adds the returned field set and the underlying IntakeQ endpoint, but says nothing about pagination, ordering, or empty-result 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?

One front-loaded sentence covering action, scope and payload, plus a short endpoint reference. No filler; every clause carries information.

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

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

With no output schema, the description usefully enumerates what each record contains (code, description, start/end date, source treatment note), which is genuinely helpful for an agent. Minor gaps remain around result volume and ordering, but the core is complete for a one-parameter read 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% and the single client_id parameter is fully documented in the schema, so baseline 3 applies. The phrase 'for one client' reinforces cardinality but adds no syntax or format detail beyond the schema.

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

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

States a specific verb (List) and resource (diagnoses) scoped to one client, and enumerates the returned fields. No sibling tool covers diagnoses, so the scope is unambiguous against tools like intakeq_get_note or intakeq_list_clients.

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

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

Usage is implied by the narrow scope ('for one client'), and there are no genuinely competing siblings to route away from. However, it never states when this is appropriate or what prerequisite (a valid client_id) is required, so guidance remains implicit.

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 as a safe read, and the description usefully discloses what the response contains (questions/answers, consent forms, linked appointment), which is real added value. However it says nothing about failure behavior for an unknown id, auth requirements, or rate limits.

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

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

Two tight sentences with the resource and payload front-loaded. The trailing 'IntakeQ: GET /intakes/{id}.' is mildly redundant with the annotations but harmless and confirms the read verb.

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

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

With no output schema, the description partially compensates by enumerating the returned sections. For a single-parameter read tool with annotations and full schema coverage, this is close to complete; only error behavior is 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 description coverage is 100% and the single intake_id parameter is documented as a GUID in the schema itself. The description adds no further meaning about the identifier, so baseline 3 applies.

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

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

States a specific verb ('Fetch') plus the exact resource ('one intake questionnaire') and enumerates the payload contents (questions/answers, consent forms, linked appointment). The singular 'one intake' implicitly distinguishes it from intakeq_list_intakes.

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: fetching a single intake by id versus the sibling list tool. There is no explicit statement of when to prefer this over intakeq_list_intakes, nor any prerequisite or error condition 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?

readOnlyHint=true already covers the safety profile, and the description adds real value by enumerating the response payload (line items, taxes, discounts, payments, totals, amount due), which matters since no output schema exists. It does not cover failure modes (e.g. invalid or unknown invoice id), keeping it short of a 5.

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

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

Two compact sentences, front-loaded with the action and its payload, with zero redundant wording. The endpoint reference is the only extra and is genuinely useful for cross-referencing.

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-param, read-only fetcher the definition is nearly complete: it names the resource, the identifier, and the fields returned, compensating for the absent output schema. Only error/edge-case behavior is 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?

Only one parameter with 100% schema description coverage, so the schema fully documents invoice_id. The description adds no syntax, format, or lookup guidance beyond what the schema already states, which is the expected baseline.

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

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

States a specific verb and resource ('Fetch one invoice') and lists the salient contents (line items, taxes, payments, totals, amount due), which sets it apart from the plural sibling intakeq_list_invoices without naming it. The REST mapping (GET /invoices/{id}) reinforces the single-resource scope.

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 singular 'one invoice' implies this is for retrieving a known id, contrasted with intakeq_list_invoices, but no explicit when-to-use, prerequisites, or error conditions are given. Usage is inferable rather than stated.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's main value-add is disclosing the returned content (all Q&A plus the linked appointment). It says nothing about permissions, error behavior when the id is unknown, or whether linked-appointment data can be null.

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 payload description. The trailing API route mapping ('IntakeQ: GET /notes/{id}') largely restates information already available from the name and schema, though it is compact.

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

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

For a one-parameter read tool with no output schema, the description covers what is returned (full Q&A and linked appointment) and annotations cover the safety profile. Nothing an agent needs in order to call it correctly 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% and the single note_id parameter is documented as a GUID in the schema, so the description adds no format or constraint detail beyond it. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (Fetch) and resource (one treatment note) plus the scope of the payload (every question and answer, linked appointment). The singular 'one' implicitly separates it from intakeq_list_notes, but neither 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: an agent can infer this is the by-id lookup counterpart to intakeq_list_notes. There is no statement of when to prefer this over listing, nor any prerequisite or failure-mode guidance.

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

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

annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description usefully adds the pagination cap ('Max 100 per page') and the underlying endpoint, which is context beyond the annotations, but it says nothing about default sort order or what happens when no filters are supplied.

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, filter capabilities front-loaded, pagination constraint second, endpoint reference last. No filler and nothing buried.

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

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

For a read-only list tool with full schema coverage and no output schema, the description covers filters, pagination and identity. It could note whether results are sorted or what an unfiltered call returns, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so every parameter is already documented with type, pattern and enum. The description's filter list largely restates what the schema provides, so it adds no syntax or default-value information beyond the schema. Baseline 3 applies.

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

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

States a specific verb (Query) and resource (appointments) and enumerates the filterable dimensions, which distinguishes it from intakeq_get_appointment or intakeq_create_appointment. It stops short of naming any sibling explicitly, so it is clear but not sibling-routing.

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

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

Usage is implied by the filter list – you call it to search/filter appointments rather than fetch one. There is no explicit when-to-use, no when-not-to, and no pointer to intakeq_get_appointment for a single record, so the agent must infer the choice.

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, and the description adds genuinely useful behavior beyond that: the 100-record page cap, the differing return payloads with and without include_profile, and the concrete upstream endpoint (GET /clients). It stops short of discussing ordering, total counts, or rate limits, so it is strong but not exhaustive.

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

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

Three dense sentences: purpose/search axes first, return-shape and pagination limits second, source endpoint last. Nothing is repeated from the schema and no sentence is 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?

With 10 parameters and no output schema, the description carries the return-value burden and does so by describing both payload shapes and the page limit. It omits result ordering, whether a total count is returned, and behavior when no filters are supplied, which would matter for a zero-required-param search.

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%, making 3 the baseline, but the description adds cross-parameter meaning the schema does not: that searching covers name, email, or client number, that custom fields can act as a filter, and that include_profile changes the shape of the response rather than just a flag. This is meaningful value above the per-field schema text.

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

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

The description names a concrete verb+resource ('Search the practice's clients (patients)') and immediately enumerates the five search axes (name/email/client number, date ranges, external id, custom field). It also clarifies the practitioner-side terminology (clients = patients), leaving no ambiguity about what the tool returns. No sibling competes for this purpose.

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

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

It implies when the tool is useful by listing searchable dimensions, and the include_profile flag is framed as an optional expansion. However, it never names an alternative (e.g. save_client for writes, get_client_diagnoses for clinical data) or states exclusions such as 'use X to create a client'. Usage is inferable but not prescribed.

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

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

Annotations only declare readOnlyHint=true, so safety is covered elsewhere. The description adds real behavioral context the schema/annotations do not: the default status filter (only Completed) that an agent could otherwise get wrong, the full status enumeration, and the 100-record page cap. It does not mention auth or rate-limit behavior, keeping it short of a 5.

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

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

Three tight sentences, front-loaded with what is queried and what comes back, then the default filter, then pagination and the underlying endpoint. No sentence is filler.

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

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

For a read-only list tool with full schema coverage and no output schema, the description is nearly complete: it covers scope, default filtering, and pagination. It could still note how the listed summaries relate to fetching a full form via intakeq_get_intake, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters in detail. The description restates the 'all' flag and the page size rather than adding format, defaults, or edge cases beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Query submitted intake questionnaires') and even enumerates the summary fields returned (client, status, questionnaire, practitioner, dates). It is easy to distinguish from intakeq_get_intake, which fetches a single form. However, it never names or contrasts itself with a sibling, so it falls short of the 5 bar.

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 explains the default scope ('By default only completed forms; set all=true for every status'), which is genuine conditional guidance. But it never says when to reach for this tool versus intakeq_get_intake or intakeq_list_questionnaires, so usage against alternatives is only implied.

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

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

Annotations only declare readOnlyHint=true; the description adds the pagination ceiling ('Max 100 per page') and the composition of each returned record, which is real behavioral context beyond the annotation. It stops short of noting auth requirements, whether filters combine with AND, or ordering.

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

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

Three short sentences, front-loaded with the filter set and followed by return shape and page limit. The trailing 'IntakeQ: GET /invoices' endpoint note is mildly redundant but cheap and confirms the operation type.

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

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

With no output schema, the description usefully compensates by describing per-invoice contents, and it covers pagination bounds for an 8-parameter optional-filter tool. Minor gaps: whether filters are conjunctive, default sort order, and behavior on out-of-range pages.

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

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

Schema description coverage is 100%, with each parameter's format (yyyy-MM-dd, enum statuses, numeric client id) fully documented in the schema. The description merely summarizes the filter dimensions, so it adds little beyond what the schema already carries; baseline 3 applies.

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

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

States a specific verb and resource ('Query invoices') plus the exact filter dimensions available, so the agent immediately knows this is a list/query operation rather than the single-invoice sibling. It also previews the payload contents ('items, payments and amounts due/paid'), which no sibling shares.

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

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

The filter list implies when to reach for this tool (by client, date range, status, practitioner), but there is no explicit when-to-use or when-not, and no routing to intakeq_get_invoice for a single record. Usage is inferable but not guided.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the pagination cap and the underlying endpoint, which gives light context, but says nothing about what a 'summary' returns or ordering behavior. Adequate but not rich.

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

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

Two short sentences plus an endpoint reference, with the query dimensions front-loaded and no wasted words. The trailing API endpoint is mildly extraneous for an agent but does not hurt readability.

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 could explain what fields a note summary contains, but it only implies 'summaries' versus full notes. For an 8-parameter list tool this is minimum viable rather than 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 eight parameters are already fully documented in the schema; the description merely names the same filter dimensions (client, lock status, date range, last-updated). Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

States a specific verb (Query) and resource (treatment note summaries) with the queryable dimensions spelled out. The word 'summaries' quietly distinguishes it from the singular intakeq_get_note, but no sibling is named explicitly, so it stops short of a 5.

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

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

Lists the available filters but gives no when-to-use guidance, no prerequisites, and does not point to intakeq_get_note or any other alternative for retrieving full note content. The agent must infer usage purely from the list-style name and 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?

The readOnlyHint annotation already establishes this is a safe read. The description adds the endpoint mapping (GET /practitioners) and the shape of returned fields, which is useful since no output schema exists, but it says nothing about pagination, result limits, or whether the list is scoped to the authenticated account or all accounts.

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

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

One compact sentence plus an endpoint reference, with the resource and return fields front-loaded. Nothing is redundant and nothing is padded.

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

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

For a simple read-only list tool with no parameters, the description covers purpose and return fields, which substitutes adequately for the missing output schema. Only pagination or volume behavior is left unstated, a minor gap at this complexity level.

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; there is nothing for the description to clarify beyond what the empty schema already communicates.

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

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

States a specific verb (List) and resource (practitioners) and enumerates the returned fields (id, name, email, external id), which no sibling tool covers. It does not explicitly contrast itself with the other list_* siblings, but the resource is unambiguous enough to select it 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?

Usage is only implied: an agent can infer this should be called when practitioner records are needed, but there is no statement of when to prefer it over alternatives or any precondition notes. For a zero-argument list tool the implied case is largely sufficient, so a middling score is fair.

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 value beyond that by disclosing the shape of the response (id, name, archived, anonymous) in the absence of any output schema. It says nothing about pagination, ordering, or whether archived templates are included or filtered, which are the remaining behavioral gaps.

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

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

A single front-loaded sentence that leads with the action and resource, then the payoff ('the ids you need'), then the return fields. The trailing 'IntakeQ: GET /questionnaires.' costs little and maps the tool to its underlying endpoint, aiding debugging.

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 input parameters and no output schema, the description carries the response burden and does so by listing the key fields plus the workflow purpose. It is nearly complete, lacking only pagination/ordering behavior and any mention of filtering archived items.

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 there is nothing for the description to disambiguate and the baseline of 4 applies. The parenthetical describing return fields is a bonus rather than parameter guidance, which is the correct emphasis for a no-arg tool.

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

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

States a specific verb and resource ('List the intake questionnaire templates in the account') and scopes it explicitly to templates rather than intakes or sent questionnaires, which separates it from siblings like intakeq_list_intakes and intakeq_send_questionnaire. The parenthetical enumerates the returned fields, so the agent knows exactly what it gets.

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 ids you need to send one' clearly establishes this as the prerequisite step for intakeq_send_questionnaire, giving a concrete when-to-use context. It stops short of naming the sibling tool explicitly or stating when not to use this (e.g., for already-sent intakes), so it is clear context rather than full when/when-not routing.

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

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

Annotations only declare destructiveHint=true, so the description carries real load: it discloses the surprising silent-upsert behavior (a create call can update an existing record), the field-clearing hazard on updates, and the required fetch-then-resubmit workflow. These are non-obvious behaviors an agent must know and are not derivable from 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?

Front-loads the create/update distinction and the dedup caveat before the workflow tip and format notes. Sentences are dense with information and earn their place, though the run-on ClientId sentence could be split for readability.

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?

Covers the genuinely hard parts of a 37-param, zero-required, no-output-schema upsert tool: mode selection, dedup risk, and profile round-trip. It still leaves most individual field semantics undocumented, which matters given the low schema coverage, but the operationally critical context is present.

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

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

With 37 parameters and only 22% schema description coverage, the description should compensate but largely does not. It adds meaning for ClientId behavior and the Unix-ms date format, but leaves the insurance, address-component, CustomFields, and status fields entirely unexplained beyond their names. 'Field names are IntakeQ's own' is a non-explanation.

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 pair (create/update) and resource (client) and immediately explains the two modes. It is easily distinguished from siblings like intakeq_list_clients, which it even references. An agent knows exactly what this does without opening the schema.

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

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

Explicitly states when to pass ClientId versus when to omit it, warns that omission triggers automatic matching by first name + email/phone, and names the alternative/prep step (intakeq_list_clients with include_profile=true). This is precisely the when/when-not/alternatives guidance the rubric rewards.

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 emphasized 'This MESSAGES THE CLIENT' discloses the outward-facing side effect beyond the destructiveHint annotation, and 'omit ClientEmail to force SMS' reveals channel-selection behavior that is not in the schema. 'Returns the new intake' also discloses the response despite there being no output schema.

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

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

The client-messaging warning is front-loaded, followed by identification rules, optionality, and the return value in a few tight sentences. 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?

Covers identification, required vs optional fields, side effects, channel behavior, and the return value, which is everything needed to invoke a 7-param tool with no output schema. Missing auth/rate-limit notes are minor.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds conditional logic the schema cannot express: the ClientId vs ClientName+ClientEmail/ClientPhone identification paths and the omission-of-ClientEmail SMS trick. This meaningfully enriches the terse schema field descriptions.

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

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

States a specific verb (Send) and resource (intake questionnaire) plus the delivery channels (email or SMS). It is clearly distinguishable from sibling intakeq_list_questionnaires, which only lists templates.

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?

Explains the two mutually exclusive ways to identify the client (ClientId, or ClientName plus contact info) and notes PractitionerId is optional. It gives strong in-context guidance but does not state when not to use this tool or name a preferred alternative.

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

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

Annotations only supply destructiveHint=true; the description adds genuinely useful behavior: required-field semantics, immutable fields, and a state-transition rule (no Confirmed → WaitingConfirmation). It does not cover auth requirements, notification defaults, or the response shape, so it is solid but not exhaustive for a mutation 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?

Three tight sentences, front-loaded with the mutable fields and immediacy of the required params. Slight redundancy with the schema's required list and the API path suffix, but 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 7-param destructive mutation with no output schema, the description covers required params, immutability, and state rules adequately. Missing permission/auth notes and what a successful update returns, which are minor given no output schema exists.

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 86%, so the baseline is 3. The description earns above baseline by clarifying that UtcDateTime must be sent even when unchanged ('send the current time to keep it') and by noting fields that exist in the API but not the schema (client, practitioner) as immutable.

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 (change/update) and resource (appointment) plus the exact mutable fields: time, service, location, status, reminder type. Easily distinguished from siblings like intakeq_create_appointment, intakeq_cancel_appointment, and intakeq_get_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 strong operational guidance: Id and UtcDateTime are required, send the current time to keep it, and include only fields being changed. It also states exclusions (client/practitioner cannot be changed; Confirmed cannot revert to WaitingConfirmation), but never explicitly routes to siblings such as cancel or create when this tool is the wrong choice.

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