Practice Better MCP by usefulapi

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

Far exceeds the annotation bar: it discloses there is no search endpoint, that it reads only the 500 most recent records (5 pages of 100), filters client-side, and that the `complete` flag reports whether every record was checked. This truncation caveat is exactly the kind of limitation an agent cannot infer from readOnlyHint/openWorldHint.

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 purpose and match fields, then the operational caveat, then the return shape and endpoint. 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, the description carries the return contract: at most max_results matches, same fields as list_clients, plus the `complete` boolean. Combined with the 500-record scan disclosure, an agent has everything needed to call and interpret results.

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 query, status and max_results. The description corroborates the case-insensitive text-match behavior and the max_results cap, but adds nothing beyond the schema's own field descriptions. Baseline 3.

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

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

States a specific verb (search) and resource (client records) with the exact match fields (name, preferred name, email). It implicitly distinguishes itself from practice_better_list_clients by noting it returns 'the same fields as practice_better_list_clients', signaling this is the filtered variant.

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 context for when to use it: looking up clients by name/preferred name/email. It references the sibling list tool for field parity but does not explicitly say 'use list_clients to enumerate all clients' or give any when-not condition, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds valuable negative scoping ('Settings, integrations and the bio are not returned') and identifies the endpoint. It doesn't discuss auth or error behavior, but for a read-only GET that's partially covered by annotations.

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

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

Two dense sentences front-load the resource and field list, then add the exclusions and endpoint. Every clause earns its place with zero filler.

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

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

For a no-arg read tool with annotations covering safety and no output schema, the description is largely complete: it names the resource, enumerates returned fields, and states what is excluded. The only minor gap is no note on pagination/error handling, but that's low-value for this shape.

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

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

Zero parameters, so there is no parameter semantics to convey; per the rules, 0 params baseline is 4. The description correctly implies a no-arg call by not mentioning any inputs.

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

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

States a specific resource (the practitioner/API user behind the connection) and enumerates exactly what fields it returns: id, name, title, timezone, default currency, role flags, and practice id/name. It also names the HTTP endpoint, making the mapping unambiguous and distinguishing it from siblings like get_client or list_practitioners.

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

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

The description is clear that this returns the authenticated caller's own account via the connection, not an arbitrary practitioner. It does not explicitly state when-not-to-use or name an alternative, but the framing ('behind this connection') effectively constrains usage. No explicit exclusions beyond the field-level negatives.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds that results are governed by the practitioner's booking settings and that each slot carries start, end and duration, but says nothing about result limits, pagination, or how the date window behaves.

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 that front-load the core purpose and the returned fields, with the prerequisite and endpoint appended. Slight redundancy in restating the required ids that the schema already marks as required, 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?

With no output schema, the description does the necessary work of describing the return shape (start, end, duration per slot). It is adequately complete for a read-only availability lookup, though it omits how the date range extends beyond the start day and how many slots come back.

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

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

Schema description coverage is 100%, so the baseline is 3. The description echoes only the required practitioner_id and service_id and the notion of a starting day; the optional filters (type, package_id, location_id) and the enum values are 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?

The description names a specific verb and resource — opening booking slots for one practitioner and one service starting from a given day — and even previews the returned fields (start, end, duration). It is unambiguous, but it never names or differentiates itself from any sibling tool, and the schema's other filters go unmentioned.

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?

'Needs a practitioner id and a service id' establishes a prerequisite, and 'follows the practitioner's booking settings' hints at scope. However, there is no explicit when-to-use guidance, no statement of the alternatives (e.g., listing practitioners or services first), and no exclusions such as how far ahead slots are returned.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value by disclosing the exact field scope and, notably, which sensitive fields (DOB, address, insurance, emergency contacts, notes, health history) are NOT returned, which is meaningful beyond annotations.

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

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

Two dense sentences with the resource and field scope front-loaded, followed by exclusions and the endpoint. 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 must describe the return shape, and it does so thoroughly — both included fields and deliberately excluded fields. An agent knows exactly what calling this tool yields.

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 parameter is documented as 'Client record id.' The description restates 'by id' but adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('One client record by id') and enumerates the returned fields, making it clearly a single-record fetch. That contrasts with siblings like practice_better_find_clients and practice_better_list_clients without ambiguity.

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

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

