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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful shape information beyond that: clients is always a list, and one login (a 'client access') may span multiple clients, which prevents an agent from assuming a single-client return.

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 that are front-loaded with the returned content, followed by the multi-client clarification. The parenthetical 'a parent seeing two children' earns its place as a concrete illustration, though it is slightly verbose for the amount of information conveyed.

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 burden of explaining the return, and it names the three top-level components (practice, signed-in client, clients list). It stops short of describing auth requirements or error conditions, but for a zero-parameter read tool it is largely complete.

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

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

The tool takes zero parameters, so the baseline is 4. The description references the 'clients' field of the response, which adds a little meaning without implying any input the agent might try to supply.

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 makes clear this returns the account context: the practice, the signed-in client, and every visible client. The verb is only implied (the name get_account carries the action), and no sibling is named or contrasted, but an agent can immediately tell this apart from list_appointments or list_documents.

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 rather than stated — an agent infers this is the identity/context call to make before filtering other resources by client. There is no explicit when-to-use, no prerequisites, and no alternative named among the many list_* 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?

Annotations already cover safety (readOnlyHint=true), so the description's added value is the cost/comparative behavior: it is 'cheaper than paging the billing collections.' That is genuine context beyond the annotations, though it says nothing about auth scope or result size.

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 waste; the return contents are front-loaded and the second sentence earns its place by justifying use over the alternative.

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

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

For a single-param, read-only overview tool with no output schema, the description conveys what comes back (balance due, per-category counts) and when it beats the alternative. Enough to call it correctly, though it omits return-shape details.

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 sole 'view' enum is fully documented in the schema, so the schema does the heavy lifting. The description adds nothing about the view parameter, making the baseline 3 appropriate.

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

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

States a specific verb and resource: returns 'balance due and per-category counts for the Client Portal account.' It implies the distinction from the billing collections listing, but never names the sibling tool (simplepractice_list_billing_items) outright, so differentiation is by inference rather than explicit.

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

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

The second sentence gives clear context for use: it is a cheap existence check ('whether anything is there') that avoids paging billing collections. That routes the agent well, though it states no explicit when-not or names the alternative tool by 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 and openWorldHint, so the safety profile is covered. The description adds genuinely non-structured context by warning that returned text is third-party authored and must be treated as data, never as instructions - a useful prompt-injection guard. It still says nothing about error behavior for an unknown id or payload size.

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

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

Two sentences, front-loaded with the core purpose and followed by the one non-obvious safety caveat. No filler and nothing that repeats structured fields.

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 describing what comes back (body, questions, answers). Parameters are fully covered by the schema, so nothing critical is missing for a 2-param read tool, though error/empty-result behavior is unstated.

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

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

Schema description coverage is 100%, with both 'id' and the 'view' enum fully documented in the schema itself, so the baseline is 3. The description's mention of 'body or its questions and answers' loosely gestures at what full retrieval returns but adds no syntax or semantics beyond the schema.

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

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

States a specific verb and resource: retrieving one document request in full, including its body/questions and prior answers. It is distinguishable from the sibling simplepractice_list_document_requests by the singular scope and the 'in full' framing, 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 only implied by the wording 'one document request in full' - an agent can infer it should call this rather than the list tool when it needs a single record's contents. There is no explicit when-to-use statement, no prerequisites, and no named alternative.

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

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

Annotations already mark the tool read-only and idempotent, and the description adds further context: it never returns the credential, makes exactly one authenticated request, and distinguishes 'no credential' from 'credential rejected' from 'clientsecure.me-side problem.' No contradiction with annotations.

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

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

The description is compact and well-structured: action, outputs, safety, and usage each get focused sentences. There is no filler, repetition, or unnecessary 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 zero-parameter diagnostic tool with safety-related annotations, the description fully specifies what it does, what it reports, and when to use it. It even supplies the failure-hint semantics that would otherwise be missing without an output 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?

The tool has zero parameters, so there is no parameter documentation burden and schema coverage is effectively complete. The baseline of 4 applies because no parameter meaning is needed.

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 diagnostic action: resolves the credential, makes one authenticated request to clientsecure.me, and reports credential source, acceptance, RTT, and a plain-English failure hint. This clearly distinguishes it from sibling tools, which perform real operations rather than diagnose the connection.

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

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

It explicitly says to call this 'when a real tool fails and you want to know which hop broke.' This gives the agent a clear trigger condition and implies the alternative—using the actual SimplePractice tools—without ambiguity.

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?

