Chia Health MCP

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

The annotation declares readOnlyHint=true, but the description states the tool 'upgrade the token to full scope' and 'the token is automatically upgraded to full scope', which is a state-changing side effect. This directly contradicts the read-only annotation, making the description misleading.

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 three concise sentences. The first sentence states the core purpose, the second gives timing/polling guidance, and the third states the prerequisite. Every sentence earns its place with no redundant text.

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 purpose, when to call, polling interval, prerequisite token, and the effect on token scope. Given the output schema exists, return values need not be described. However, the contradiction with annotations reduces overall reliability, though that is already captured in behavioral transparency.

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 already fully documents the only parameter (bearer_token) with a description 'Guest token from auth_verify_otp' at 100% coverage. The description repeats the same source, adding no meaningful new information. Baseline 3 is appropriate because the schema 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?

The description clearly states 'Check if the patient has completed payment and upgrade the token to full scope', which is a specific verb+resource and includes the unique token-upgrade side effect that distinguishes it from sibling tools like checkout_status. Adding 'Call this after sharing the checkout payment link' reinforces the intended flow.

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 explicitly tells when to use the tool ('Call this after sharing the checkout payment link') and how often to poll ('every 10-15 seconds'). It also names the prerequisite token source. It does not explicitly mention when not to use it or list alternatives, so it misses the full 'when-not/alternatives' bar for a 5.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, so the description adds some context about the 5-minute expiration window and the need for session_id. However, it doesn't disclose any side effects (e.g., invalidating the previous code) or rate limits. It does not contradict annotations, so a mid-range score is appropriate.

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

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

The description is extremely concise: two short sentences. The first sentence states the purpose, and the second provides usage conditions and prerequisite. Every word earns its place with no redundancy or fluff.

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 (1 parameter, output schema present), the description covers purpose, usage conditions, and the required input. It doesn't explain error scenarios or what happens to the previous code, but for a straightforward resend operation with an output schema, it is sufficiently 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% with a clear description of session_id as 'Session ID from auth_start.' The description reinforces this by stating 'Requires the session_id from auth_start — no email needed,' but it adds no new meaning beyond the schema. Baseline of 3 is suitable.

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: 'Resend the verification code to the patient's email.' It includes a specific verb ('resend') and resource ('verification code'), and distinguishes itself from siblings by specifying the resend use case and prerequisite session_id from auth_start.

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 conditions for use: 'Use this if the original code expired (5-minute window) or was not received.' It also clarifies that only session_id is needed, not an email, which helps the agent understand when to invoke this tool in the auth flow. It lacks explicit alternatives, but the 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 indicate destructive/read-only hints, and the description adds important behavioral context: it sends an email, returns a session_id (not a token), and discloses the exact email subject line for retrieving the code. This is valuable and 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 five sentences, each earning its place: purpose, return value distinction, email subject info, and usage timing. It is well-structured and front-loaded with the primary action.

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 complexity and the presence of an output schema, the description is complete: it explains what happens, what is returned, how to retrieve the verification code, and when to call it. It fully supports the agent in selecting and using the tool effectively.

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 100% parameter description coverage, so the schema already documents each field. The description only says 'providing their contact information' and does not add new parameter-level details. Baseline 3 is appropriate since the schema carries 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?

The description clearly states the tool's purpose: 'Start a patient session by providing their contact information. Sends a 6-digit verification code.' It specifies the action (start), the resource (patient session), and the side effect (sending a code). It also distinguishes itself from siblings by explaining the session_id flow and that it is not a token.

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

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

Explicit usage guidance is provided: 'Call this when the patient is ready to proceed with their medical intake — after browsing medications and checking eligibility.' It also states 'No authentication required' and describes the next step (use with auth_verify_otp), making the usage context 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?

Beyond the annotations (destructiveHint=true), the description adds valuable behavioral context: it specifies the returned token's scope, the tools it enables, and the upgrade path via auth_check_payment. It does not elaborate on why the operation is marked destructive (e.g., consuming the OTP), but the annotation already conveys the safety concern, so the description adds meaningful context 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?

The description is three sentences, each with a distinct purpose: the action and result, the prerequisite, and the follow-up action. Every sentence earns its place, with no redundant or filler content.

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 output schema and the clear workflow, the description is complete: it explains the token scope, the required precursor, and the next step for full access. It is well-integrated with the sibling tools and leaves no critical gaps for the agent to guess.

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% with clear descriptions for both parameters (code and session_id). The description adds extra meaning by stating that only session_id is needed and email is not, reinforcing the schema's session_id description and clarifying the login flow. It also reiterates the code format.

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 specific action (verify a 6-digit OTP), the input (code from email), and the outcome (a guest-scope bearer token for intake, consent, order, and checkout tools). It distinguishes itself from siblings like auth_resend_otp and auth_check_payment by focusing on verification and the exact scope of the returned token.

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

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

The description provides explicit usage context: it requires the session_id from auth_start, clarifies that email is not needed, and tells the agent to call auth_check_payment after checkout/payment to upgrade the token scope. This gives clear when-to-use guidance and names a relevant alternative 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 label the tool as destructive, but the description adds valuable specifics: it releases held inventory, cancels the Stripe PaymentIntent if not yet captured, and requires authentication. These details are not in the annotations and help the agent understand the full impact. 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 concise (two sentences), front-loaded with the primary action, and contains no irrelevant information. Every sentence contributes meaningful 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?