The phrase 'by id' implicitly distinguishes this from the find/list siblings, but the description never explicitly states when to use this versus those alternatives. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered, but the description adds real value by enumerating the returned line-item fields and, more importantly, the fields deliberately omitted (descriptions, payment history, billing contact). That omission note is genuine behavioral context the annotations do not provide.

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

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

Two sentences, zero filler, front-loaded with the return payload before the exclusions, with the endpoint path tacked on last. Every clause carries information.

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

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

For a single-parameter read tool with full schema coverage and clear annotations, the description covers what an agent needs, and with no output schema present the run-down of returned and omitted fields is genuinely useful. Only minor gaps remain, such as behavior on an unknown invoice id.

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?

One required parameter (invoice_id) with 100% schema description coverage, so the schema already documents its meaning. The description only implies the id selects a single invoice and adds no format or sourcing detail beyond that, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource ('One invoice by id'), the fields it carries (line items with date, quantity, amount, tax, plus totals), and the endpoint path. An agent can cleanly separate it from the sibling list_invoices, which returns many.

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 'one invoice by id' implicitly signals the single-record counterpart to list_invoices, and the explicit exclusion of descriptions, payment history and billing contact tells the agent when this tool will not satisfy a need. It never names list_invoices as the alternative, so the routing is left partly to inference.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds real value by disclosing field exclusions ('Booking notes and session notes are not returned') and the underlying GET endpoint, letting an agent know the response is a partial view.

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?

Dense and front-loaded: returned fields first, then the two special-case caveats, then the endpoint. Every clause earns its place, though the raw HTTP path is somewhat redundant metadata for an agent caller.

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

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

With no output schema, the description compensates by listing the returned fields and explicitly noting what is excluded, so an agent knows what it will and won't get. It is close to complete for a two-parameter read tool; only pagination/error behavior is unaddressed, which is minor 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%, and the record_id parameter is already documented in the schema as group-sessions-only. The description restates that constraint with a bit of added rationale ('one client's view'), so it does not meaningfully exceed the schema and the baseline 3 applies.

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

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