Although annotations already cover the read-only/open-world safety profile, the description adds substantial non-obvious behavior: pageSize is capped at 50, hasMore flags that older rows and their counts are truncated, and readAt is null on unread items. It also warns that returned text is third-party and untrusted, which is real operational context annotations cannot 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?

Front-loaded with what the tool returns, then layers pagination and security notes. Every sentence earns its place and none is boilerplate.

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

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

With no output schema, the description carries the return-value burden and does so well: it covers row content, the unread indicator (readAt null), pagination limits, and the reliability of returned text. Nothing an agent needs to call and interpret this correctly is missing.

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

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

Schema coverage is 50% — view is fully documented in the schema, but pageSize has no schema description. The description compensates by explaining pageSize's max (50) and the meaning of the resulting hasMore/pagination truncation, adding genuine semantics beyond the schema.

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

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

States a specific verb+resource (list announcements) and scopes it precisely: 'Announcements the practice has posted to the Client Portal.' This is easily distinguished from siblings like list_documents, list_appointments, and list_document_requests, which cover different resources.

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

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

The context makes the tool's purpose obvious and the readAt note implies the unread-filtering use case, but there is no explicit when-to-use, when-not-to-use, or naming of an alternative sibling. Usage is only implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: pagination exists ('Pages by number') and the two status values map to distinct result sets. It does not mention auth requirements, rate limits, or how many pages/items to expect.

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

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

Three short sentences, front-loaded with the resource and scope, then status semantics, then pagination. Nothing is redundant, though the pagination note is thin enough that it could have carried the default and max page size at little cost.

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 paginated list with no output schema, the description covers what the tool returns and the status filter, and annotations carry the safety profile. It omits practical pagination detail (default page size, 50-item cap, how to detect more pages), which matters for a tool that explicitly pages by number.

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 50%: view and status are documented in the schema, page and pageSize are not. The description elaborates the semantics of status beyond the schema's terse 'Which side of the pending-confirmation filter to read' and hints that page is a page number, partially compensating for the undocumented pagination parameters, but pageSize and its 50-item cap are left unexplained.

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 clear verb (list) and resource (appointments) with scope qualifier (Client Portal), so the agent knows exactly what it returns. It is the only appointment-listing tool among the siblings, but the description never explicitly differentiates itself from adjacent list tools like simplepractice_list_documents or simplepractice_list_announcements.

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 context is implied rather than stated: it explains what the status values mean but never says when to call this tool versus alternatives, nor any prerequisites or exclusions. An agent can infer it is the read path for appointments, but there is no explicit 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 and openWorldHint, so safety is covered; the description adds non-obvious behavior beyond that: that an empty result is a legitimate answer rather than an error, and that paging is cursor-based with nextCursor fed back as 'before'. It stops short of describing the shape of returned records, but that is partly delegated to the view parameter.

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 what is returned and followed by the two most operationally important caveats (empty-is-valid, cursor paging). No filler, though the paging sentence is slightly terse relative to the ambiguity of the 'before' 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 a read-only, zero-required-parameter list tool with no output schema, the description covers the resource, the empty-result case, and pagination, and the enums are documented in the schema. What an agent needs to call it correctly is essentially present; only return-shape and sibling selection are unaddressed.

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

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

With only 50% schema description coverage, the description compensates meaningfully: it enumerates the kind values informally and explains the 'before' cursor's provenance (the returned nextCursor from a previous call), which the schema only names. pageSize and view semantics remain schema-only, keeping it below a 5.

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

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

The first sentence names the specific resources (invoices, statements, superbills, receipts, account history) and scopes them to the Client Portal, so an agent knows exactly what record type it retrieves. It lacks an explicit verb like 'list' and does not name sibling tools such as get_billing_overview, but the resource plus portal scope is distinctive enough to separate it from the other billing 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?