Given the destructive nature and the existence of an output schema, the description covers the essential aspects: what it does, its side effects, and authentication requirements. It lacks explicit caveats (e.g., cannot be used on completed sessions), but overall is quite complete for a cancellation tool.

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 provides clear descriptions for both parameters (checkout_id and bearer_token) with 100% coverage. 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 uses a specific verb ('Cancel') and resource ('in-progress checkout session'), clearly distinguishing it from sibling tools like checkout_complete and checkout_create. It also explains the key side effects, leaving no ambiguity about its function.

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 for when to use the tool: canceling an in-progress checkout that has held inventory and a pending PaymentIntent. However, it does not explicitly mention alternatives or situations where this tool should not be used, so it falls short of a 5.

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

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

Annotations already declare destructive and idempotent behavior. The description adds valuable context: 'Requires authentication', ACP/SPT prerequisite, and the fallback path. It does not contradict annotations and goes beyond what annotations say about when this tool is appropriate.

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

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

Three sentences with no filler: purpose, condition, alternative/auth. Front-loaded and efficiently 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?

With output schema, annotations, and a clear usage policy, the description covers when to use, when not to use, authentication, and a fallback. It is complete for an agent to decide and invoke without additional ambiguity.

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 covers all 3 parameters with descriptions (100% coverage), so baseline is 3. The description reinforces the SPT requirement and authentication need but does not add significant detail beyond the schema.

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

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

The description starts with 'Complete payment using Stripe ACP (Shared Payment Token)', which clearly states the action, method, and resource. It distinguishes from sibling tools like checkout_create, checkout_status, and checkout_cancel by specifying the completion step.

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 provides conditions for use: 'Only use this if your platform supports Stripe Agentic Commerce Protocol' and names an alternative path ('use the payment_url from checkout_create instead, then poll checkout_status') when the condition is not met. This is strong 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?

The description explains what the tool returns (checkout details including line items, total, payment options) and the payment_url behavior, going beyond the annotations. It does not contradict the annotations and adds context about the preferred vs fallback workflows.

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 well-structured with a clear purpose sentence and two labeled payment paths, making it easy to scan without being overly verbose. Every sentence adds value.

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 initiation purpose, return contents, authentication requirement, and both follow-up paths. With an output schema present, it sufficiently addresses the complexity of the tool.

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 descriptions cover both parameters fully (100%), so the baseline is 3. The description adds that authentication is required, but no additional parameter details beyond the schema.

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

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

The description clearly states 'Initiate a checkout session for a medication order' with a specific verb and resource, and it differentiates from sibling tools by explaining the two payment paths and referring to checkout_complete and checkout_status.

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 describes the two payment paths (Stripe ACP preferred, payment link fallback) and instructs to call checkout_complete or checkout_status. It also notes the need for authentication, providing clear usage context, though it doesn't explicitly state 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?

The description contradicts the annotations: readOnlyHint=true but the description states the tool 'triggers order fulfillment', implying a write/side effect. This is a serious inconsistency. The description also adds useful context like polling interval and authentication, but the contradiction overrides any positive contribution.

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 three sentences and each sentence provides meaningful information without fluff. It is front-loaded with the core purpose and includes necessary polling and authentication details.

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?

Despite having an output schema and good schema coverage, the description misleads about the tool's side effects by claiming it triggers order fulfillment while annotations say read-only. This fundamental inconsistency makes the description incomplete and unreliable for an agent, even though it covers how to use the tool.

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 baseline is 3. The description adds some value by mentioning authentication and referencing checkout_create for payment_url, but it doesn't substantially enhance parameter understanding beyond what the schema already provides.

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

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

The description clearly states the tool checks the payment status of a checkout session, using the specific verb 'check' and resource 'payment status'. It distinguishes itself from siblings by referencing polling after checkout_create and the payment_url.

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 explicitly says to use this tool for polling after sending a payment link and even provides the polling interval (every 5-10 seconds). It lacks explicit when-not-to-use or alternative tools, but the context is clear enough.

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

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

Annotations already declare destructiveHint and idempotentHint, and the description adds valuable context: authentication requirement, timing constraint, and the scope of modifications. It does not contradict any annotation and provides beyond what the annotations alone would convey.

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

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

The description is exactly two sentences, front-loaded with the primary action, and every phrase earns its place. It avoids redundancy and effectively communicates the tool's purpose and key constraints.

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 presence of an output schema, the description does not need to explain return values. It covers the core action, prerequisites (authentication), timing ('before payment is completed'), and update scope, making it complete for a checkout update tool.

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 descriptions are comprehensive (100% coverage), but the tool description enriches the 'updates' parameter with concrete examples (shipping method, promo code, customer details), giving semantic meaning beyond the generic schema 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 uses a specific verb 'Update' and resource 'existing checkout session,' clearly distinguishing it from siblings like checkout_create, checkout_cancel, or checkout_status. It also lists concrete capabilities (modify shipping method, apply promo codes, update customer details) and adds a temporal constraint ('before payment is completed').

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 for when to use the tool: 'before payment is completed' and requires authentication. It does not explicitly name alternatives or state when not to use it, but the context strongly implies it is for updating existing sessions rather than creating or canceling.

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 description adds valuable behavioral context beyond the readOnlyHint annotation: it lists the specific consent documents, notes the return fields (IDs, titles, summaries, order), and emphasizes that each consent must be fetched individually. It also mentions authentication, which is relevant for a patient-session tool. 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 well-structured and front-loaded: the first sentence states the core purpose, followed by return values, a helpful enumerated list of consent types, and a workflow note. Every sentence adds useful information, and there is no fluff 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?

