intakeq

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

Beyond the destructiveHint annotation, the description discloses two useful behavioral traits: the tag is auto-created if missing (a resource side effect) and re-adding an existing tag is a no-op (idempotency). This adds real value the annotations do not cover, though it says nothing about permissions or the response.

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

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

Three short sentences, front-loaded with the core action and then the two behavioral caveats. No padding; every sentence earns its place.

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

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

For a two-parameter mutation with a fully documented schema and no output schema, the description covers purpose, idempotency, side effect, and even the underlying endpoint. Authentication or error behavior is absent, but little else is needed.

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 (tag, client_id) are already fully documented in the schema. The description adds no syntax or format detail beyond that, 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 verb and resource: 'Add a tag to a client.' It is unambiguous about what the tool does, though with no competing tag-related sibling it has no need to differentiate and does not do so.

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 'Add a tag to a client'; there is no explicit when-to-use, when-not-to-use, or alternative (e.g. save_client for creating clients). It is adequate but leaves context to inference.

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

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

Annotations declare destructiveHint=true, but the description adds the crucial detail that the change cannot be undone through the API and that a new booking is the recovery path. That operational consequence goes meaningfully beyond the annotation, though it says nothing about auth scope or side effects on notifications/billing.

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 plus the endpoint mapping; the irreversibility warning is front-loaded where it matters. Every clause earns its place with no filler.

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

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

For a destructive two-parameter mutation with no output schema, the description covers the essential risk and recovery path, and the annotations carry the safety profile. It could still mention what the response confirms, but nothing an agent needs to invoke 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 both parameters are already documented by the schema. The description only notes that the reason is optional, which is already evident from the required list — 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 (cancel) and resource (appointment), and the sibling set (create/get/update/list appointments) makes the distinct action unambiguous. An agent can tell exactly which operation this is 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?

Cleanly states the operating context: cancellation is irreversible and a replacement must be booked, so the agent knows when this tool is appropriate. It stops short of naming alternatives (e.g., update_appointment for rescheduling) or when not to cancel, so it is clear context rather than full routing 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 only provide destructiveHint=true; the description goes further by stating that all fields are required by IntakeQ, that Status must be Confirmed or WaitingConfirmation, and that SendClientEmailNotification is gated on Status=Confirmed. It does not describe failure modes or the response shape, but adds meaningful constraint context 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?

Four short sentences, front-loaded with the core action and then prerequisites, constraints, and endpoint in order of decreasing importance. No filler or restatement of the tool name.

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 tool with no output schema, the description covers prerequisites, enum constraints, and the conditional field. It could say more about what a successful booking returns or side effects (e.g., client notification behavior), but it is close to complete for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-field semantics (the Status/SendClientEmailNotification dependency) and points to the source tool for three of the IDs. That provenance guidance is genuinely useful information the schema does not carry.

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 ('Book an appointment in the PracticeQ scheduler'), which cleanly separates it from siblings like intakeq_cancel_appointment and intakeq_update_appointment. The added endpoint reference (POST /appointments) reinforces exactly what operation is performed.

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 routes the agent to intakeq_get_booking_settings to obtain PractitionerId, ServiceId and LocationId before calling, and states the conditional rule for SendClientEmailNotification. It lacks an explicit 'do not use when' clause, but the context is otherwise 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely new context by enumerating the returned payload (client, practitioner, service, location, status, price, invoice, telehealth link, cancellation details), which matters because no output schema exists. It stops short of covering error/not-found behavior or access requirements.

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 front-loads the action and resource, then lists the payload; the trailing endpoint mapping (GET /appointments/{id}) is compact and useful. Nothing is padded or 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 one-parameter read with no output schema, the field enumeration is the key missing piece an agent needs and it is present. It does not address failure modes such as an unknown or deleted appointment id, which leaves a small 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% for the single 'appointment_id' parameter, so the schema already carries its meaning. The description adds no format, source, or lookup guidance beyond what the schema provides; baseline 3 is appropriate.

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

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

States a specific verb ('Fetch') and resource ('one appointment'), and the enumerated field list makes the returned scope concrete. The singular 'one appointment' implicitly separates it from intakeq_list_appointments, but the sibling is never named or contrasted explicitly, so it falls short of the top tier.

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 infers this is the single-record lookup keyed by appointment_id, versus the list variant. There is no explicit when-to-use, when-not-to-use, or named alternative for lookups by other keys.

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 is a safe read. The description adds the concrete return contents and the REST endpoint mapping, but says nothing about pagination, size limits, or auth requirements. With annotations covering the safety profile, this modest added context merits a 3.

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

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