It gives real interpretive guidance — an empty list is valid, and many practices bill entirely outside the portal — plus how to page. However, it never states when to choose this over get_billing_overview or get_account, and no exclusions or prerequisites are given, so routing is left 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 declare readOnlyHint/openWorldHint, but the description adds materially beyond them: the hard truncation behavior (at most pageSize, max 50, newest rows only) and the non-obvious caveat that hasMore:true means older rows AND the counts over them may be missing — a subtle correctness trap for an agent. It also flags that returned text is third-party authored and untrusted, an explicit prompt-injection warning. This is exactly the beyond-annotation context this dimension rewards.

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 sentences, front-loaded with the resource identity, then the filter tip, the pagination caveat, and the security warning. Every sentence carries distinct operational value — no restatement of the tool name or 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 must carry return-value semantics, and it does the important part: hasMore, the pageSize cap, newest-first ordering, and the missing-counts caveat. The main remaining gap is that it never hints at what fields an individual request row contains, which an agent must discover by calling.

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 67%: includeBody and outstandingOnly are described in the schema, but pageSize has no description there. The description compensates by stating 'Returns at most pageSize (max 50) of the newest rows', adding the truncation/ordering meaning the schema lacks, and reiterates the outstandingOnly filter meaning. Small residual gap around pageSize's default/ordering semantics alone.

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 resource — 'paperwork the practice has sent' — and enumerates the concrete types (consents, questionnaires, contact and insurance forms, Good Faith Estimates, shared files), so an agent knows exactly what is listed. It does not explicitly distinguish this from the sibling get_document_request (singular) or list_documents, which keeps it out of 5 territory, but the resource is unambiguous.

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

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