Given the tool's moderate complexity and the presence of an output schema, the description is complete. It explains what the tool returns, the required consents, and the necessary workflow (fetch each via consent_text, confirm). It also notes the read-only nature implicitly through 'list' and explicitly via the annotation, making it well-rounded.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra meaning to the parameters beyond what the schema provides (intake_id and bearer_token). It mentions authentication, but that is already explicit in the bearer_token parameter 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 states the tool's purpose: 'Get the list of all consent documents a patient must accept before ordering medication.' It specifies the resource (consent documents), the action (list), and the context (before ordering medication). It also distinguishes from sibling tools like consent_text (fetch individual consent) and consent_submit (confirm consent) by focusing on listing required consents.

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 explicitly provides usage guidance: 'Each consent must be fetched individually via consent_text and confirmed by the patient before proceeding.' This names the alternative tool (consent_text) and clarifies the workflow order. It also implies that consent_list is the first step, not a replacement for fetching text or confirming.

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 description adds meaningful behavioral context beyond the readOnlyHint annotation, such as returning per-consent status and a proceed/no-proceed indication. It also notes the gating relationship with order_create and the authentication requirement. No contradictions 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 three sentences long, front-loaded with the primary purpose, and every sentence adds useful information (purpose, return values, gating behavior, authentication). No redundant or irrelevant content.

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 tool is simple with only two parameters and an output schema. The description covers the purpose, the gate behavior, return values, and authentication. The existence of an output schema makes detailed return format explanations unnecessary. The description is complete enough for correct selection and invocation.

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 (intake_id and bearer_token) are already documented. The description merely reiterates that authentication is required, which is already implied by the bearer_token parameter. Thus it adds no significant meaning beyond the schema.

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

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

The description clearly states the tool checks consent completion status for a patient intake, using a specific verb ('Check') and resource ('consents'). It also distinguishes itself from sibling tools like consent_list, consent_submit, and consent_text by focusing on completion status and progression to ordering.

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 for when to use this tool, explicitly noting it is a gate before order_create and that order_create will reject if consents are incomplete. It implies this should be used prior to ordering, though it does not explicitly say when not to use alternative consent 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?

With annotations already indicating readOnlyHint=false, idempotentHint=true, and destructiveHint=true, the description adds valuable context beyond those: 'All consent records are retained for 10 years per HIPAA requirements' and 'Requires authentication.' It also describes the return value (record with timestamp, audit trail details, remaining consents). This provides a more complete behavioral picture without contradicting the annotations, so it earns a 4.

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 paragraph composed of four sentences. The first sentence clearly states the primary action, and subsequent sentences add prerequisites, required parameters, return value, and compliance requirements. Although it's slightly longer than a two-sentence ideal, every sentence provides essential operational context with no filler. It is front-loaded with the purpose, making it efficiently scannable.

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 8 parameters, a true output schema, and annotations, the description covers all critical operational aspects: when to use it (after consent_text), what parameters are essential, what it returns (consent record with timestamp, audit trail, remaining consents), legal retention (10 years), and authentication. It does not delve into parameter-by-parameter syntax, but the schema covers that. This is a high-degree of completeness for a moderately complex tool.

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 already covers 100% of parameters with descriptions, giving a baseline of 3. The description enriches this by explicitly listing required params and providing concrete examples: 'patient's exact confirmation text (e.g. 'I agree'), consent method ('ai_agent_conversational'), the AI platform name ('chatgpt', 'claude', 'gemini')'. It also clarifies the meaning of patient_confirmation as 'exact' text, surpassing the schema's simple 'Patient's exact confirmation text'. This adds practical value, so a 4 is justified.

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 opens with a specific verb+resource: 'Record a patient's consent confirmation for a specific consent document.' It clearly distinguishes from sibling tools like consent_list and consent_status by stating this is the submission/recording action. It also specifies the required preparatory context (presenting consent_text and receiving explicit confirmation), making the tool's role unmistakable.

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 explicitly states the prerequisite: 'The agent must have already presented the full consent text (from consent_text) to the patient and received explicit confirmation.' This tells the agent when to use the tool. It references consent_text as the source of the text, implying that consent_submit is the follow-up step. However, it does not explicitly exclude alternative tools or list when-not-to-use scenarios, so it falls short of a perfect 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 declare readOnlyHint=true, so the read-only nature is already known. The description adds significant behavioral context beyond that: it returns the consent split into titled sections, must be presented verbatim, includes version/effective date/content/confirmation prompt/withdrawal instructions, lists available consent types, and notes authentication requirements. It also clarifies the prerequisite for calling consent_submit, which helps the agent understand the operational context. 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 moderately long but every sentence adds value: it states the purpose, mandates verbatim presentation, lists content elements, enumerates consent types, and gives a workflow constraint. It is structured with clear sentences, front-loading the core purpose before elaborating. No unnecessary fluff 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 tool returns structured consent text and there is an output schema (indicated by the context signal), so explaining return values is not necessary. The description covers the key contextual aspects: what the returned data contains, how it should be used (verbatim presentation), what consent types are available, and the workflow prerequisite for consent_submit. Authentication is also mentioned. This is sufficiently complete for an agent to use 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 100%, so both consent_id and bearer_token are already described in the schema. The description does not add parameter-level details beyond the schema. The mention of available consent types might help the agent understand what consent_id refers to, but since consent_id is an opaque ID from consent_list, the description does not materially enhance parameter understanding. Baseline 3 is appropriate due to high schema coverage.

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

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