A single sentence that front-loads what is returned and closes with the endpoint reference. No filler, nothing 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?

No output schema exists, so the description correctly compensates by enumerating the returned data (locations, services with duration/price, practitioners). It is nearly complete for this simple parameterless GET, though it omits any note on response shape or pagination.

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; the baseline for a 0-param tool is 4.

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

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

The description names a specific verb (list) and enumerates the exact resources returned — locations, services with duration and price, and practitioners — plus the underlying endpoint. This clearly differentiates it from siblings like intakeq_list_practitioners, which covers only one of the three 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?

It states the motivating context — 'the ids you need to create an appointment' — which implicitly positions it as a prerequisite step before intakeq_create_appointment. There are no explicit exclusions or alternatives named, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered by structured data. The description adds that records originate from a treatment note, which is mild contextual value, but says nothing about pagination, ordering, empty results, or auth requirements. With annotations carrying the safety burden, a 3 is appropriate.

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

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

Two compact sentences, front-loaded with the purpose before the endpoint detail. Every clause earns its place: the field list doubles as return-value documentation and the endpoint adds integration context.

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 naming the returned fields (code, description, start/end date, source note). This is close to complete for a simple one-parameter read tool; only pagination/ordering behavior is left unspecified, which is a minor gap.

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

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

Only one parameter exists and schema coverage is 100%, so the schema already documents client_id fully (numeric id, ClientId/ClientNumber). The description adds no syntax or format detail beyond reinforcing that a single client is targeted. 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 ('List') and resource ('the diagnoses recorded for one client'), then enumerates the returned fields. No sibling tool deals with diagnoses, so it is trivially distinguishable, and the endpoint reference (GET /client/{clientId}/diagnoses) reinforces the single-client 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?

Usage is implied by the scoping phrase 'for one client' — the agent can infer this retrieves a specific client's diagnoses rather than a bulk list. However, there is no explicit when-to-use guidance, no mention of prerequisites (e.g., a valid client id must exist), and no alternatives named among the 18 siblings.

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 non-destructive read, so the description's 'Fetch' framing repeats rather than extends it. It does add useful scope information about what gets returned, but discloses nothing about auth needs, error behavior when the id is missing, or response size for large intakes.

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 first front-loads what is returned, the second gives the equivalent API endpoint. No filler or repetition 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 a read-only single-record fetch with no output schema, the description covers the operation, the identifier, and the shape of the return payload. It is nearly complete; only the absence of any linkage to how an intake_id is obtained keeps it short of full marks.

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 intake_id parameter is documented in the schema as a GUID, so the description need not compensate. It adds no format or constraint detail beyond what the schema already provides, 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 (fetch) and resource (one intake questionnaire) and enumerates the payload: every question and answer, consent forms, and linked appointment. The singular 'one' implicitly contrasts with intakeq_list_intakes, though it never names the sibling 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 presence of intakeq_list_intakes and the word 'one' suggest this is the single-record retrieval path, but there is no explicit when-to-use or when-not-to-use statement and no stated prerequisite (e.g., needing an id from the list call).

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds genuine value by disclosing the shape of the result (line items, taxes, discounts, payments, totals, amount due) in the absence of an output schema, though it omits error/not-found behavior and any auth or rate-limit context.

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

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

Two tight sentences with zero filler; the purpose and the returned fields are front-loaded and the API mapping (GET /invoices/{id}) is appended last where it does not interrupt reading.

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 both the operation and the returned content, which is what an agent most needs. It stops short of error handling and alternative selection, leaving only minor gaps given the low 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?

There is a single parameter (invoice_id) with 100% schema description coverage, so the schema fully documents it. The description adds no syntax, format, or sourcing detail for the id, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch one invoice') and enumerates what the response contains (line items, taxes, discounts, payments, totals, amount due). The singular 'one invoice' implicitly separates it from intakeq_list_invoices, but the sibling is never named, so differentiation relies on inference.

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: needing the details of a known invoice by id. There is no explicit when-to-use guidance, no mention of when to prefer intakeq_list_invoices, and no note on what to do if the id is unknown or the invoice is not 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?