It gives a concrete use case for one parameter ('Use outstandingOnly to see just what still needs the client's attention'), which is real guidance. However, it says nothing about when to reach for this list versus get_document_request for a single item or list_documents, so sibling routing is left 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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses ordering (newest first), the max page size, the meaning of hasMore, the caveat that counts over truncated rows may be incomplete, and an untrusted-content/prompt-injection warning about third-party text. That last point is high-value behavioral context no structured field 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?

Three tight sentences, each carrying distinct information: what the resource is, pagination semantics, and a safety warning. Front-loaded with the resource definition; 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?

No output schema exists, so the description appropriately describes the return shape (newest rows, page cap, hasMore) and adds a security caveat. For a single-optional-parameter read tool, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain that pageSize caps the page and is at most 50, and that the rows returned are the newest, but it omits the default value (50) and the exclusive-minimum constraint present in the schema.

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

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

States a specific resource with scope: 'Files the practice has shared through the Client Portal.' The Client-Portal framing distinguishes it from sibling simplepractice_list_document_requests, which covers requests rather than shared files.

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 resource definition, and the pagination note ('hasMore: true means the page came back full') implicitly tells the agent when to page further, but there is no explicit when-to-use or when-not-to-use guidance versus siblings like list_document_requests.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely useful context beyond them: results are scoped to the Client Portal and are masked (no full card numbers), which tells the agent what it will and will not receive back.

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

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

Two short clauses, front-loaded with the resource and scope, then the security-relevant caveat. Every phrase carries information; nothing is padded.

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

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

With no input parameters and no output schema, the description usefully summarizes the return shape (brand, last four, expiry) and the masking constraint. An agent has enough to call and interpret it, though nothing is said about ordering, pagination, or empty-result behavior.

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 parameterless tool is 4. The schema is empty and consistent with the description.

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

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

The description states the resource (payment methods), its location/scope (saved to the Client Portal), and the returned fields (brand, last four digits, expiry). It is immediately clear what is being listed, though it does not explicitly differentiate itself from the neighboring billing tool (list_billing_items).

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

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

There is no statement of when to use this tool versus alternatives such as list_billing_items, nor any prerequisite or context cues. Usage can only be inferred from 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?

Goes well beyond the annotations: discloses that a real email is sent, that it is rate-limited per email address AND per IP, that a confirmation prompt/two-step confirmToken flow gates execution, and the non-obvious fact that success does not prove an account exists (enumeration resistance). These are exactly the behavioral traits an agent must know before invoking.

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?

Purpose is front-loaded in the first sentence, and each following sentence carries distinct operational information (rate limits, confirmation modes, enumeration caveat). Some sentences are dense, but nothing is padding.

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

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

For a mutating, rate-limited, open-world tool with no output schema, the description covers the safety profile, the confirmation mechanics, and the misleading-success caveat. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents email, practice, and confirmToken in detail. The description reinforces the confirmToken workflow but adds little syntax or semantics not already present in the schema; baseline 3 applies.

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

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

States a specific verb ('email a sign-in link') and resource ('Client Portal address') with a clear scope. It is immediately distinguishable from siblings like verify_sign_in_token or verify_sign_in_pin because it is the entry point that sends the link rather than validating a credential.

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

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

Explains the context ('the portal has no password — this is how you sign in') and details the two confirmation paths thoroughly, including the env-var controls. It does not, however, explicitly name when a sibling such as verify_sign_in_token would be the better next call, leaving that 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the three ways a practice can be determined (sign-in link, SIMPLEPRACTICE_PRACTICE, stored session) and the no-network-call guarantee. No output schema exists, so the description reasonably carries the return-content burden, though it doesn't say what is reported when no session exists.

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

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

Two tight sentences, front-loaded with the primary purpose and followed by the determination-source detail. Every clause adds information and nothing is redundant.

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

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

For a zero-parameter, read-only status tool with no output schema, the description covers what is reported and where the answer comes from. The only gap is the no-session/empty-state behavior, which an agent might want to know to avoid misreading a negative result as an error.

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

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

The tool takes zero parameters, so the baseline is 4. There are no parameter semantics for the description to clarify or obscure.

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 ('Report') and resource (Client Portal session status) and enumerates exactly what is reported: whether a session exists, which practice, and how that was determined. This is clearly distinguishable from siblings like sign_out, request_sign_in_link, and verify_sign_in_token.

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 establishes clear context for when to call it (checking session state before deciding whether to sign in or sign out) and adds the constraint that it reads local state only. It stops short of naming an explicit alternative or when-not-to-use condition.

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

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

Goes well beyond the annotations by disclosing the crucial caveat that the session is NOT revoked server-side, that no network call is made, that other browser/app/server copies are unaffected, and that re-signing-in reverses it. This resolves the semantic ambiguity around readOnlyHint=false/destructiveHint=false with real consequence detail.

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 action in the first clause, then spends the remaining sentences on precise scope limits (no revocation, no network call, not global, reversible). Every sentence carries non-redundant information; 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 parameters and no output schema, the description fully covers what an agent needs: what is affected, what is not, side-effect scope, and reversibility. Nothing important is omitted.

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

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

The tool takes zero parameters, so the schema carries no semantic burden and the description correctly does not invent any. Baseline of 4 applies; there is nothing parameter-related to clarify.

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 concrete verb and resource: 'Forget the Client Portal session stored on this machine, so this server stops using it.' This is a specific local-state action that is clearly distinct from the sibling sign-in/session tools (request_sign_in_link, session_status, verify_sign_in_*).

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 clear from the description: use it when you want this server to stop using a stored local session, and 'signing in again undoes it' implies the reverse path. It does not explicitly name an alternative sibling or state an exclusion, so it stops 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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description usefully adds 'Single-use,' which reinforces the non-idempotent nature of the PIN, but it says nothing about what a 'session' means, whether it mutates server state, or any expiry/auth constraints. No contradiction with the annotations.

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

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

Two short sentences with the action and scope front-loaded and the single-use constraint appended. Every clause earns its place; there is 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 no-output-schema tool, the description conveys both the input semantics (6-digit PIN, email) and the outcome (a session). What the returned session looks like and its lifetime are unstated, but the annotations carry the mutation/safety context, so the gap is minor.

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

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

Schema coverage is 50%: email is documented in the schema, while pin has only a regex pattern and no description. The description compensates minimally by restating '6-digit PIN', which aligns with the schema pattern but adds no new format or source information. Baseline 3 is appropriate given the schema does most of 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+resource (exchange a 6-digit PIN for a session) with a clear scope qualifier ('for practices that email a code instead of a link'). This cleanly distinguishes it from the sibling verify_sign_in_token, which handles link-based sign-in.

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 'for practices that email a code instead of a link' tells the agent the exact condition under which this tool applies rather than its siblings. It stops short of naming the alternatives (request_sign_in_link, verify_sign_in_token) or stating when not to use it, so it is clear context but not fully explicit routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description independently explains why by disclosing that tokens are single-use and expire in 24 hours, and that the server remembers the practice afterward. This adds real behavioral context (one-shot consumption, expiry, state persistence) beyond the structured hints, though it doesn't cover what a returned session contains.

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 with the purpose front-loaded and no filler; each sentence carries information (purpose, accepted forms, rationale, token lifetime). It stops just short of the tightest possible phrasing but is well-sized.

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 token-redeem tool with annotations covering the safety profile, the description covers the flow, accepted input, and token lifetime. It omits what the resulting session provides or how to use it afterward, but the session_status sibling and the lack of an output schema make that a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema's terse parameter note: it explains the consequence of passing the whole link (the address names the practice, so no configuration is needed). That rationale is genuinely useful selection guidance 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: 'Exchange an emailed sign-in link (or the token in it) for a Client Portal session.' An agent can immediately tell what this does. It does not, however, explicitly differentiate itself from the sibling simplepractice_verify_sign_in_pin, 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?

It gives clear in-parameter guidance ('Accepts the whole link or just the part after the #') and a recommendation ('Prefer passing the WHOLE link'), which implies usage. But it never states when to choose this tool over the sibling verify_sign_in_pin or request_sign_in_link, so alternative selection is left to inference.

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