The description clearly states 'Fetch the full text of a specific consent document for patient review,' which is a specific verb+resource. It distinguishes itself from siblings like consent_list (which lists IDs), consent_status (checks status), and consent_submit (submits confirmation). The explicit mention of returning sections and the verbatim presentation requirement further clarifies its unique role.

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 explicit usage context: it should be used to fetch consent text for patient review, and the agent must present it verbatim. It also states a workflow rule: the patient must confirm each consent before calling consent_submit, which helps the agent sequence tools correctly. It does not explicitly state 'when not to use,' but the alternative is implied by the sibling list and the mention of consent_submit.

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 and openWorldHint annotations, the description discloses important server behavior: 'if you don't know, leave the parameter out and the server will return what is or isn't checkable.' It also details return content and lists specific disqualifying reasons, adding valuable transparency without contradicting any 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 organized into three clear paragraphs: purpose and parameter summary, parameter selection rules, and pre-fill/return behavior. Every sentence carries essential information, with no filler. It's concise for the number of parameters covered, though slightly longer than absolutely necessary, making it a 4 rather than a 5.

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 complexity (7 parameters, 2 required, conditional logic), the description is thorough: it covers required vs optional parameters, conditional use of pregnancy_status, handling of missing values, pre-fill confirmation, return values, and disqualifying conditions. The output schema exists, so return value details aren't required, but the description still provides a high-level summary, making it 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 already has 100% parameter description coverage, so the baseline is 3. The description adds meaningful meta-guidance beyond the schema: 'Only pass parameters that apply to this patient,' how to handle uncertainty, and when pre-filling is acceptable. This lifts it above baseline, but it doesn't significantly alter the meaning of individual parameters, so a 4 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 opens with a specific verb 'Pre-screen' and identifies the resource 'a patient's basic eligibility for telehealth prescription services,' clearly distinguishing it from sibling tools like medications_availability or intake_submit. The title 'Check Eligibility' is reinforced with concrete operational context, making the tool's purpose unmistakable.

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 explicit guidance on when to call: pre-screen a patient's eligibility, pre-fill only with confirmation from prior context, and omit parameters you don't know rather than inventing values. It clearly states the rule for pregnancy_status based on biological sex. However, it doesn't explicitly name alternative tools or list exclusion scenarios, which prevents a 5.

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

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

Annotations only state readOnlyHint and openWorldHint, but the description discloses extensive behavioral traits: product-aware question selection, conditional predicates, union dedup, progressive disclosure requirements, and pre/post-checkout phases. It adds far beyond the annotations without contradicting them.

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 long but every section serves a purpose. It is front-loaded with the core purpose, followed by behavioral specifics and a well-structured numbered list of presentation guidelines. 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?

Given the tool's complexity (product-aware, multi-medication, two-phase, conditional questions) and the presence of an output schema, the description fully covers what the agent needs: when to call, how to handle responses, and what to avoid. It leaves no critical gap.

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

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

Schema already covers all parameters with descriptions. The description adds meaning to 'additional_medications' by explaining the union/dedup behavior, and clarifies that 'medication' drives product-aware content. The 'client_ip' parameter is only in the schema, but since coverage is 100%, the baseline is honored with added context for the key 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 opens with 'Get the medical intake questionnaire for the chosen medication(s)', a specific verb+resource statement. It further distinguishes itself from siblings by describing product-aware behavior and the union/dedup logic for multiple medications, clearly separating it from intake_submit or intake_status.

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 rich usage context: when to use additional_medications, the two-phase submission timing, and detailed presentation instructions. However, it does not explicitly name alternative tools or state when not to use this tool, leaving a slight gap in 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?

The description adds behavioral context beyond the readOnlyHint annotation by specifying the possible return statuses and noting that it requires authentication. It frames the tool as a polling mechanism, which implies it can be called repeatedly without side effects.

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 four sentences of direct, functional prose with no redundant filler. It front-loads the primary action and outcome, then adds usage context and an auth requirement.

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 presence of an output schema and high schema coverage, the description sufficiently covers purpose, usage context, and prerequisites. It does not detail error handling, but that is not required given the output schema exists.

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 provides full descriptions for both parameters (intake_id and bearer_token), including where intake_id comes from. The tool description adds no additional parameter-specific information, 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?