readOnlyHint=true already establishes the safe-read profile, so the description's additional disclosure that the response includes every question and answer plus the linked appointment is genuinely useful. However, nothing is said about permissions, error behavior when the id is invalid, or pagination/size 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 payload contents front-loaded. The trailing 'IntakeQ: GET /notes/{id}' is slightly redundant with the tool name but cheap and mildly useful for endpoint mapping.

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?

A single-parameter read tool with an annotation and no output schema, where the description covers both the input (via schema) and the returned payload shape. Only the absence of failure/auth behavior keeps it short of a 5.

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 one parameter and schema coverage is 100% with its own description ('The note's id (a GUID)'), so the schema fully documents it. The description adds no format or sourcing detail beyond the schema, which matches the baseline 3 for fully covered parameters.

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) and explicitly scopes it to a single record with its Q&A and linked appointment, which clearly separates it from intakeq_list_notes.

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

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

The word 'one' implies the single-record counterpart to list_notes, but the description never names the alternative or states when to prefer this over listing or get_intake. Usage 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?

The readOnlyHint annotation already establishes this is a safe read. The description adds the useful cap of 'Max 100 per page', but that same limit is already stated in the page parameter's schema description, and nothing is said about auth, sort order, or how multiple filters combine.

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

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

Two tight sentences, front-loaded with the capability and filters. The trailing 'IntakeQ: GET /appointments' endpoint reference is marginally useful and slightly redundant with the tool name, keeping it just under a perfect score.

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, zero-required list tool with only readOnlyHint as annotation coverage, the description covers the filter surface and pagination limit adequately. It omits how filters combine and default ordering, and with no output schema the return shape is left undocumented, but nothing critical to invoking 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 description coverage is 100%, so all eight parameters (including the status enum and date patterns) are already documented in the schema. The description merely restates the filter categories without adding format/syntax detail, so the baseline 3 applies.

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

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

The description gives a specific verb (Query) plus resource (appointments) and enumerates the five filter axes, so an agent immediately knows this is a filtered list operation. It does not name a sibling such as intakeq_get_appointment to draw the boundary explicitly, 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: the filter list suggests the tool is for browsing/filtering many appointments, which contrasts with the single-record get_appointment sibling. There is no explicit when-to-use, when-not-to-use, or named alternative, so it lands at minimum-viable.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: the page size cap of 100, and the fact that the returned shape changes materially with include_profile (light fields vs. address, insurance, tags, custom fields, linked clients) – important for an agent deciding what it will receive.

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

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

