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

The readOnlyHint annotation already signals a safe read operation. The description adds valuable behavioral context by explaining that a single portal login may cover multiple clients and that clients is always a list, which helps the agent anticipate the return shape. 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 two sentences with no fluff. It front-loads the core content (practice, client, clients list) and uses an illustrative example to clarify a non-obvious behavior. Every word earns its place.

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

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

For a zero-parameter tool with a readOnly annotation and no output schema, the description sufficiently explains the conceptual return (practice, signed-in client, all visible clients). It lacks explicit output format details, but given the simplicity and existing annotations, 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?

With zero parameters, the schema already fully covers parameter documentation (100% coverage). The description has no need to add parameter meaning, and adheres to the baseline of 4 for tools with no parameters.

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

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

The description clearly states the tool returns the practice, the signed-in client, and every client visible to the login, with the specific clarification that clients is always a list. This precise scope distinguishes it from sibling tools that focus on specific operations like session status or sign-in links.

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 explains what the tool returns and clarifies the multi-client nature, but it does not explicitly state when to use this tool versus alternatives. Since it's a general 'get account' tool, usage is implied, but no explicit exclusions or comparisons to siblings are given.

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

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

The readOnlyHint annotation already covers the safety profile. The description adds a lightweight 'cheaper' performance hint and indicates the aggregate nature of the response, but it does not disclose other behavioral details such as exact response shape or which categories are counted. With annotations present, this is adequate but not rich.

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

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

The description is two sentences with no wasted words. The primary purpose is front-loaded, and the second sentence adds a valuable usage cue without redundancy.

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

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

This is a low-complexity tool with one optional parameter and no output schema. The description states what the tool returns and why it is preferable to item-level billing calls. It is nearly complete, though the exact output structure is left unspecified in the absence of 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?

Schema description coverage is 100%, and the only parameter, 'view', is fully documented with enum values and explanations. The tool description adds no additional parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as returning 'Balance due and per-category counts for the Client Portal account,' which is a specific output and resource. It also distinguishes itself from item-level billing tools by positioning itself as a quick summary rather than 'paging the billing collections.'

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

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

The description gives context for when to use this tool: when you want to know whether anything is owed without paging through billing collections. However, it does not explicitly name the alternative sibling tool or state when not to use it, so the guidance is clear but not fully 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?

The annotations already declare readOnlyHint=true, so the description does not need to establish that this is a safe read. The description adds useful context about what the response contains: body or questions and existing answers. It does not describe further behavior like pagination or error cases, but for a simple get-by-id tool this is adequate.

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 a single, compact sentence that front-loads the core purpose ('One document request in full') and immediately clarifies what 'full' means by naming body/questions/answers. Every word earns its place; there is no redundancy 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?

For a simple read-only get-by-id tool, the description plus the fully documented input schema and readonly annotation give an agent enough to select and invoke it correctly. It does not describe the output shape fully, but that is not required given the straightforward resource and available schema information.

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 input schema already documents both parameters at 100% coverage, including the view enum and its compact/full effects. The description adds no parameter-specific meaning beyond the schema, so it meets the baseline but does not exceed it.

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 ('document request') and the scope ('one... in full'), which clearly implies fetching a single item rather than a list. It does not explicitly name a sibling to distinguish itself, but 'one' versus the sibling 'list_document_requests' makes the purpose reasonably clear.

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

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

The singular framing implies the tool is for retrieving one specific document request by id, rather than listing all requests. However, it does not explicitly say when to prefer this over list_document_requests or any other alternative, so usage guidance 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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses exactly what the tool does (one authenticated request), what it reports (credential source, acceptance, RTT, plain-English hint), and an important safety property (never returns the credential itself). This gives the agent a precise behavioral model.

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?

Every sentence earns its place: what it does, what it reports, when to call it, and its read-only safety guarantee. The description is dense but not bloated, and it leads with the core action before explaining outputs.

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 zero parameters, no output schema, and safety covered by annotations, the description still supplies the essential response semantics (what gets reported and how to interpret the hint). An agent has everything needed to invoke the tool and understand its result.

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 and 100% schema description coverage, so there is no parameter semantics burden. The baseline of 4 applies because no parameter explanation is needed; the description correctly focuses on behavior instead.

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 diagnostic action (resolves the credential, makes one authenticated request, reports results) and clearly sets it apart from sibling session, sign-in, and data tools. An agent can tell this is the reachability/credential healthcheck without opening schemas.

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

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