The description uses a specific verb ('Check') with a clear resource ('current status of a previously submitted intake questionnaire') and enumerates possible outcomes (under review, approved, denied). It clearly differentiates from sibling tools like intake_submit and intake_questions.

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 states when to use the tool: 'Use this to poll for provider review completion before proceeding to order placement.' This provides clear context for the use case, though it doesn't explicitly mention alternatives or when not to use it.

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 destructiveHint=true (a write operation), and the description adds meaningful context beyond that: authentication requirements, that a licensed US healthcare provider reviews the intake and makes prescribing decisions, and that it returns an intake ID and estimated review time. 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 front-loaded with the main action and then provides prerequisite, return value, and human review context in three additional sentences. Each sentence earns its place; it is slightly dense but not verbose.

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 complexity (submission, auth, validation) and that an output schema exists (so return format doesn't need explanation), the description covers the essential context: prerequisite, authentication, human review process, and return info. It could optionally mention error handling, but is sufficiently 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% (all parameters described), so baseline is 3. The description adds value by clarifying that intake_answers must contain 'all fields from intake_questions', which is a critical constraint not fully expressed in the schema. It also reinforces that bearer_token is for authentication.

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 uses a specific verb ('Submit') and resource ('completed medical intake questionnaire'), clearly distinguishing this from sibling tools like intake_questions (which fetches questions) and intake_status (which checks status). The scope is precise: submission for provider review.

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 the usage workflow: 'All fields from intake_questions must be completed' signals the prerequisite to fetch questions first. It does not explicitly name alternatives or exclusions, but the context of submission is clear relative to siblings. The 'Requires authentication' line further clarifies when the tool is appropriate.

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?

While annotations already declare readOnlyHint and openWorldHint, the description adds valuable behavioral context: it returns availability status and reason if unavailable, and explains the licensing-based state restrictions. This goes beyond the annotations by specifying the output shape and domain logic without contradicting the read-only nature.

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 three sentences with no redundant content. The first sentence states the primary action, the second provides necessary background on why restrictions exist, and the third outlines the return behavior. Every sentence earns its place, and the main purpose 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?

The tool has an output schema and annotations, and the description adds the necessary context: purpose, return value (status and reason), and the state-specific shipping nuance. Given the simplicity of the operation and the structured schema, the description is complete enough for an agent to select and invoke 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?

The schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds some context by linking medication and state to the shipping availability check, but it doesn't elaborate on client_ip or parameter syntax beyond what the schema already provides.

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

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

The description clearly states the tool's function: 'Check if a specific medication is available for shipping to the patient's state.' It uses a specific verb ('check') and identifies the resource (medication availability for shipping), and it distinguishes itself from sibling tools like medications_list or medications_details by focusing on state-specific restrictions.

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 to use the tool: when needing to verify whether a medication can be shipped to a patient's state, especially for compounded medications with state-specific restrictions. It doesn't explicitly name alternative tools or exclusions, but the purpose is evident from the phrasing 'to the patient's state' and the mention of shipping restrictions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description only needs to add context. It adds value by specifying the return structure (description and count per category) and enumerating example categories, which goes beyond the annotations. No contradiction exists.

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

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

The description is a single, information-dense sentence that front-loads the main action and then provides specific examples and output details. Every word contributes to understanding the tool's purpose and return value, with no redundant language.

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 (one optional parameter, read-only operation, output schema exists), the description fully covers what the tool does and what it returns. It states the scope (all categories), provides concrete examples, and mentions the included fields, making it self-sufficient for an agent to invoke 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?

The input schema has only one optional parameter (client_ip) with a complete description ('Client IP address for rate limiting'), giving 100% schema coverage. The tool description does not add any extra meaning for this parameter, so the baseline score 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 lists all medication categories with specific examples (Weight Loss, Peptide Therapy, Anti-Aging & Longevity) and mentions the included fields (description, count). This distinguishes it from sibling tools like medications_list and medications_details, which focus on medications themselves rather than categories.

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 category-level information is needed) but does not explicitly mention alternatives or when not to use it. It provides clear context but lacks explicit exclusionary guidance, so it falls short of a 5.

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

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

Annotations already signal readOnlyHint and openWorldHint. The description adds meaningful behavioral context by enumerating exactly what data is returned (forms, plan options, included services, side effects) and supporting both name and category queries. It does not contradict annotations and provides extra value beyond the hints.

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

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

The description is longer than typical but front-loads the main purpose and then delivers dense, useful enumeration. Each clause adds specifics (forms, pricing, included services, contraindications, side effects) without fluff, though it could be slightly more 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?

With the output schema present and annotations covering safety, the description provides a thorough overview of what can be queried and what the response will include. It covers the full query space (name/category), supported medication examples, and the practical use case, making it complete for an agent to invoke 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?

The schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds value by giving concrete examples for both medication names and categories, clarifying how the parameters are meant to be used together. This goes beyond the schema's basic descriptions.

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 uses a specific verb ('Get') and resource ('detailed information about a specific medication'), listing concrete content (dosage strengths, titration schedules, forms, pricing, contraindications, side effects). It clearly distinguishes itself from sibling tools like medications_list and medications_pricing by emphasizing detailed per-medication data.

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 states when to use the tool: 'Use this to look up exact plan durations and pricing.' It gives query patterns (by medication name or category) but does not explicitly mention when not to use it or name an alternative sibling, though the 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=true and openWorldHint=true, so the read-only nature is established. The description adds meaningful context about the medication domain (compounded by US-licensed 503A pharmacies, requiring healthcare provider evaluation) and clarifies the content of the response. It does not mention rate limiting or pagination, but with annotations covering the safety profile, this adds sufficient value beyond annotations.

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

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