Two tightly-packed sentences plus the endpoint reference; the most decision-relevant facts (search capability, output variance via include_profile, page cap) are front-loaded and nothing 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 no output schema, the description correctly compensates by describing both return shapes and the 100-per-page limit. It stops short of covering edge cases such as the deleted_only 10-day window or how custom_fields keys are formed, though those are fully documented in the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description still adds value: it clarifies that 'search' spans name/email/client number and spells out the concrete fields that include_profile toggles on, which the schema only summarizes as 'full client profile'.

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 ('Search the practice's clients (patients)') and enumerates the exact filter dimensions available (name/email/client number, date ranges, external id, custom field). This is clearly distinct from siblings like intakeq_get_client_diagnoses or intakeq_save_client without needing to name 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 implied by the enumeration of filter criteria, but there is no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as intakeq_get_client_diagnoses for richer client data. The include_profile note hints at choosing between lightweight and full results, which is a partial substitute for 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 supplied, the description adds real context: the default status filter, the enumerated status values (Sent, Partial, Completed, Offline), the 100-per-page cap, and the underlying endpoint. This goes meaningfully beyond the annotations, though it says nothing about ordering or total-count 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?

Front-loads the core purpose and packs filter defaults, pagination, and endpoint into a compact block with no filler. Slightly dense but each 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 no-output-schema list tool with nine fully documented params, the description covers default filter behavior, pagination limit, and the shape of returned summaries, which is sufficient to call it correctly. Ordering and pagination iteration guidance are the only minor omissions.

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 nine parameters; baseline is 3. The description adds the status enumeration for all=true and reiterates the page cap, but adds little else beyond the structured fields.

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 submitted intake questionnaires') and clarifies it returns summaries rather than full forms, which distinguishes it implicitly from intakeq_get_intake. It does not name a sibling alternative 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?

Gives a concrete default ('only completed forms') and the override ('set all=true for every status'), which is useful usage context. However, it never states when to prefer this over intakeq_get_intake or intakeq_list_questionnaires, so guidance is implied rather than explicit.

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

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

With readOnlyHint=true already covering safety, the description adds real value: it discloses the payload shape ('items, payments and amounts due/paid') and a pagination constraint ('Max 100 per page'). Auth requirements and whether the last-updated filters differ in semantics from issue-date filters remain unstated.

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 filters, then payload, then pagination. The trailing 'IntakeQ: GET /invoices.' endpoint reference is low-value padding for an agent but not harmful.

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 summarizes the return payload and page cap. All parameters are covered by the schema, and no required params exist. It stops short of stating pagination termination or total-count behavior, but the essentials for a correct call are present.

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

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

Schema description coverage is 100%, so all 8 parameters are already documented with types, patterns and enum values. The description only echoes the same filter dimensions (client, issue date range, status, practitioner, last-updated range) without adding syntax or interaction guidance, 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?

Starts with a specific verb ('Query') on a specific resource ('invoices') and enumerates the filterable dimensions plus what each record contains. It reads clearly as a bulk-list operation, distinct from the singular intakeq_get_invoice, though it never names that sibling 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 implied by the filter list (client, date range, status, practitioner, last-updated) but there is no explicit statement of when to use this versus intakeq_get_invoice or when to combine filters. No prerequisites or exclusions are given.

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 only needs to add context. It adds the 100-records-per-page cap and the underlying endpoint, but the cap largely duplicates the schema's page description and nothing is said about total counts, ordering, or pagination end conditions.

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 sentences plus an endpoint reference, front-loaded with the capability and filters before the page limit. The 'IntakeQ: GET /notes/summary' fragment is implementation trivia that adds little for an agent, keeping it just under top marks.

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

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

There is no output schema, so the description carries the burden of describing what comes back, and 'note summaries' is left undefined (which fields, whether locked/deleted notes are excluded by default). For a read-only list tool the safety profile is covered, but the return semantics are only gestured at.

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 (page, client, status, dates, updated_since, deleted_only) are already documented, including the lock-status enum values. The description only restates the filter categories at a high level and adds no format or defaulting 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?

States a specific verb (Query) and resource (treatment note summaries) and enumerates the filter dimensions, so it is clearly not the single-note sibling intakeq_get_note. It stops short of explicitly naming that sibling or contrasting list-vs-get, so it is clear but not fully self-differentiating.

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 available filters implies when this tool is useful, and 'summaries' hints it is the bulk/overview route rather than full note retrieval. However, there is no explicit when-to-use vs intakeq_get_note guidance and no stated prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds value by disclosing the return shape (id, name, email, external id), which matters because there is no output schema, plus the underlying endpoint. It stops short of noting pagination or result caps.

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

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

Two tight sentences, front-loaded with the action and resource, followed by the field list. Every clause earns its place with no redundancy.

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

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

For a zero-param, read-only list tool with no output schema, the description supplies the missing return-field information, which is the main thing an agent would otherwise lack. Nothing essential for calling it correctly is absent.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There are no argument semantics to explain, and the description correctly spends no words on them.

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) scoped to the account, and even enumerates the returned fields. It is clearly distinguishable from sibling list tools like intakeq_list_clients and intakeq_list_notes.

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 strongly implied by the name and the simple no-argument nature of the tool, but the description never states when to use it versus alternatives or any preconditions. Adequate but with a clear gap for the usage dimension.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavior beyond that: it enumerates the returned fields (id, name, archived, anonymous) and names the upstream endpoint (GET /questionnaires). It stops short of pagination or result-size 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?

A single front-loaded sentence delivers purpose, return fields, and downstream use, followed by a compact endpoint reference. 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?

With no output schema present, the description usefully names the relevant returned fields, which compensates well. It omits any note on pagination or whether archived templates are returned by default, a minor gap for a list endpoint.

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 are zero parameters, so the schema carries no semantics to supplement and the baseline is 4. Nothing in the description is needed or missing on the parameter side.

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 (intake questionnaire templates) and even enumerates the returned fields, which lets an agent confirm it's the template catalog rather than submissions. It does not explicitly contrast itself with the nearby intakeq_list_intakes sibling, so the template-vs-submission distinction must be inferred from the word '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?

