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 meaningful context by explaining that clients is always a list because one portal login may cover multiple clients (e.g., a parent with two children). This clarifies an expected output shape without contradicting the annotation.

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

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

Two sentences with no filler. The first sentence immediately states what is returned, and the second explains the key nuance about the clients list. The information is front-loaded and every clause 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, read-only tool with no output schema, the description covers the essential aspects: the resource scope and the critical behavioral quirk (clients always being a list). An agent can correctly anticipate the tool's result shape and behavior without further documentation.

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 nothing for the description to add beyond the schema. The schema coverage is 100% (vacuously), and the baseline for no-parameter tools is 4. The description appropriately focuses on output semantics 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 clearly states the resource being retrieved: the practice, the signed-in client, and all visible clients. It uses specific nouns and implies a retrieval action, making the tool's purpose obvious without referencing the tool name. It is distinct from sibling tools which focus on specific entities like appointments or 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?

The description explains what the tool returns but does not explicitly state when to use it versus the sibling list tools. There is no mention of alternatives or exclusions. The context about multi-client access is helpful, but the tool's usage window is left to the agent's 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?

The readOnlyHint annotation already communicates that this is a safe read operation. The description adds a cost/efficiency signal ('Cheaper than paging...') but does not elaborate on response behavior, rate limits, or other side-effect-relevant details. 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?

Two short sentences, front-loaded with the core purpose and followed by a useful efficiency note. Every word earns its place; no filler 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 simple, read-only tool with one optional, well-documented parameter, the description covers the high-level return content and the practical reason to use it. It could be more specific about what 'per-category' means or the response shape, but the annotation and schema already reduce the burden.

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

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

Schema description coverage is 100% and the single 'view' parameter is fully documented with enum meanings. The tool description adds no parameter-specific meaning beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool returns balance due and per-category counts for the Client Portal account, and it hints at a distinction from detailed billing collection paging. It lacks an explicit action verb and does not name a sibling tool, so it falls 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 phrase 'Cheaper than paging the billing collections just to find out whether anything is there' gives clear contextual guidance for when to use this overview tool rather than pulling detailed billing items. It does not name the sibling explicitly or provide exclusions, but the intended use case is reasonably clear.

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 signals this is a safe read operation, and the description adds response-content context without claiming any mutation. It does not disclose authentication requirements, and 'in full' sits somewhat loosely against the compact/full view distinction, though the schema itself clarifies 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?

A single front-loaded sentence with no filler: it names the resource, its scope, and the key response contents. 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 simple one-resource read tool with two well-documented parameters and a readOnly annotation, the description plus schema is enough to invoke the tool correctly. Since there is no output schema, the description usefully orients the agent to what the response will contain.

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 thoroughly documented, including the compact/full response-shape behavior. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

The description clearly identifies the resource as a single document request and indicates the scope ('One document request') and the payload contents (body/questions/answers). It is not a tautology, but it never states an explicit retrieval verb or names a sibling like list_document_requests to differentiate against.

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

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

The phrase 'One document request' implies this is the tool for a single request rather than a list, but the description gives no explicit guidance on when to use it versus list_document_requests or any exclusions. Usage context is only implied, not 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 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?

The readOnlyHint annotation already covers safety, and the description adds a useful data-model detail: readAt is null on unread announcements. However, it does not disclose ordering, pagination, or other behavioral traits beyond that field note.

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 no filler. The identifying resource information comes first, and the readAt clarification earns its place by adding useful field semantics.

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-required-parameter read-only list tool, the description plus schema is sufficient for an agent to invoke it correctly. The readAt note helps interpret results, though a bit more output-shape detail would have made it 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 schema fully documents the view parameter, and pageSize is largely self-explanatory from its name, default, and maximum. The description itself adds no parameter-level meaning, but the schema provides enough for correct invocation.

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 identifies the resource as announcements posted by the practice to the Client Portal, which is specific enough to tell it apart from sibling tools like list_documents and list_appointments. It does not explicitly state the verb 'list', but the tool name supplies that.

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?

