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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false) and openness, but the description adds genuinely new behavior: the return shape changes with the environment — a path on a local install, base64 bytes inline on a hosted runner. That is exactly the kind of context annotations cannot convey. It stops short of noting permissions or document-size/rate limits.

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

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

The core action is front-loaded in the first clause and the ID source follows immediately; nothing is redundant. The nested parenthetical and dual-return clause make the single sentence dense, but every piece carries information.

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

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

With no output schema, the description takes on the burden of describing return values and does so precisely (path on local install, base64 inline on hosted runner). Combined with the sibling pointer and full schema coverage on both parameters, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented in structured form, including dest's confinement to THERAPYPORTAL_OUTPUT_DIR. The description only reinforces the portal_document_id provenance and says nothing about dest, so it adds little beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Download a TherapyPortal document as a file') and enumerates the two document classes it covers (client-completed forms rendered to PDF, practice-uploaded files). It also names the sibling that supplies the identifier (therapyportal_list_documents), so an agent can separate it from therapyportal_download_receipt without opening either schema.

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

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

Explicitly directs the agent to get portal_document_id from therapyportal_list_documents, which is the key prerequisite for calling it. It does not state exclusions (e.g., 'use download_receipt for payment receipts'), so routing is clear but not fully disambiguated.

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

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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false), but the description adds genuinely non-obvious behavior: the return shape varies by transport—a file path on a local install versus base64 bytes inline on a hosted runner. That is the kind of gotcha an agent must know before parsing output. It doesn't address overwrite behavior for an existing file at dest or failure modes, so not a 5.

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

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

Two sentences, zero filler: the action and identifier source come first, then the transport-dependent return behavior. Every clause carries information an agent needs.

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

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

With no output schema, the description correctly assumes the burden of explaining return values—path vs. inline base64—which it does. Both parameters are covered by a fully described schema, and the sourcing requirement is stated, so nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%; both payment_id and the dest folder constraint (must live inside THERAPYPORTAL_OUTPUT_DIR or ~/Downloads / ~/Documents) are fully documented in the schema. The description adds no format or constraint detail beyond what the schema already states, so baseline 3 applies.

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

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

States a specific verb and resource ("Download a therapy payment receipt as a PDF") plus the identifier source, and names the sibling tool therapyportal_list_receipts, which cleanly separates it from therapyportal_download_document and therapyportal_list_receipts.

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

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

Gives clear upstream context ("by payment_id from therapyportal_list_receipts") and a motivating use case (insurance / HSA-FSA submission), which tells an agent exactly when this tool is the right call. It stops short of explicit exclusions—e.g., it doesn't say to use therapyportal_download_document for non-receipt documents—so a 4 rather than 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine behavioral detail about what is counted (awaiting completion vs. awaiting practice approval), which is more than the annotations convey. It says nothing about freshness/staleness of counts or how clients with zero documents appear.

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 that front-load the per-client aggregation and then the category split. Dense but efficient; the parenthetical-use sentence earns its place by conveying intent.

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 must imply the return shape — and it does, indicating per-client records with three breakdown categories. It stops short of describing the actual fields (client id/name, per-category numbers) or ordering, which would fully close the gap.

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

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

Only one optional parameter, and the schema documents the compact/full/raw enum at 100% coverage with per-value explanations. The description contributes nothing about the view parameter, 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?

States a specific resource (TherapyPortal document counts) and the exact bucketing: pending completion, completed-awaiting-approval, split into clinical/administrative/billing. This is clearly an aggregation, distinguishable in kind from list_documents or list_forms, though no sibling is named 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 closing phrase "a quick 'do I owe the therapist any forms?' check" implies the intended scenario, which is useful context. But it never says when to prefer this over therapyportal_list_documents or therapyportal_list_forms, nor any exclusions or prerequisites.

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

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

Goes beyond the readOnlyHint annotation by disclosing two behaviors annotations can't express: it does not mark the conversation read, and the returned content is third-party authored and must be treated as untrusted data rather than instructions. That injection-resistance warning is exactly the security context an agent needs for a message-reading 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 short sentences: operation first, then side-effect clarification, then the trust/safety caveat. Every sentence carries distinct, non-redundant information with nothing repeated from the schema.

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

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

For a single-parameter read tool with no output schema, the description covers what is returned (message text), its trust status, and the absence of a read-marking side effect. Nothing needed to invoke or interpret the result safely is missing.

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

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

Schema coverage is 100% and there is a single parameter, so the schema already carries the type constraints. The description still adds value by specifying provenance — the thread id must originate from therapyportal_list_message_threads — which tells the agent how to obtain a valid value.

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

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

Specific verb+resource: read the messages in one named secure-message conversation. It also identifies the source of the identifier (therapyportal_list_message_threads) and the domain (TherapyPortal), which distinguishes it from siblings like therapyportal_list_message_threads and therapyportal_download_document.

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

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

Explicitly states the prerequisite chain — the thread_id must come from therapyportal_list_message_threads — and clarifies the read-only-ness ('does not mark the conversation read'), which steers agents away from expecting a read-receipt side effect. No explicit exclusions or when-not guidance, but the selection context is 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?