'the ids you need to send one' clearly signals the use context: call this before intakeq_send_questionnaire to obtain an id. No explicit exclusions or when-not-to-use guidance is given, but the routing intent 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?

Annotations only declare destructiveHint=true, but the description adds high-value context: a create call can silently update an existing client via name/email matching, and sending a partial profile risks unintentionally clearing fields. These are exactly the 'what gets destroyed' facts an agent needs 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?

Five sentences, each load-bearing: purpose, branching rule, hidden matching behavior, update workflow, and format conventions. The critical create-vs-update distinction 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 destructive 37-param upsert with no output schema, the definition covers the essential footguns (dedup matching, field clearing) and format conventions. It could say more about the create path's result or required-field expectations, but nothing critical to calling it safely 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?

With 37 params at 22% schema coverage, the description cannot fully compensate. It adds important conventions (ClientId behavior, 'field names are IntakeQ's own', Unix-ms dates), but the large majority of fields remain undocumented in both schema and description, so it earns only 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?

States a specific verb+resource ('Create a client, or update one') and immediately clarifies the create-vs-update branch via ClientId. It is clearly distinguishable from siblings like intakeq_list_clients, which it references for the update workflow.

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 describes when the tool creates vs updates, discloses the dedup matching fallback (first name + email/phone), and prescribes the correct update workflow (fetch full profile first). This is genuine when/how guidance rather than inference.

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

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

destructiveHint=true is already declared, and the description adds meaningful context: it messages the client, the delivery channel is chosen by omitting ClientEmail to force SMS, and the call returns the new intake. It stops short of stating irreversibility or 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?

Four tight sentences, side-effect warning front-loaded immediately after the purpose, no filler. The endpoint reference is a small extra 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 'Returns the new intake' note covers the return adequately, and channel selection is explained. For a 7-parameter messaging tool, some delivery failure or idempotency behavior is still 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 the baseline is 3, but the description adds real semantics beyond the schema: 'omit ClientEmail to force SMS' and the ClientId-vs-ClientName identification rule. It does not explain QuestionnaireId sourcing beyond what the schema already notes.

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 ('Send an intake questionnaire to a client') and immediately flags the externally visible effect ('This MESSAGES THE CLIENT'). It is clearly distinguishable from sibling tools like intakeq_list_questionnaires or intakeq_get_intake.

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

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

Gives the alternative identification paths (ClientId, or ClientName plus ClientEmail/ClientPhone) and notes PractitionerId is optional. It does not state when to prefer ClientId over name-based lookup, but the routing conditions are otherwise explicit.

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

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

Annotations only supply destructiveHint=true and a title; the description adds genuine behavioral context beyond that, notably the immutable fields and the state-transition restriction that blocks Confirmed → WaitingConfirmation. It still does not disclose permission/auth requirements or defaults for notifications, so a 4 rather than 5.

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

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

Three compact sentences, front-loaded with the operation and followed by the rules an agent needs. Every clause carries information (required fields, partial-update convention, two constraints) with no filler.

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

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

For a 7-parameter mutation tool with no output schema, the description covers the key calling constraints (required fields, immutable fields, status restriction) and partially addresses update semantics. It omits auth requirements and mention of side effects like the SendClientEmailNotification default, leaving a minor gap.

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

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

Schema coverage is high (86%), so the baseline is 3, but the description adds real meaning: it clarifies that Id and UtcDateTime are required even when unchanged (send current time to keep it) and that only changed fields should be included. This goes beyond the schema's per-parameter descriptions.

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

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

States a specific verb and resource ('Change an appointment's time, service, location, status or reminder type') and enumerates exactly which fields can be modified, distinguishing it from sibling tools like intakeq_create_appointment, intakeq_cancel_appointment and intakeq_get_appointment. The reference to 'PUT /appointments' confirms the operation.

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

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

Provides clear usage context: send the current time to keep it, include only fields being changed, and two exclusion rules (client/practitioner not changeable, Confirmed cannot revert to WaitingConfirmation). It does not explicitly name an alternative sibling (e.g., cancel vs update), so it falls just short of a 5.

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