States a specific verb+resource ('One session (appointment) by id') and enumerates the returned fields (date, duration, service, practitioner, client, location, status). This clearly separates it from the sibling list_sessions, which returns many sessions rather than one.

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 one conditional usage rule ('For a group session pass record_id to see one client's view'), which is genuinely helpful. However it never states when to prefer this over list_sessions or other lookup tools, so overall 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description still adds real behavioral context: newest-first ordering, a hard page cap of 100 records, and the explicit list of omitted fields. It stops short of describing cursor semantics or empty-result behavior, so not a 5.

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

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

Three sentences, front-loaded with what the tool returns and how it orders results. Every sentence carries distinct information: return fields, exclusions, page size, sibling routing, and the endpoint. 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?

There is no output schema, so the description's enumeration of returned fields and exclusions is doing necessary work. Combined with the page-size cap, ordering guarantee, and alternative-tool routing, an agent has everything needed to call this correctly against 8 optional parameters.

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 every parameter (limit, status, after_id, before_id, has_account, child_records, modified_after/before) is already documented in the schema. The description only restates the 100-record page cap, which duplicates the limit maximum, so baseline 3 applies.

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

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

States a specific verb and resource ('List client records') plus ordering ('newest first') and the exact field set returned, so an agent knows precisely what it gets. It explicitly distinguishes itself from practice_better_find_clients, which is the nearest sibling.

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

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

Names the alternative tool and the condition that selects it: 'To look up one person by name or email use practice_better_find_clients.' It also sets scope by declaring which fields are not returned (DOB, address, insurance, notes), so the agent can rule this tool out for detail lookups.

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 cover the read-only, non-destructive safety profile, so the description adds real value: it discloses the 'newest first' ordering and, importantly, that 'the answers are never returned', which prevents an agent from expecting submitted content. It does not mention pagination behavior beyond the schema's cursor hints.

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 that front-load the resource and the return fields, then add the key limitation. The trailing 'GET /consultant/formrequests' endpoint restates nothing harmful but is slightly redundant system detail.

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, eight-parameter list tool with full schema coverage but no output schema, the description usefully summarizes the returned shape and the answers-omitted behavior. The main missing piece is the relationship to the sibling list_forms tool, which would complete the selection picture.

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 (limit, cursors, completed, record_ids, date filters, practitioner_ids) is already documented. The description only reinforces the newest-first ordering and does not add filter syntax or date-format detail beyond the schema, so baseline 3 applies.

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

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

Specific verb (List) plus resource (forms sent to clients), and it enumerates the returned fields (form, client id, practitioner, started/completed, dates). It implicitly distinguishes itself from the sibling list_forms by specifying requests 'sent to clients', but 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?

There is no explicit when-to-use guidance and no mention of alternatives such as list_forms. The description only states what the tool returns, leaving the agent to infer that this is the request-tracking list rather than a form-template list.

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

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

Annotations already declare it a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds real value by disclosing the response payload scope ('id and name only') and that the source is a scoped practice endpoint, information the annotations do not convey.

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

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

A single tight line with the resource scope front-loaded, the returned-field qualifier next, and the route last. No filler sentences.

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

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

No output schema exists, and the description compensates by stating exactly what each item contains. Pagination and filtering are covered by the schema, so the only small gap is the lack of any hint about result volume or when the list is empty.

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 four parameters (limit, before_id, after_id, team_for) are fully documented in the schema, including the enum and cursor semantics. The description adds no parameter-level detail, which matches the baseline for high coverage.

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

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

States a specific verb (List) and resource (form templates), and enumerates what counts (intake forms, questionnaires, consent forms), which distinguishes it from the sibling practice_better_list_form_requests. It also declares the returned fields ('id and name only') and the underlying route.

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

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

There is no explicit when-to-use guidance and no mention of alternatives, despite a genuinely confusable sibling (practice_better_list_form_requests) that an agent could easily pick by mistake. Usage is only implied by the resource name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: newest-first ordering, the exact field set returned, and the deliberate exclusion of payment history and line items. It does not mention pagination mechanics or result limits, but the schema covers those.

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 dense clauses: the operation plus returned fields first, then the exclusion and the alternative tool, then the HTTP path. No filler, nothing repeated from the schema, and the most decision-relevant information is front-loaded.

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

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

There is no output schema, and the description compensates by enumerating the returned fields and stating the sort order, which is what an agent most needs for a read-only list. Combined with 100% schema coverage for the 8 input parameters, the definition is close to self-sufficient; pagination response shape (next_page.before_id) is only implied via the schema.

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

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

Schema description coverage is 100%, with every parameter (limit, cursors, record_ids, payment_status, practitioner_ids, date bounds) documented inline, so the schema does the heavy lifting. The description adds no parameter-level meaning — it never mentions the available filters or the cursor convention — so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('List client invoices') plus the sort order ('newest first'), and enumerates the fields returned (number, date, totals, amount due/paid, status, client, practitioner). It also explicitly separates itself from practice_better_get_invoice, so an agent can distinguish this list tool from its detail sibling without opening either schema.

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

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

Gives a clear when-not condition ('Payment history and line items are not in the list') and names the alternative tool to use instead (practice_better_get_invoice). However, it offers no guidance on the filter dimensions the tool exposes (payment_status, record_ids, date ranges) or when a filtered list is preferable to an unfiltered one, so routing is covered but selection strategy is not.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set and endpoint path but says nothing about pagination ordering or result limits beyond what the schema's cursor parameters already document.

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 gives resource, semantics, returned fields and endpoint with zero filler. The key scoping information is front-loaded.

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

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

For a simple read-only list tool with no output schema, the description names the returned fields, which compensates reasonably for the missing output schema, and the schema carries pagination. Only minor gaps (e.g. ordering of results) remain.

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 three parameters (limit, after_id, before_id) are already fully documented in the schema, including pagination direction. The description adds no parameter-level meaning beyond that 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?

Specific verb+resource ('List the package definitions') with a parenthetical that defines what a package is ('bundles of sessions or programs'), which usefully distinguishes it from sibling tools like list_services and list_sessions. It also names the returned fields (id, name, SKU) and the underlying endpoint.

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: an agent can infer this is the listing tool for the packages resource. However, there is no explicit statement of when to use it versus list_services or list_sessions, nor any 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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuine behavioral context beyond the annotations: the result set includes both practitioners AND admin users (broader scope than the name implies), the exact fields returned, and the underlying endpoint GET /company/administration/members.

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

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

Two sentences plus endpoint: the purpose and returned fields come first, the downstream usage hint second, and the raw endpoint last. No filler or redundant 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?

There is no output schema and no input schema, so the description carries the full burden and largely meets it by enumerating the returned fields and clarifying that admin users are included. It omits pagination/ordering behavior for what is presumably a full list, which is a minor remaining gap.

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

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

The tool takes zero parameters, so the baseline for this dimension is 4 by rule. The description correctly implies a no-argument full-list call and instead directs the agent how to use the returned ids, adding value where there are no inputs to document.

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 admin users of the practice), and enumerates the returned fields (id, name, role flags, activation status). It is clearly distinguishable from siblings like list_clients or list_invoices by resource, though it never explicitly names an alternative.

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 line 'Use the ids to filter sessions and invoices' gives a downstream workflow hint, which implies why an agent would call this tool. However, there is no explicit when-to-use vs when-not, no mention of alternatives such as the singular get_account, and no prerequisites for the call.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned-field inventory, which is useful behavioral context, but says nothing about pagination behavior or result ordering beyond what the schema already states. 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?