Annotations cover safety (readOnly/openWorld/idempotent), and the description adds substantial context they don't: no auth required on the bridge path, the credential is resolved the same way real tools do it, the credential is never returned, and the error taxonomy is spelled out ('bridge never came up' vs 'extension not connected' vs 'browser can't serve a capability' vs 'upstream-side problem'). That is exactly the failure-mode disclosure a diagnostic tool needs.

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 two-path structure with leading labels is well front-loaded, but the literal placeholder 'www.therapyportal.com/p/sunrise-family-medicine' is repeated eight times and dominates the prose, bloating a short description considerably. The information is all relevant; the packaging wastes attention.

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

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

With no output schema, the description carries the burden of describing returns, and it does: bridge role/port/version/link state/elapsed time/hint, and for the credential path the credential source, acceptance, round-trip time, and hint. Both transport paths are covered, and the read-only, no-auth, no-credential-leak guarantees are all stated.

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

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

The tool takes no parameters, so there is nothing to disambiguate; the description correctly presents no parameter semantics and instead clarifies that the server picks the transport path automatically ('for whichever path this server is actually using'). Baseline 4 for a zero-parameter tool.

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

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

The first sentence states a specific verb and outcome — 'Reports which hop is broken when a real tool fails' — and the two labeled subsections ('Relaying through your signed-in browser tab' / 'Signing in server-side with configured credentials') make it unambiguous that this is a diagnostic/healthcheck tool rather than a data tool. No sibling does anything similar, so the agent can distinguish it immediately.

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?