The description is two sentences and front-loaded with the action 'List all available...'. It includes detailed examples (GLP-1 drugs, peptide therapies) that are useful for understanding the domain but adds some length. Each element contributes to understanding the tool's scope, so it remains appropriately concise.

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 tool has an output schema (so return values are structured separately) and annotations for read-only behavior. The description fully covers the purpose, the content domain, and key regulatory constraints. For a simple list tool, this is complete and sufficient, with no major gaps in context.

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 one optional parameter (client_ip) with full description coverage (100%), so the schema already provides complete parameter semantics. The description adds no extra parameter information, which is fine because the baseline is 3 when schema coverage is high. No compensation 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 clearly states 'List all available prescription medications' with a specific action and resource, and enumerates the return fields (names, categories, forms, starting prices). It distinguishes from sibling tools by emphasizing the complete list scope ('all available') rather than specific categories, details, or pricing, aligning with the tool's purpose.

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 by stating the tool returns a comprehensive list of all medications, making it evident when to use it for an overview. However, it does not explicitly mention alternatives or exclusions (e.g., 'for specific details use medications_details'), though sibling names are visible. This meets the 'clear context, no exclusions' criterion.

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 description discloses that the tool returns a price breakdown including cost, consultation fee, shipping, and discounts, and notes that plan durations vary by medication. Since annotations already declare readOnlyHint, the description adds context about response content and dependencies, but doesn't mention rate limiting or error behavior.

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 at three sentences, front-loaded with the main action, then return value, then usage note. No unnecessary words 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?

Given the presence of an output schema and readOnlyHint annotation, the description covers the essential input caveat (plan duration variation) and lists supported medications. It is complete and self-sufficient for the tool's purpose.

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 already includes descriptions for all four parameters, so baseline is 3. The description adds the important nuance that plan_months values vary by medication and that medications_details should be consulted first, which is semantic information not fully captured in the schema's simple '1, 4, or 6' 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 states 'Get detailed pricing for a specific medication, form, and plan duration' with a specific verb and resource. It distinguishes itself from sibling tools like medications_details and medications_availability by focusing on pricing and specifying the return breakdown.

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 directs users to 'use medications_details first to see available plan_months values,' providing a concrete workflow. It also clarifies scope by listing supported medications, effectively guiding when 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 indicate readOnlyHint=false and destructiveHint=true, but the description adds substantial context: provider review, pharmacy compounding, shipping, payment via Stripe ACP, and authentication requirements. This goes beyond the structured hints. It does not elaborate on possible destructive effects (e.g., irreversible charges), but it doesn't 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 about 140 words and logically flows from action and prerequisites to required fields, process, return values, and payment/auth. Each sentence adds value, though slightly long, it remains informative 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?

Given the tool's complexity (6 params, nested shipping address, auth, payment, provider review), the description covers prerequisites, required inputs, the review process, return values, and financial handling. It doesn't mention failure modes or denial scenarios, but that is not critical given the output schema and overall detail.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics by specifying valid values for form and plan_months, describing shipping_address keys, and noting that intake_id comes from intake_submit. This helps the agent construct valid arguments.

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 'Create a new prescription medication order' with a specific verb and resource. It distinguishes from sibling tools like order_status and order_upload by focusing on the initial creation step. The mention of prescription medication also differentiates it from checkout 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 explicitly states the prerequisite: 'The patient must have completed intake questionnaire and consent before ordering.' This tells the agent when the tool is appropriate. It does not explicitly name alternative tools, but the context strongly implies that if prerequisites are unmet, other tools (e.g., intake_submit, consent_submit) should be used first.

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 readOnlyHint already providing safety information, the description adds valuable behavioral context by noting that authentication is required and that the response includes upload status and accepted file formats. This goes beyond the annotation without contradicting it.

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, with two sentences that directly convey purpose, return content, and authentication. No unnecessary words 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?

Given the tool's simplicity, presence of an output schema, and readOnly annotation, the description sufficiently covers purpose, key return elements, and auth. It provides enough context for an agent to invoke the tool correctly without needing further explanation.

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 provides full descriptions for both parameters (order_id and bearer_token), so the baseline is 3. The description does not add further parameter-specific details beyond what the schema already covers.

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?

Description clearly states the tool retrieves the list of documents a patient must upload for an order, using the specific verb 'Get' and the resource 'list of documents'. It distinguishes from siblings like order_upload by focusing on fetching requirements rather than performing the upload.

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

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

The description establishes clear context: it is used to check required documents for a specific order, with no exclusions or alternatives mentioned. While it doesn't explicitly name sibling tools or state when not to use it, the context 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?

The annotation readOnlyHint=true already declares this as a safe read operation. The description adds useful context beyond that: the list of possible statuses, the return of tracking info and delivery estimate, and the authentication requirement. There is no contradiction, and the description supplements the annotation 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 two sentences, front-loaded with the primary purpose in the first sentence. The second sentence efficiently lists return data and a final note on authentication. There is no redundant filler; every sentence carries meaningful 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?

Given that an output schema exists (indicated by context), the description does not need to detail return structure. It covers all necessary aspects for a status-check tool: action, resource, statuses, additional outputs, and authentication. For a simple read-only operation, this is complete relative to its complexity and schema richness.

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 order_id and bearer_token have descriptions). The tool description itself does not add new meaning beyond the schema; it simply lists return fields. Since the schema fully documents parameters, baseline 3 is appropriate, and there is no extra value added 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 states the tool's action ('Get the current status of a medication order') and the specific resource (medication order). It also enumerates the possible statuses and return data (tracking, delivery estimate), making it distinguishable from sibling tools like checkout_status or order_documents. This is a specific verb+resource with clear 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 usage when one needs order status, but it does not explicitly state when to use this tool versus alternatives or provide any exclusion criteria. It mentions 'Requires authentication' as a prerequisite, which is mildly helpful, but lacks direct comparison to sibling tools or clear guidance on when not to use it.

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 a non-read-only, idempotent, and destructive operation. The description adds useful behavioral constraints (base64 encoding, supported formats, 10MB limit, authentication requirement). It does not address the destructiveHint (e.g., possible overwriting), but given annotation availability, the description still adds value.

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 concise sentences with no redundancy. The first sentence states the purpose, the second covers file requirements, and the third gives the auth requirement. 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?