No guidance is given about when to use this tool versus alternatives, nor are there any exclusions or preconditions. The intended use case is only implied by the resource name and the portal 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 include readOnlyHint=true, and the description aligns with this by describing a read-only operation. The description adds value beyond annotations by explaining status semantics and pagination behavior. It does not disclose any side effects, which is appropriate given the readOnly hint, but it could have mentioned response shape or pagination details more thoroughly.

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 concise, two sentences, and directly states the core function and key filtering. It front-loads the main purpose and then explains status values. There is no fluff, and it is easy to scan. It could be slightly more explicit about listing, but overall it is well-structured.

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 list tool with a readOnly annotation, the description covers status and pagination. It does not describe the output structure, but there is no output schema to rely on. It also does not mention default behavior for pageSize, but that is in the schema. The description is adequate but not exhaustive; an agent might need to infer some details about the response format.

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 descriptions for 'view' and 'status', covering 50% of parameters. The description adds meaning for 'status' by explaining the two values, and for 'page' via 'Pages by number'. However, it does not address 'pageSize', and the coverage is only partial. The description partially compensates for the schema gaps but not fully.

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 indicates the tool returns appointments from the Client Portal and clarifies the meaning of the status filter. However, it lacks an explicit verb like 'list' or 'retrieve', relying on the tool name for that. It is distinct from siblings as no other tool lists appointments, so it is adequately differentiated.

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 the two status values and pagination, which informs usage. However, it does not explicitly state when to use this tool over alternatives, nor does it mention any exclusions. Since no sibling provides the same functionality, the lack of explicit guidance is not critical but still a gap.

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 call read-only; the description adds behavioral facts that annotations cannot, including that an empty list is a legitimate answer and that pagination uses a cursor that must be fed back as before. It does not mention rate limits or output format, but the main call semantics are disclosed.

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-load the resource scope, then add the empty-list caveat and pagination rule. No content is repeated from the schema or annotations.

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

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

For an optional-parameter read-only list tool, it covers the unusual behaviors that would otherwise trip up an agent: empty list semantics and cursor pagination. It does not describe the actual shape of returned records, but since there is no output schema and the view parameter describes shapes, a fuller description would add bulk without much call-time value.

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 maps the kind enum values and explains the before cursor beyond the schema's bare 'Cursor for the next page'. It leaves pageSize to schema defaults and view to the schema's long description, which is reasonable given their self-describing names.

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 enumerates the exact resource types returned (invoices, statements, superbills, receipts, account history) and scopes them to the Client Portal, clearly distinguishing them from sibling list tools. It lacks an explicit verb, but 'list' in the tool name plus the object list 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?

It provides clear context: this is the tool for Client Portal billing documents, and an empty result is meaningful rather than an error, which is important for deciding whether a practice uses the portal. It does not name alternatives such as get_billing_overview or list_payment_methods, so it stops short of explicit exclusionary 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 declare readOnlyHint=true, so the description doesn't need to restate safety. The description adds context about the content (consents, questionnaires, forms, estimates, shared files) and the outstandingOnly filter's meaning. It doesn't disclose pagination or default behavior beyond what the schema already provides, but the read-only nature is covered by annotations.

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

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

Two sentences with no waste. The first sentence defines the resource and scope, the second explains the key filter. Front-loaded with the most important information.

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

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