'when a real tool fails' gives an explicit trigger condition, and the framing implies it is not a routine data-fetch call. It does not explicitly say when NOT to use it (e.g. don't call it preemptively on every request) or name a sibling to prefer for actual data retrieval, so it falls just short of the top score.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond them: the data is forward-looking only, and the response also carries pending appointment requests and the practice phone number. It does not mention auth or rate limits, keeping it short of a 5.

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

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

Two sentences, no padding, with the substantive payload and the future-only constraint front-loaded. Every clause earns its place by naming either a returned field or a scope limit.

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

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

For a two-parameter read tool with no output schema, the description is complete: it tells the agent what will come back, what extra non-appointment data is included, and the one hard limitation. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the enum for `view` and the 1–200 range for `limit` are fully documented in the schema. The description adds no syntax, ordering or defaulting detail beyond 'soonest first' implied by the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('List upcoming therapy appointments / sessions from TherapyPortal') and enumerates the returned fields: date/time, clinician, modality/location, and client. The scope statement 'future appointments only' separates it cleanly from the other sibling list_* tools, which cover receipts, clients, documents, forms and threads.

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 boundary condition — future appointments only, no past-visit history — which tells the agent when this tool will not answer a question. It does not explicitly name an alternative for past visits, but no sibling provides that either, so the gap is minimal.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds meaningful context beyond them by stating 'Changes nothing — this server cannot make a payment,' which preempts an agent from attempting a payment action. It does not cover result volume or pagination, keeping it short of a 5.

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

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

Two short sentences, zero filler, and the core scope is front-loaded before the negative capability statement.

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 listing tool with no output schema, the description tells the agent what comes back (per-client balance and autopay flag) and confirms no side effects. It omits anything about result size or whether all clients are always returned, a minor gap given 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?

Schema description coverage is 100% and the single 'view' enum is fully documented in the schema itself, so the schema carries the burden. The description adds nothing about the view parameter – baseline 3 applies.

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

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

States a specific verb ('Show what is owed') and resource ('the balance due for each client, and whether autopay is on'), which is enough to distinguish it from siblings like list_receipts and list_clients without opening any schema.

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

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

Usage is implied by the scope statement (balances owed, autopay status) and the note that it cannot make a payment, but it never names an alternative such as list_receipts for payment history or list_clients for roster data, so the agent must infer the boundary.

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, openWorldHint=true, and destructiveHint=false. The description adds useful disclosure about the response contents, saying it returns names and date of birth only and never contact details or identifiers.

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 front-loaded, starting with the primary purpose before adding the parent/child clarification and the PatientId relevance. Every clause adds useful information without 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?

Given the low complexity, annotations, and complete schema coverage for the single parameter, the description provides enough context. It explains the returned fields and the key identifier an agent needs for sibling tools, with no output schema required.

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 only parameter is view, and the schema description coverage is 100% with a detailed enum explanation. The description does not mention view, but the schema fully documents it, 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 states a specific verb and resource: "List the clients (patients) linked to this TherapyPortal login." It clarifies the parent/child relationship and explains that the returned PatientId is used by the message and document tools, which distinguishes it from the sibling list/download/get tools.

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 for using this tool: to retrieve clients and their PatientId for downstream message and document tools. It does not explicitly state when not to use it or name a direct alternative, but the usage context is 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?

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds genuine beyond-schema context: what fields come back per request and document, and a prompt-injection warning that returned text is third-party and must be treated as data. It omits pagination/result-size behavior, which matters for a listing tool against an open-world portal.

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, no redundancy: the first front-loads what is listed and what is returned, the second delivers the security caveat. 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?

With no output schema, the description does the necessary work of describing return contents (status, date, instructions, portal_document_id) and the untrusted-content caveat, which is sufficient for correct invocation. Minor gap: no indication of ordering, completeness, or pagination for the listing.

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 both params (view, status) have enums plus inline explanations, so the schema carries the full load. The description's mention of 'status' refers to returned request status rather than the filter parameter, and it says nothing about the view modes, so it adds no parameter meaning beyond the schema. Baseline 3 applies.

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

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

A specific verb (List) plus a well-enumerated resource (intake and consent forms, questionnaires, files sent for review) with a clear scope qualifier ('paperwork the practice sent through TherapyPortal'). It also states what each returned record carries, which makes it distinguishable from siblings such as therapyportal_list_forms and therapyportal_list_receipts without opening any schema.

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

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

It routes the agent forward by naming therapyportal_download_document as the consumer of the returned portal_document_id, which implicitly tells the caller when to use this tool (to discover document IDs before downloading). It stops short of explicit exclusions — it never says how it differs from therapyportal_list_forms or when to prefer therapyportal_get_document_counts.

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 readOnly/openWorld/non-destructive, so the safety profile is covered; the description adds genuinely new behavioral context by warning that the returned text is third-party and untrusted and must not be followed as instructions. That is high-value context beyond the structured fields, though it says nothing about result size, pagination, or freshness.

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

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

Two sentences, front-loaded with what is listed and what it reports, followed by the one safety-critical caveat. No filler or restated title.

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

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

For a read-only listing tool with zero required params, full schema coverage, and complete annotations, the description covers purpose, examples, and the untrusted-content caveat. It stops short of indicating roughly what a record contains or how many items to expect, but nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and the single 'view' enum carries a detailed explanation of compact/full/raw, so the description adds nothing about it. Baseline 3 applies since the schema fully does the heavy lifting.

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

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

Uses a specific verb+resource ('List the practice's always-available forms and documents'), plus concrete examples of what counts as standing paperwork (disclosure statement, upload) and what metadata is reported (signature/upload requirement). It implicitly separates itself from therapyportal_list_documents by emphasizing always-available/standing items, but never names the sibling, so the differentiation is inferential rather than explicit.

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

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

The phrase 'always-available forms and documents' and the 'to sign / to upload' examples give a usable sense of when this tool applies, but there is no explicit when-not guidance and no named alternative (e.g., list_documents for client-specific uploads) telling the agent which listing tool to pick.

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 readOnly/destructive=false, so the bar is lower, yet the description adds genuinely new behavior: newest-first ordering, the read-state side effect (none), the empty-inbox shape (`threads: []`), and an untrusted-third-party-content warning against prompt injection. That last point is behavioral context no annotation conveys.

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

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

Four tight sentences, each carrying distinct information — scope/ordering first, then the read-state clarification, then the empty case, then the safety note. No repetition of the tool name or schema.

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

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

With no output schema, the description carries the return-value burden and covers ordering and the empty case, but does not indicate what fields a thread object contains (e.g., subject, participants, unread count). For a simple two-parameter list tool this is nearly 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 the schema already documents both parameters and a baseline 3 applies. The description adds provenance for patient_id (derive it from therapyportal_list_clients), which is not in the schema and helps avoid guessing IDs; limit remains schema-only, which is acceptable.

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

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

States a specific verb and resource ('List one client's secure-message conversations'), plus scope (one client), domain (TherapyPortal), and ordering (newest first). An agent can distinguish this from therapyportal_get_thread_messages purely from the description.

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

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

Names the prerequisite source for patient_id (therapyportal_list_clients) and clarifies that listing does not mark anything read, which is decision-relevant context. It stops short of explicitly routing to the sibling get_thread_messages for reading a thread's contents, so it's clear but not fully prescriptive about 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 declare readOnlyHint, openWorldHint, and destructiveHint=false, so safety is covered. The description adds context beyond annotations by describing returned fields and the functional linkage to download_receipt, though it omits pagination or result limits.

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

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

Two tightly written sentences, front-loaded with the core purpose and followed by the useful cross-tool linkage. Every sentence earns its place with zero filler.

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

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

For a read-only list tool with no output schema, the description does enough: it specifies returned fields and the downstream payment_id use case. The view parameter is fully documented in the schema, so the remaining gap is minor, such as pagination behavior.

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

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

Schema description coverage is 100% and the single view parameter is thoroughly documented in the schema. The description does not mention the view parameter, so baseline 3 is appropriate since the schema carries the semantic burden.

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

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

States a specific verb (list) and resource (payments), enumerates the returned fields, and distinguishes itself by naming the sibling tool that consumes the payment_id. An agent can tell exactly what this tool does and how it relates to download_receipt.

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

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

Explicitly links to therapyportal_download_receipt by explaining it returns the payment_id that tool takes, with an example use case for insurance or HSA/FSA claims. It lacks an explicit when-not-to-use clause, but the sibling routing is clear.

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