The tool has 5 parameters and an output schema, plus annotations. The description covers purpose, file formats, size, and authentication. It does not explicitly explain the destructive behavior or what happens after upload, but the output schema and annotations fill some gaps. Overall, it is complete for an upload tool.

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% for all parameters, so the baseline is 3. The description reinforces parameter semantics by mentioning photo ID/selfie (matching document_type), supported formats and max size (matching file_base64 constraints), and authentication (matching bearer_token). This adds synergy beyond the schema.

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

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

The description clearly states the action ('Upload'), the resource ('a verification document for a medication order'), and the specific document types (photo ID, selfie). This distinguishes it from siblings like order_documents, which likely lists 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 conveys a clear purpose and prerequisites (authentication), and the context of a medication order makes the intended use obvious. It does not explicitly name alternatives or exclusions, but the clarity of the upload scenario is sufficient for most cases.

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 provide readOnlyHint: true, and the description aligns by using 'Get' and listing informational content. The description adds the behavioral requirement of authentication and details what data is included, which is useful context beyond 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?

The description is a single sentence that front-loads the purpose and lists the included data elements without redundant wording. It efficiently conveys the essential 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?

The description is comprehensive for a read-only retrieval tool: it specifies the scope ('current'), lists the contents, and mentions authentication. An output schema exists, so return value details are not needed in the description.

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 provides full descriptions for both patient_id and bearer_token, achieving 100% coverage. The tool description does not add any additional parameter-specific guidance, so the baseline score 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 begins with 'Get the patient's current care plan' which clearly identifies the action and resource. It enumerates specific data elements (medication, dosage, titration schedule, etc.), distinguishing it from other portal tools that handle unrelated actions.

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

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

The description establishes a clear context for when to use the tool: to retrieve the patient's current care plan. It notes the authentication requirement, which is a prerequisite. However, it does not explicitly contrast with alternative tools or state when not to use it.

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 destructiveHint:true and readOnlyHint:false. The description goes beyond by disclosing that severe side effects trigger auto-flagging for immediate provider review and return urgent guidance, and that authentication is required. This adds meaningful behavioral context not present in 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 three concise sentences, front-loaded with the primary purpose. Every sentence adds distinct information: what it does, the severe-case behavior, and the auth requirement. No waste 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 tool with an output schema and full parameter descriptions, the description covers the core behavior, edge-case behavior (severe), and auth context. It does not elaborate on non-severe outcomes or prerequisites, but these are not critical given the schema and output schema richness. Slightly more detail on the default workflow could push it to 5.

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 semantic value by explaining the consequence of the severity parameter ('severe' causes auto-flagging and urgent guidance) and reinforcing the auth requirement for bearer_token. This goes beyond simple parameter type definitions.

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 starts with a specific verb and resource ('Log side effects a patient is experiencing'), clearly distinguishing it from siblings like portal_log_weight. The additional detail about severe cases being auto-flagged further specifies the tool's unique behavior.

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 purpose implies when to use the tool (when a patient reports side effects), but it does not explicitly mention alternatives or exclusions. It lacks the specific 'use this instead of X' guidance present in high-quality examples, though the intended use is reasonably clear from the verb and resource.

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=false and destructiveHint=true, so the agent knows this is a write with potential destructive impact. The description adds the 'requires authentication' requirement and the purpose context, but does not disclose any additional behavioral traits like append vs. override behavior.

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 long with no filler. It communicates the core action, required parameters, and authentication need efficiently.

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 presence of an output schema and annotations, the description sufficiently covers the tool's purpose and requirements. It does not explain edge cases like duplicate logging or side effects, but the annotated destructive hint and output schema reduce the burden on the description.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description repeats parameter names and units but adds no new semantic information beyond what the schema provides. Baseline 3 applies because the schema carries the full 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?

The description clearly states the tool's function with a specific verb ('Log') and resource ('a patient's weight'), and adds context ('for tracking progress on their treatment plan'). It distinguishes from sibling tools by the unique resource, though it does not explicitly name alternatives.

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 provided on when to use this tool versus alternatives. It only lists required parameters and authentication, but does not mention exclusions or conditions under which to choose a different 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?

Adds meaningful context beyond annotations: returns confirmation and estimated response time, urgent messages are prioritized, and authentication is required. This complements the annotation hints, though it does not explain the unusual destructiveHint=true, but no contradiction exists.

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

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

Three concise, front-loaded sentences. Each sentence adds distinct value: purpose, outputs/priority behavior, and authentication. No fluff 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?