For a read-only list tool with 3 optional parameters and no output schema, the description is sufficient. It explains what the tool returns and the key filtering option. It doesn't mention pagination limits or the includeBody tradeoff, but the schema already documents those defaults. The sibling list_documents is not explicitly contrasted, but the resource type is clear enough.

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% (2 of 3 params have descriptions). The description adds meaning to outstandingOnly ('just what still needs the client's attention'), which complements the schema's 'not completed or locked'. It doesn't add detail for pageSize or includeBody beyond the schema, but the schema already covers those adequately.

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 ('Paperwork the practice has sent') and the action ('list document requests'), enumerating the types of paperwork included. It also distinguishes itself from the sibling simplepractice_list_documents by focusing on requests sent by the practice, and mentions the outstandingOnly filter for scoping.

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 a clear context for when to use this tool: to see paperwork the practice has sent, and specifically mentions using outstandingOnly to see what still needs the client's attention. It doesn't explicitly name alternatives or exclusions, but the sibling list_documents is implicitly differentiated by the focus on requests vs. documents.

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 useful scope qualifier ('files the practice has shared') but does not disclose pagination behavior, ordering, or return shape. This is acceptable given the annotation, 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 a single short sentence with no filler. Its scope is front-loaded and every word contributes meaning, even though the sentence is grammatically a noun phrase rather than a full clause.

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 one optional parameter, this is minimally adequate. However, with no output schema, no discussion of pageSize, and no explicit disambiguation from document-request siblings, an agent still has to make assumptions about the return shape and exact use case.

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 description contains no parameter information, and schema_description_coverage is 0%. The pageSize parameter's default and maximum constraints are visible in the schema, but the description does nothing to explain or add meaning to 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 identifies the resource as files the practice has shared through the Client Portal, which distinguishes it from sibling tools like list_document_requests. However, it is a noun phrase rather than an explicit verb+resource statement and does not name the sibling it is not.

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 implies a read-only listing use case from the resource wording and the readOnlyHint, but it gives no explicit when-to-use guidance, no exclusions, and no named alternatives. An agent must infer when to pick this over list_document_requests or other document-related tools.

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 description adds value by specifying the exact data returned (brand, last four, expiry) and explicitly noting that full card numbers are not included. This security context goes beyond the annotation. No other behavioral traits are disclosed, but for a simple list operation this is sufficient.

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 with zero waste. The core purpose and returned fields are front-loaded, and the exclusion of full card numbers is stated clearly. Efficient and well-structured.

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 parameterless, read-only list operation, the description fully covers what an agent needs: what is returned (brand, last four, expiry) and what is not (full numbers). Since no output schema exists, this explicit enumeration of returned fields is essential. Complete for the tool's simplicity.

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, so the description need not add parameter semantics. The schema coverage is 100% by virtue of having no properties. The baseline for zero parameters is 4, and the description adds nothing beyond that, which 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 operation: listing payment methods saved to the Client Portal. It specifies the returned fields (brand, last four digits, expiry) and explicitly excludes full card numbers. This distinguishes it from sibling list tools by subject matter and scope.

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

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

The description implies when to use the tool: when a list of stored payment methods is needed. It does not explicitly mention alternatives or exclusions, but the subject is distinct enough that no confusion with siblings arises. Context is clear, though it stops short of explicit when-not 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 are minimal (only readOnlyHint=false, idempotentHint=false), so the description carries the full burden — and it delivers richly. It discloses a real side effect ('Sends a real email'), rate limits per email and per IP, the confirm:true requirement, and the critical caveat that success does not prove an account exists because the API answers identically for unknown addresses. 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?

Four sentences, zero waste, and the core purpose is front-loaded in the first sentence. Each subsequent sentence earns its place: the passwordless context, the side-effect/rate-limit/confirm requirement, and the unknown-address caveat. Highly efficient.

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 moderate-complexity tool (3 params, 1 required) with no output schema, the description covers the essential operational facts: real side effect, rate limits, confirm gate, and the anti-correlation between success and account existence. It does not describe the preview returned when confirm is false, but the schema's confirm description covers that path. Reasonably 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 coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining WHY confirm must be true (rate-limiting rationale) and by clarifying the practice parameter's optionality ('Only needed when this server does not know the practice yet'), neither of which appears in the schema. That lifts it above 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 ('Ask... to email') and resource ('a sign-in link to a Client Portal address'), and distinguishes itself from the verify siblings (verify_sign_in_token, verify_sign_in_pin) by framing this as the request step: 'this is how you sign in.' Purpose is unambiguous and not a tautology.

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 clear context ('The portal has no password — this is how you sign in'), which tells an agent when the tool is relevant. However, it never explicitly names or routes to the sibling verify tools (verify_sign_in_token, verify_sign_in_pin), so an agent must infer the full sign-in flow rather than being told when NOT to use this tool.

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, conveying safety. The description adds meaningful context beyond that by stating it 'Reads local state only — makes no network call,' which is a significant behavioral guarantee for an agent. It also explains how the practice value is resolved (sign-in link, SIMPLEPRACTICE_PRACTICE, or stored session), adding useful logic transparency.

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

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

A single, information-dense sentence front-loads the core action ('Report whether...') and packs additional specifics about practice and provenance without verbose framing. Every clause adds value, and there is no redundant text 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?

The description covers the essential return concepts (existence of session, practice identifier, determination mechanism) and notes the local-only read behavior, which is sufficient for a no-parameter, read-only tool. While it omits exact data types or response shape, the absence of an output schema is partially mitigated by this high-level enumeration; a more detailed field breakdown would be nice but is not critical.

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 has zero parameters and 100% schema description coverage, so there is nothing for the description to clarify about parameters. As a no-parameter tool, the baseline of 4 applies; the description correctly focuses on output semantics rather than inputs.

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

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

The description leads with a specific verb ('Report') and a precise resource: whether the server holds a Client Portal session, for which practice, and how the practice was determined. This clearly distinguishes it from siblings like simplepractice_sign_out (action) or simplepractice_list_documents (data listing), and a reader immediately knows what this 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?

The description implies its use case by stating it reports session state and reads local state, so an agent can infer when to call it (e.g., before acting on a practice session). However, it gives no explicit guidance on when to prefer this over related session tools like simplepractice_verify_sign_in_token or when not to use it, nor does it name 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?

Annotations already establish non-read-only and idempotent behavior. The description adds a meaningful behavioral detail by specifying that the session is discarded 'from local state,' clarifying that this is a local-state mutation rather than a server-side invalidation. It does not contradict 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?

The description is a single, front-loaded sentence with no filler. Every term ('Discard', 'stored', 'Client Portal session', 'local state') adds necessary meaning.

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, no-output-schema tool, the description is complete: it states the action, the object, and the scope. The idempotency and non-read-only annotations cover the remaining safety profile, so no critical information 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 tool has zero parameters and the input schema is empty, so there are no parameter semantics for the description to document. The baseline of 4 applies because the description correctly focuses on the operation rather than parameter details.

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 action ('Discard') and the exact resource ('the stored Client Portal session from local state'). It clearly communicates a sign-out operation and is easily distinguished from sibling tools like simplepractice_session_status or simplepractice_request_sign_in_link.

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 intended usage is implied: use this when a stored Client Portal session should be discarded. However, the description does not explicitly state when to prefer this over alternatives, whether a session must already exist, or what happens if no session is stored.

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 indicate readOnlyHint=false and idempotentHint=false, and the description reinforces this with 'Exchange' (mutating) and 'Single-use' (non-idempotent). It adds the single-use constraint, which is important for understanding that the PIN cannot be reused. It does not contradict annotations. Could add what happens on failure, but not required for a clear definition.

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 short sentences with zero fluff. The core action is front-loaded, and the single-use behavior is stated separately. It is concise and well-structured.

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 has only 2 simple parameters, no output schema, and annotations that cover mutation and idempotency, the description provides enough context for an agent to call it correctly. It states what it does, when to use it, and the single-use nature. It lacks explicit error handling details, but these are not essential for a straightforward exchange tool. Overall, it is complete for its complexity.

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

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

Schema coverage is 50%: email has a description, pin does not. The description clarifies that pin is a '6-digit Client Portal sign-in PIN', which adds context beyond the raw pattern. However, it does not fully compensate for the missing schema description of pin, though the pattern and the tool name make it obvious. Email's description already matches the schema. Overall, the description adds marginal value but is not insufficient.

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 (exchange), the resource (a 6-digit Client Portal sign-in PIN), and the outcome (for a session). It also differentiates from the sibling tool `simplepractice_verify_sign_in_token` by specifying the context (practices that email a code instead of a link). The purpose is unambiguous and distinct.

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 a clear condition for use ('for practices that email a code instead of a link'), which implicitly distinguishes it from link-based sign-in alternatives. It does not explicitly name the alternative tool, but the context makes the intended usage clear. The single-use note also guides behavior. Slight gap: no explicit exclusion or alternative naming.

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

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

Annotations only declare readOnlyHint=false and idempotentHint=false; the description adds meaningful behavior: tokens are single-use, last 24 hours, and the server persists the practice association from the link. These details go beyond the annotations and give an agent useful expectations about side effects and token consumption.

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

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

Three sentences with no filler: purpose first, then accepted formats, then a clear preference with rationale, and finally token lifecycle. Every sentence earns its place and the most decision-relevant detail (whole link preference) 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 single-parameter tool with no output schema, the description covers the required input format, the optimal input choice, and token behavior. It does not describe the return value or what the resulting portal session looks like, but that is a minor gap given the simplicity and the guidance already provided.

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 the parameter. The description adds value by explaining why the whole link is preferred (it identifies the practice and is remembered afterward), which is actionable semantic guidance beyond the schema's plain format 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 a specific action ("Exchange"), resource ("emailed sign-in link or the token in it"), and result ("Client Portal session"). It is clear about what the tool does, and the focus on the emailed link/token distinguishes it from the sibling PIN-based tool, 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?

The description implies when to use this tool (when you have an emailed sign-in link or token) but does not explicitly say when not to use it or name alternatives like simplepractice_verify_sign_in_pin. It does provide practical guidance on preferring the whole link, which helps invocation but not tool selection.

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