It gives an explicit trigger: 'Call this when a real tool fails and you want to know which hop broke.' This is clear context for use, though it does not explicitly name sibling alternatives or when-not scenarios.

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 provide readOnlyHint=true, so the safe read-only nature is established. The description adds useful context about the readAt field being null for unread announcements and scopes the data to practice-posted Client Portal announcements, but it does not disclose ordering, pagination behavior, or response shape beyond that.

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 only two short sentences with no filler. The core subject is front-loaded, and the readAt clarification earns its place by explaining a meaningful field semantic.

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 required parameters, the description plus the detailed view parameter schema is sufficient for an agent to call it correctly. The lack of an output schema is partially offset by the readAt detail and the schema's description of compact versus full response shapes.

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 50%, with the view parameter already well described and pageSize being self-explanatory through its name, default, and maximum. The tool description does not add parameter-level meaning, but the schema carries enough weight for these two simple optional parameters.

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

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

The description clearly identifies the resource as announcements posted by the practice to the Client Portal, which distinguishes it from sibling list tools like list_appointments or list_documents. It does not explicitly include a verb such as 'lists' or 'retrieves,' but the tool name and phrasing make the operation obvious.

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 gives no guidance about when to use this tool versus other listing tools, nor does it state any exclusions or prerequisites. The intended use is only implied by the resource name and the brief description.

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

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

The readOnlyHint annotation already communicates that this is a safe read operation. The description adds useful behavioral context around status filtering and pagination, but it does not disclose pageSize behavior, defaults, or response shape, leaving the behavioral picture incomplete.

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 short, front-loaded, and contains no filler. 'Pages by number' is concise but slightly cryptic, and the opening phrase is a fragment rather than a full purpose statement, preventing a top score.

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

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

This is adequate for a read-only list tool: it covers the resource, status semantics, and pagination, while schema defaults handle some missing detail. However, pageSize is unexplained and there is no output schema or description of what the returned appointments contain, so it is minimally viable rather than complete.

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

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

Schema description coverage is only 50%, so the description needs to compensate for undocumented parameters. It clarifies the status enum meanings and mentions pagination by number, but the pageSize parameter is left undocumented in both the schema and 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 clearly identifies the resource as Client Portal appointments and explains the key status distinction between scheduled and requested results. The verb is implied via the tool name and the word 'returns' rather than explicitly stated as 'list/get', so it stops just 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?

The description gives explicit, actionable guidance on when to use the 'scheduled' versus 'requested' status values, which is the main decision an agent faces. It does not discuss alternative sibling tools, but the resource scope is unambiguous enough for selection.

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?

Beyond the minimal isSearch/systemOnly annotations, the description discloses two non-obvious behaviors: empty results are meaningful rather than errors, and pagination uses a nextCursor that must be passed as 'before'. This is useful behavioral context that 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?

Three short sentences, each carrying essential information: what the tool returns, the empty-list caveat, and pagination mechanics. No filler or repetition.

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?

The description covers the core list behavior, empty results, and pagination intent, which is strong for a simple two-parameter tool. However, the cursor instruction cannot be satisfied with the given input schema, and because there is no output schema the description remains the only source for return expectations. That gap prevents it from being fully complete.

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

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

The prose restates the kind enum values and adds portal context, but the schema already supplies those enums with far better precision. More importantly, the pagination instruction references a 'before' parameter that is absent from the input schema, so an agent following the description cannot actually execute pagination. The view parameter is only documented by the schema, not enhanced by 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 clearly enumerates the resource scope: invoices, statements, superbills, receipts, or account history from the Client Portal. It is distinguishable from sibling list tools like appointments and documents, though it does not explicitly name the alternative or state the verb 'list'.

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 gives important operational context: an empty list is a legitimate answer because many practices bill outside the portal, and it explains cursor pagination. However, it does not state when to prefer this tool over alternatives or provide exclusions.

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

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

Annotations already declare readOnlyHint=true, so the bar is lower. The description adds valuable context about the nature of the resource (types of forms) and the practical meaning of outstandingOnly, going beyond the annotation. It does not disclose any undocumented mutations or side effects, but none exist given the read-only hint.

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

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

Two sentences, zero filler. The main purpose is front-loaded, and the outstandingOnly hint adds actionable value without redundancy. Every word earns its place.

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

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