A single front-loaded sentence: verb and resource first, then the field inventory and endpoint. Nothing is wasted, though the trailing 'GET /consultant/services' is somewhat redundant with the name and adds little for an agent.

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 no output schema, the description usefully enumerates the fields returned (id, name, duration, group or 1-1, session types, SKU), which substitutes for the missing output schema. Annotations cover safety. Only the absence of guidance relative to sibling list tools 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 description coverage is 100%, including cursor semantics for before_id/after_id, the limit range, and the team_for enum values, so the schema does the heavy lifting. The description adds no parameter-level meaning. Baseline 3 is correct.

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

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

The description gives a specific verb and resource ('List the services (appointment types) the practice offers') and pre-empts ambiguity by clarifying that services are appointment types. It also enumerates the returned fields, so an agent knows exactly what this call yields. It does not explicitly distinguish itself from sibling list tools, keeping it 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?

There is no guidance on when to use this versus other list tools (e.g. list_practitioners, list_packages) or any prerequisite/precondition. The GET endpoint hint gives a technical anchor but no selection criteria, so usage must be inferred from the name alone.

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

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

Annotations already carry readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: results are ordered newest first and booking/session notes are deliberately excluded from the payload.

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?

Dense and front-loaded: purpose and returned fields first, then the exclusion, then filters, then the endpoint. Every sentence carries information, though the trailing 'GET /consultant/sessions.' is of limited value to an agent.

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

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

With no output schema, the description usefully enumerates the returned fields and what is omitted, and the schema documents pagination cursors. It stops short of describing the response envelope (next_page cursor flow) an agent needs to page through results.

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 (including the before_id/after_id cursors and the group boolean) is already documented in the schema. The description restates the filter categories and adds the ordering fact, which only marginally exceeds what the schema provides.

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 sessions (appointments)') and enumerates the fields returned, which separates it from the singular practice_better_get_session. It does not explicitly name a sibling alternative, so it falls just short of the top score.

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 enumeration ('date range, practitioner, client record, service or group/1-1') gives context for how to narrow results, but there is no when-to-use guidance relative to practice_better_get_session for a single appointment, and no explicit 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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the underlying endpoint (GET /tags) and the return shape (id and name), which is useful context, but says nothing about pagination behavior or rate limits beyond what the schema already carries.

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

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

Two short sentences with zero waste; the resource and its purpose are front-loaded before the endpoint reference. Nothing is repeated from annotations or schema.

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

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

For a read-only, fully documented list endpoint with annotations and no output schema, the description covers what the tool is, what it returns at a high level, and how tag ids relate to client records. Only pagination/return-volume expectations are left unstated, which is minor given the schema documents the cursors.

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 cursor parameters (limit, after_id, before_id) are fully documented in the schema itself, including the note that before_id is the normal cursor. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (tags) and immediately scopes what they are: labels used to organize clients, returned as id and name. The resource is distinct from every sibling list_* tool, so an agent can distinguish 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: 'A client record carries tag ids' hints that this tool resolves those ids to names, but there is no explicit when-to-use statement, no alternatives named, and no exclusion conditions. Adequate but leaves the agent to infer the workflow.

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