With an output schema present and good annotations, the description covers the core purpose, return info, priority logic, and auth. It does not detail edge cases or side effects, but those are not essential for a message-sending tool.

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 covers all 3 parameters with descriptions, so baseline is 3. The description does not add new parameter-level detail beyond the schema; it mentions urgent keywords but not as a parameter syntax explanation.

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 starts with a specific verb 'Send' and identifies the resource ('message to the patient's healthcare provider'), making the action unmistakable. It also differentiates from siblings by focusing on provider messaging, and adds useful outcomes (confirmation, response time).

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 explicit guidance on when to use this tool versus alternatives like provider_respond or portal_support. The description implies use for patient-provider communication but does not state exclusions or when to prefer another 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?

The description adds context beyond annotations: it reveals the 24-48 hour review delay and the need for authentication, complementing the destructiveHint annotation by explaining the workflow. It avoids contradicting the annotations, though it doesn't detail what destructive effects (if any) occur. This is sufficient given annotation coverage.

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 long, each with a clear purpose: the first states the action, the second explains the workflow and authentication. No unnecessary words.

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 tool with 2 parameters and an output schema, the description covers the essential action and outcome. It lacks explicit preconditions (e.g., must have a current prescription) and doesn't clarify the output shape, but the schema fills that gap. Slightly more context could be added, but it's 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?

Schema coverage is 100% for both parameters, and the descriptions are minimal but present. The tool description itself adds no additional detail about parameter semantics, 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 specific action ('Request a medication refill') and the resource ('the patient's current prescription'). It distinguishes itself from sibling tools like medications_list or order_create by focusing on the refill workflow, making it unique.

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: it creates a refill order reviewed within 24-48 hours, indicating this is for refills of existing prescriptions. However, it does not explicitly exclude alternatives (e.g., when to use order_create instead), so it falls short of a 5.

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

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

The description adds behavioral context beyond the annotations: it creates a ticket, returns a ticket ID and estimated response time, and requires authentication. Since annotations already indicate a non-read-only, non-idempotent, potentially destructive operation, the description adds useful specifics without contradiction. The destructiveHint is somewhat incongruent with the benign create action but not a direct contradiction.

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 three concise sentences with no unnecessary words. It front-loads the primary purpose, states the 'Creates' action and return values, and ends with the authentication requirement. Every sentence 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?

The description covers the essential aspects: purpose, action, return values, and authentication. Given the tool's simplicity and the presence of an output schema, the description is reasonably complete. It does not mention edge cases or prerequisites beyond authentication, but these are not critical for a support-ticket creation tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The tool description does not add any parameter-specific semantics beyond what the schema provides, so the baseline 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 states the tool's purpose: contacting customer support with a question or issue. It specifies the action (creates a support ticket) and the output (ticket ID and estimated response time), and it is distinct from sibling tools like portal_message (provider messaging) and portal_refill (prescription refills).

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 for when to use the tool: when the user has a question or issue for customer support. It does not explicitly mention alternatives or when not to use it, but the context is strong and unambiguous, earning a 4 rather than a 5.

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

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

The readOnlyHint annotation already signals a safe read operation. The description adds value by disclosing that the tool returns different messages depending on the order status ('needs_info' vs. no pending questions) and that authentication is required. This goes beyond the annotation to explain real behavior.

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 and front-loaded with the primary purpose. The second sentence about prescribing decisions adds useful context, though it could be merged with the first to reduce redundancy. Overall, it is appropriately sized for a tool with conditional behavior.

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 context: what the tool does, when it returns questions vs. a message, and authentication requirements. Since an output schema exists, it need not explain return values. This is complete for the tool's 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 description coverage is 100%, with both order_id and bearer_token already described. The tool description does not add extra parameter context, but the baseline of 3 is appropriate since the schema carries the full burden and the parameters are straightforward.

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's purpose: retrieving follow-up questions from a healthcare provider for a specific order. It distinguishes this from sibling tools like intake_questions (patient intake) and provider_respond (responding to questions) by specifying the resource and context.

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—use this when you need provider questions for an order—and even explains the conditional behavior based on order status. However, it does not explicitly mention alternatives or when not to use the tool, though the context strongly implies the appropriate use case.

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=false, idempotentHint=true, and destructiveHint=true. The description adds value by disclosing that responses are sent to the provider for review, that it returns confirmation and updated order status, and that authentication is required. These go beyond the annotation hints and provide practical expectations for the agent.

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, front-loaded with the primary action, and includes essential outcomes in the second sentence. Every word contributes: no repetition of schema fields, no vague filler. It is concise and well-structured for quick agent comprehension.

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 moderate complexity (nested answers object, 3 parameters, output schema exists), the description sufficiently covers purpose, outcome, and authentication. It does not explain prerequisites like needing to call provider_questions first, but the output schema and schema descriptions fill in many details. The description is complete enough for an agent to select and invoke 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 all parameters have descriptive text. The tool description does not add additional meaning beyond the schema: no formatting constraints, examples, or behavioral notes for parameters. It only mentions 'Requires authentication' which aligns with the bearer_token parameter, but does not enrich parameter understanding. 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 states the verb and resource: 'Submit answers to provider follow-up questions for a specific order.' It distinguishes from siblings like provider_questions (which likely requests questions) by specifying the submission action and intended recipient. The additional outcome 'sent to the provider for review' further clarifies the tool's unique role.

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 clear use context: use when you have answers to provider follow-up questions for an order. It does not explicitly exclude alternatives or provide when-not-to-use guidance, but the context is specific enough that an agent can infer when this tool is appropriate. No explicit alternative tools are named, but the sibling 'provider_questions' suggests the complementary flow.

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