No output schema exists, so the description should convey the return concept. It implies a list of requests by the verb 'list' and enumerates categories. Pagination is partially covered by the pageSize parameter in the schema. Combined with the readOnly annotation, the description is sufficient for an agent to call the tool 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 67%, with includeBody and outstandingOnly documented in the schema. The description adds a human-oriented rationale for outstandingOnly ('see just what still needs the client's attention'), which is more interpretable than the schema's 'not completed or locked.' It does not add new meaning for pageSize, but that parameter is intuitive and covered by its name and default.

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 clear verb+resource: lists document requests (paperwork the practice has sent). It enumerates concrete types (consents, questionnaires, etc.), which distinctively frames what this tool returns. The mention of outstandingOnly further clarifies the function, making it unmistakable what the tool does.

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 guidance is implied rather than explicit. The description says 'Use outstandingOnly to see just what still needs the client's attention,' which is a parameter-level hint, but it does not compare this tool to siblings like get_document_request or list_documents, nor state when to prefer one over the other. Context is present but no explicit exclusions or alternatives.

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

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

The readOnlyHint annotation already covers the safety profile. The description adds that the files are 'shared through the Client Portal', providing a bit of context. However, it does not disclose anything like pagination behavior, sorting, or empty results. With the annotation present, this is a minimal but acceptable addition.

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

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

One sentence, no wasted words. It is concise and to the point. However, it may be under-specified for a tool with a parameter, but conciseness itself is well executed.

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?

The description lacks essential context for a tool with no output schema. It does not explain the pageSize parameter, pagination, or any ordering. While it clarifies the return type (files shared via Client Portal), it is incomplete for an agent to call it correctly without further inference.

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 schema has zero description coverage, so the description should compensate. It does not mention the only parameter, pageSize, at all. The agent receives no guidance on how to use this parameter (e.g., default, max, or its effect on results). This is a clear gap.

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 (files/documents) and context (shared via Client Portal), which clearly indicates a read/list operation. It distinguishes from sibling tools like list_document_requests by specifying actual files rather than requests. The verb is implicit rather than explicit, but the tool name reinforces it.

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 gives no guidance on when to use this tool versus alternatives such as list_document_requests or get_document_request. It only defines what it returns, without clarifying selection criteria or context.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral detail beyond annotations: it specifies that full card numbers are NOT returned, which is a critical privacy constraint. It also enumerates the exact fields returned (brand, last four digits, expiry). This is strong supplementary disclosure for a simple read operation.

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

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

The description is a single sentence that front-loads the core purpose and immediately states the key constraint (no full card numbers). Every word earns its place, and there is no fluff or redundancy.

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

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

For a zero-parameter, read-only list tool with no output schema, the description is largely complete. It tells the agent what data to expect and what not to expect. It does not discuss response format or pagination, but these are minor gaps for such a simple tool, and the annotation covers the safety profile.

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

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

There are no parameters, and schema description coverage is 100% (vacuous). The baseline for zero-parameter tools is 4, and the description does not need to explain parameters. It adds no parameter-specific information, which is appropriate here.

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 clearly states the resource (payment methods saved to the Client Portal) and the specific data returned (brand, last four digits, expiry). It is distinct from all sibling tools, which deal with sessions, appointments, billing, documents, etc. The purpose 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?

The description provides no guidance on when to use this tool versus alternatives. It does not mention any alternative tools or scenarios where it should or should not be used. While the tool is obviously for listing saved payment methods, the absence of explicit usage context leaves the agent to infer intent.

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

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

With only readOnlyHint=false and idempotentHint=false, the description carries full behavioral burden and exceeds it. It discloses that a real email is sent, that rate limits apply per email and per IP, that confirm:true is required, and that the API deliberately gives identical responses for unknown addresses.

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 tightly written sentences deliver the action, the reason this tool exists, the side effects and preconditions, and a critical caveat about false confidence. Nothing is wasted and the most important operational facts are 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?

The description covers the action, real-world side effect, rate limiting, confirmation requirement, the practice parameter's optionality, and the ambiguous success signal. With no output schema, this is sufficient context for an agent to call the tool safely and interpret results appropriately.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds meaningful context beyond the schema: confirm exists because the action sends real email and is rate-limited, and practice is only needed when the server has not yet learned the practice from a prior sign-in.

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 precise action — 'Ask SimplePractice to email a sign-in link to a Client Portal address' — and immediately distinguishes the tool's role: it sends the email that starts the sign-in process. It is clearly differentiated from sibling verification tools like verify_sign_in_token and verify_sign_in_pin.

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 clearly frames when to use the tool: the portal has no password, so this email link is the sign-in method. It also warns about rate limits and the need for confirmation, but it does not explicitly name alternatives such as verifying a token or PIN after the link is used.

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

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

Annotations declare readOnlyHint=true, and the description adds the valuable detail that it makes no network call, which is beyond the annotation. It also explains what information is reported (session, practice, determination method), giving a complete picture of behavior without over explaining.

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 a single sentence, tightly packed with essential information: what it reports, the three ways practice is determined, and the local/no-network nature. Every word earns its place, and the key action 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 stateless diagnostic tool with no parameters and no output schema, the description fully covers what an agent needs to know: the scope of the check, the report content, and the absence of side effects. The sibling list underscores that this is a lightweight status check, and the description matches.

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 the description need not document them. The schema coverage is 100% vacuously, and the description adds no parameter-specific information, which is appropriate. The baseline for zero parameters is 4.

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

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

The description states exactly what the tool does: reports session existence, practice, and determination method. It uses a specific verb ('Report') and a clear resource (Client Portal session), and it distinguishes itself from siblings by focusing on status rather than actions like sign-in or sign-out.

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 provides clear context on when this tool is appropriate—checking session state—and notes it reads only local state, implying it's a safe, fast diagnostic. It does not explicitly mention alternative tools or exclusions, but the purpose is self-evident given the sibling list.

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

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

The annotations already state readOnlyHint=false and idempotentHint=true, indicating a mutating but idempotent operation. The description adds that the action affects local state only, which is helpful context beyond the annotations. However, it does not disclose potential side effects (e.g., whether server-side session is invalidated) or behavior when no session exists. It adds some value without contradicting 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 a single concise sentence with no redundant words. It front-loads the essential action and includes the meaningful qualifier 'from local state.' Every word contributes to understanding the tool's behavior, and it is appropriately sized for a simple operation.

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?

Given the tool's simplicity (no parameters, no output schema, straightforward action), the description is largely sufficient. It clearly states what the tool does and its scope. However, it could optionally mention the effect on the user's authentication state (e.g., requiring re-authentication), but that is not essential for correct invocation. The description covers the core functional requirements.

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?

This tool has zero parameters, and schema description coverage is 100% (vacuously). Per the rubric, a 0-parameter tool receives a baseline of 4. The description does not need to elaborate on parameters since none exist. It effectively communicates that no arguments are required, which is sufficient.

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 clearly states the action: 'Discard the stored Client Portal session from local state.' It specifies the verb (discard), the resource (session), and the scope (local state). This distinguishes it from sibling tools like simplepractice_session_status (which checks status) and simplepractice_request_sign_in_link (which initiates sign-in). The purpose 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?

The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention that this should be used when a user explicitly logs out, nor does it contrast with other session-related tools. The tool's purpose is implied by its name and description, but no alternatives or exclusions are mentioned, leaving the agent to infer usage context.

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

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

Annotations only indicate mutating (readOnlyHint=false) and non-idempotent (idempotentHint=false). The description adds meaningful behavioral detail: it is a single-use exchange that creates a session. This goes beyond annotations by explaining the one-time nature and the session outcome, which is valuable for an agent calling this tool.

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

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

The description is a single, concise sentence that front-loads the core action ('Exchange a 6-digit Client Portal sign-in PIN for a session') and appends the usage context and single-use caveat. There is no fluff or redundant wording.

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 two-parameter, no-output-schema tool, the description adequately conveys what it does, when to use it, and key behavioral constraints. It does not specify error handling or the exact session object returned, but given the simplicity and annotations, these are minor omissions.

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

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

Schema coverage is 50%: only email has a schema description ('The address the PIN was sent to.'). The pin parameter only has a pattern, but the tool description clarifies pin as a '6-digit Client Portal sign-in PIN', adding meaning beyond the schema. Thus both parameters are effectively covered via schema and description, exceeding the baseline.

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

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

The description states a specific verb ('Exchange'), resource ('6-digit Client Portal sign-in PIN'), and outcome ('for a session'), and distinguishes itself by noting 'for practices that email a code instead of a link', which clearly differentiates it from the sibling verify_sign_in_token that handles link-based authentication.

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 gives the usage context: 'for practices that email a code instead of a link' and notes 'Single-use'. This tells the agent when to use this tool (email-code-based sign-in) and implies not to use it for link-based flows. However, it does not explicitly name the alternative tool (e.g., verify_sign_in_token), so the guidance is clear but not fully 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?

The annotations only say readOnly=false and idempotent=false. The description adds valuable non-obvious behavior: tokens are single-use, last 24 hours, and the server remembers the practice from the full link. This is precisely the kind of context an agent needs before calling a session-exchange tool.

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

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

Three focused sentences: core action first, then input forms, then preference with rationale. Every sentence earns its place, with no filler or repetition.

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 auth exchange tool with no output schema, the description covers input format, preference, token lifecycle, and expected outcome—'Client Portal session.' Nothing needed to correctly select and invoke the tool 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?

The schema only describes the parameter as the sign-in link or token after '#'. The description enriches this substantially by explaining how to format the input, why the whole link is preferred, and what happens when each form is used.

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: 'Exchange an emailed sign-in link ... for a Client Portal session.' It also clarifies the acceptable input forms, making it easy to distinguish from sibling tools like simplepractice_verify_sign_in_pin.

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 context: this tool is for emailed sign-in links or tokens, and it explicitly advises preferring the whole link because it avoids needing a configured practice. It does not explicitly name alternatives like verify_sign_in_pin, but the intended use case is unambiguous.

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