Chia Health MCP Server

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

The description states the token is automatically upgraded to full scope, which is a mutating side effect. However, annotations declare readOnlyHint=true, directly contradicting the described behavior. This is an annotation 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 concise and well-structured: it leads with the primary purpose, then gives the trigger and polling cadence, and finally specifies the required token. Each sentence adds key operational information without filler.

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

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

The description covers the essential operational details: when to call, polling frequency, side effect, and required input. An output schema exists, so return values need not be explained. However, the contradiction with readOnlyHint introduces confusion about the tool's true side effects, reducing overall completeness.

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 sole parameter bearer_token is fully described in the schema as 'Guest token from auth_verify_otp', and the description merely repeats this requirement. With 100% schema coverage, the description adds no additional semantic value 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 a specific action: check if payment is completed and upgrade the token to full scope. It distinguishes itself from siblings by emphasizing the token upgrade and unlocking of portal tools, not just checking payment 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?

Explicitly tells when to use: after sharing the checkout payment link, and provides polling interval of 10-15 seconds. It does not explicitly mention alternatives or when not to use it, 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 mutation and destructiveness (readOnlyHint=false, destructiveHint=true). The description adds context about the session_id requirement and the 5-minute expiry, but doesn't elaborate on side effects such as invalidating the previous code. With annotations covering the safety profile, this is adequate but not rich.

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

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

The description is two sentences, front-loading the core action and then providing usage context and a prerequisite. Every sentence carries essential information with no 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 simplicity (one parameter, output schema available), the description covers purpose, usage condition, parameter prerequisite, and recipient (email). It is sufficient 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?

Schema description coverage is 100%, so the schema already explains session_id as 'Session ID from auth_start'. The description adds 'no email needed,' which clarifies the parameter set slightly, but otherwise adds little 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 action: 'Resend the verification code to the patient's email.' It uses a specific verb and resource, and the context of resending OTP is distinct from sibling tools like auth_verify_otp and 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 notes that only session_id is required. However, it does not provide explicit when-not-to-use scenarios or name alternative tools, 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?

Beyond annotations (which already indicate non-read-only, non-idempotent, and destructiveHint), the description adds rich behavioral context: no authentication required, sends a 6-digit code to email, returns session_id (not token), and locates the code in the email subject line. This exceeds the baseline and provides clear operational expectations.

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 with four sentences, each earning its place. It front-loads the primary action and then adds crucial flow details (session_id vs token, email subject, no auth, when to call). No fluff or redundancy.

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

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

Given the tool's complexity (starting a session with side effects) and the presence of an output schema, the description covers all essential aspects: purpose, flow, relation to verification, email subject line, no-auth requirement, and patient readiness timing. It leaves no major gaps for an agent to correctly select and invoke 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 minimal extra meaning about parameters (e.g., email is used for sending the code) but doesn't significantly compensate beyond schema details. It does not introduce new parameter semantics.

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: 'Start a patient session by providing their contact information' and distinguishes itself from siblings like auth_verify_otp by explaining it sends a code and returns a session_id, 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?

The description provides explicit when-to-use guidance: 'Call this when the patient is ready to proceed with their medical intake — after browsing medications and checking eligibility.' It also outlines the next step (use with auth_verify_otp) and offers practical tip about email subject line, effectively guiding the agent through alternatives.

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

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

Annotations include destructiveHint=true, and the description adds useful context about token scope and the upgrade path, which goes beyond annotations. It does not explain the destructive nature (e.g., OTP invalidation), but since the annotation already flags it and the description provides flow context, it's good 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?

The description is three short sentences, each adding critical information: what it does, prerequisite, and next step. No wasted words; front-loaded with the main purpose.

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?

There is an output schema, so return values are covered. The description covers prerequisites, token scope, and next step, making it context-rich. It doesn't discuss failure modes or rate limits, but given the presence of structured data, this is acceptable.

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 meaning by clarifying that session_id comes from auth_start and that no email is needed, plus the code is 6-digit and from email. This enriches the parameter understanding 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 verifies a 6-digit OTP code and returns a guest-scope bearer token for specific downstream tools. This distinguishes it from siblings like auth_start, auth_check_payment, and auth_resend_otp by specifying the exact action and output.

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 context: requires session_id from auth_start, explicitly says no email needed, and directs when to call auth_check_payment after checkout/payment. This gives clear when-to-use and next-step guidance, even if it doesn't mention auth_resend_otp explicitly.

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?

Despite annotations already indicating destructive and non-read-only behavior, the description adds critical detail: it releases held inventory and cancels the associated Stripe PaymentIntent if not yet captured. This goes beyond the annotations and explains what happens, including a conditional aspect. 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?

Two sentences with no filler. The first sentence states the core action, and the second covers additional effects and authentication. All information is relevant and 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?

Given the output schema exists and annotations cover safety, the description is largely complete for a cancellation tool. It covers purpose, effects, and authentication. Minor gaps like error conditions or prerequisites are not mentioned, but they are not essential for this 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%, so the parameters are already well-documented by the schema. The description does not add extra semantics beyond referencing 'checkout session' in the text, which aligns with the schema's checkout_id description. Baseline 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_create, checkout_complete, and checkout_status. It also adds scope ('in-progress') and key effects (releases inventory, cancels Stripe PaymentIntent), making the 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 phrase 'in-progress checkout session' provides clear context for when to use this tool, implying that it is for sessions not yet completed. However, it does not explicitly state when not to use it or name alternatives (e.g., use checkout_complete to finish), so it lacks explicit exclusions.

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

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

Annotations already indicate non-read-only, idempotent, and destructive behavior. The description adds 'Requires authentication' and the prerequisite that the platform must support ACP and have an SPT, providing useful context beyond annotations. It doesn't explicitly state the irreversible charge, but the annotations signal a write operation.

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

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

The description is three sentences: the first states the purpose, the second gives a condition, and the third provides an alternative. Every sentence earns its place without redundancy or fluff, and it is front-loaded with the core 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, the presence of an output schema, and sibling tools, the description covers purpose, conditions, alternatives, and authentication requirement. It explicitly references checkout_create and checkout_status, integrating it well into the larger workflow. No critical information is missing.

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

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

Schema descriptions cover all three parameters at 100%, so the baseline is 3. The description adds value by explaining that shared_payment_token is an SPT from the client platform and referencing payment_url from checkout_create as the alternative when ACP isn't supported, enriching understanding of the token parameter.

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 'Complete payment using Stripe ACP (Shared Payment Token),' which is a specific verb+resource and clearly distinguishes this tool from checkout_create (which creates the session) and checkout_status (which polls). It explicitly states the ACP flow, making its purpose unambiguous.

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

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

It says 'Only use this if your platform supports Stripe Agentic Commerce Protocol and can provision an SPT.' Then it explicitly says, 'If your platform does NOT support ACP, use the payment_url from checkout_create instead, then poll checkout_status.' This provides explicit when-to-use, when-not-to-use, and a direct alternative.

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

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

Annotations already indicate idempotency and destructiveness, and the description adds valuable behavioral context by explaining the return contents (line items, total, payment options) and the two possible continuation flows. It does not contradict the annotations, though it could further clarify the implication of destructiveHint, but the added flow guidance is substantial.

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 opening sentence and a numbered breakdown of the two payment paths. Every sentence contributes to understanding the tool's purpose and follow-up actions, though it is slightly longer than strictly necessary; still, the structure aids readability and 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 presence of an output schema (which handles return details) and annotations (handling idempotency/destructiveness), the description focuses on the essential workflow context: what the tool does, what it returns, and how to proceed via either payment path. This makes the description complete for an agent to correctly select and invoke 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?

The input schema already covers both parameters with descriptions (100% coverage), so the description adds little beyond reaffirming that authentication is required. It does not provide additional syntax, constraints, or formatting details beyond what the schema offers, hence a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Initiate a checkout session for a medication order.' It also distinguishes itself from sibling tools by explaining the two payment paths and referencing checkout_complete and checkout_status as subsequent actions, making its role in the workflow explicit.

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

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

The description provides explicit when-to-use guidance by detailing two payment paths: if ACP/SPT is available, use checkout_complete; otherwise, fall back to payment_url and poll with checkout_status. It also states the prerequisite of authentication, clarifying the context for invoking 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 declare readOnlyHint=true, but the description reveals a side effect: 'triggers order fulfillment.' This directly contradicts the read-only annotation, making the behavioral profile inconsistent. The description does add valuable context (polling, auth, side effect), but the contradiction forces a score of 1 per the rubric.

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 purpose stated first, then usage, side effect, polling interval, and auth requirement. Every sentence adds value without 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?

For a simple status-check tool, the description covers all necessary context: what it checks, when to use it, the side effect (triggering fulfillment), polling recommendations, and authentication. An output schema exists, so return format need not be described.

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

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

Schema coverage is 100% and both parameters have descriptive titles/schema descriptions. The tool description adds no extra meaning about parameters beyond mentioning checkout_id implicitly and authentication, which is already in the schema. Baseline 3 is appropriate.

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

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

The description states a clear verb and resource: 'Check the payment status of a checkout session.' It also distinguishes this from siblings by referencing checkout_create and the payment_url, making it unambiguous that this is the polling tool for payment 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 explicitly says when to use it: 'Use this to poll for completion after sending the patient a payment link.' It also gives a polling interval. However, it does not mention alternatives like auth_check_payment or when not to use it, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description doesn't need to restate those. It adds useful context about timing and authentication, but does not elaborate on potentially destructive side effects or idempotency behavior further. This aligns with the annotations, not 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?

Two sentences provide a clear, front-loaded purpose, then list specific capabilities and a key constraint. No waste 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?

With a full input schema, output schema, and annotations, the description covers the essential purpose, timing, and authentication. It could mention edge cases like what happens if payment is already completed, but given the structured data available, this is adequate.

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?

All parameters are described in the schema (100% coverage), including the 'updates' object description that mirrors the tool description. The tool description repeats content already in the schema without adding new syntax or structural details, so baseline 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 and resource ('Update an existing checkout session') and enumerates concrete modifications (shipping method, promo codes, customer details). This clearly distinguishes it from sibling tools like checkout_create, checkout_cancel, 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?

The phrase 'before payment is completed' provides clear temporal context for when this tool is appropriate, and 'Requires authentication' is a prerequisite. However, it does not explicitly name alternatives or exclusion cases (e.g., when to use checkout_cancel instead).

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 the description adds useful behavioral context: returns a list with specific fields, requires authentication, and each consent must be individually fetched and confirmed. There is no contradiction with annotations. The description enriches the agent's understanding of the flow without overexplaining.

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 main purpose, then elaborates with return fields, a list of required consents, and workflow guidance. Every sentence earns its place and there is no fluff. It's well-structured for quick agent parsing.

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 an output schema, the description still provides a clear summary of the return contents and the procedural context (individual consent fetching). It covers usage timing, authentication, and the workflow, making it complete for an agent to select and invoke correctly for a read-only list 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%, with both intake_id and bearer_token described. The description adds 'Requires authentication,' which lightly reinforces bearer_token, but doesn't add meaning beyond what the schema provides. Since the schema carries the parameters, 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 verb+resource: 'Get the list of all consent documents.' It distinguishes itself from sibling tools by specifying that it returns IDs, titles, summaries, and order, and by mentioning that individual consents are fetched via consent_text. The purpose is unambiguous and contextually specific to medication 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 the tool ('before ordering medication') and directs the user to consent_text for individual consent fetch and confirmation. It doesn't explicitly contrast with consent_status or consent_submit, but the workflow is implied well enough. This is clear context without explicit exclusions, so a 4 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?

Annotations provide readOnlyHint=true, and the description adds return behavior (status of each consent and proceed flag) and the gate relationship with order_create. Also notes authentication requirement, adding 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?

Three concise sentences, front-loaded with purpose, no redundant information. Each 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?

With a read-only annotation, output schema, and 100% schema coverage, the description fully explains the tool's purpose, return value, usage context (gate for order_create), and authentication requirement. Complete for the 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 covers both parameters with descriptions (100% coverage), and the description doesn't add specific parameter details beyond what's in the schema. The reference to 'patient intake' and 'authentication' aligns with but doesn't extend 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?

Description clearly states 'Check whether all required consents are complete for a patient intake' with a specific verb and resource. It distinguishes from siblings by framing as a gate before ordering, unlike consent_list or consent_submit.

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 frames the tool as a gate before ordering, noting that order_create will reject if consents are incomplete. Provides clear context for when to use, though it doesn't name alternatives or exclusions explicitly.

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 write, idempotent, and destructive hints, the description adds valuable behavioral context: HIPAA-mandated 10-year retention, requirement for exact confirmation text, audit trail details, and authentication requirement. It does not contradict any 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 moderately structured but contains an unnecessary and incorrect enumeration of required parameters that conflicts with the schema. While the core purpose, prerequisite, and retention info are useful, the parameter list wastes space and adds confusion.

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 purpose, prerequisite, return value (consent record with timestamp and remaining consents), retention, and authentication. Combined with the output schema and annotations, it is quite comprehensive. However, the parameter required-list error is a notable completeness 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?

The schema already provides full coverage of all 8 parameters with descriptions (100% coverage). However, the description incorrectly lists more parameters as required than the schema marks as required (only intake_id, consent_id, patient_confirmation are required; consent_method, agent_platform, agent_session_id are optional). This misleading information degrades the parameter semantics.

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 records a patient's consent confirmation for a specific consent document, with a specific verb ('record') and resource. It distinguishes itself from siblings like consent_text (provides text) and consent_list/status (read consent data) by focusing on the submission action.

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 and received explicit confirmation. This provides clear guidance on when to use this tool and references the sibling tool for the prior step.

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 annotation, the description details the output structure (split sections, version, effective date, confirmation prompt, withdrawal instructions) and imposes a strict behavioral requirement: present verbatim and do not summarize. It also notes the necessity of patient confirmation before proceeding. This is substantial behavioral context 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 front-loaded with the primary purpose, then logically details output composition, available consent types, mandatory presentation behavior, confirmation prerequisite, and authentication. Every sentence adds valuable information without 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?

For a read-only fetch tool, the description covers purpose, output structure, usage rules, available types, confirmation flow, and authentication. An output schema exists, so return value details are not needed. 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?

Schema description coverage is 100% for both parameters, with consent_id described as 'from consent_list' and bearer_token described as authentication token. The description adds minimal extra parameter meaning beyond the schema, as it focuses on output and usage rather than parameter formatting or constraints. Baseline 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 fetches the full text of a specific consent document for patient review, using the specific verb 'Fetch' and resource 'consent document'. It distinguishes from siblings by detailing the output contents (version, effective date, sections, etc.) and explicitly mentioning the available consent types.

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 by stating the agent must present the returned text verbatim to the patient and that the patient must confirm before consent_submit can be called. It also references consent_list for the ID. However, it does not explicitly state when not to use it or compare to consent_status, though 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, so safety is clear. The description adds rich behavioral detail: it discloses that unknown parameters should be omitted rather than invented, that pre-filling requires explicit patient confirmation, and that the response includes eligibility status, available medications, and disqualifying reasons. 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 three short paragraphs, each earning its place: first states purpose, second gives parameter rules, third covers pre-fill behavior and return content. It is front-loaded with the purpose and avoids filler, making it easy for an agent to parse.

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 7-parameter tool with output schema, the description is exceptionally complete: it explains parameter semantics, covers edge cases (biological sex/pregnancy), provides patient-confirmation policy, and describes return values (eligibility status, medications, disqualifiers). Even with the output schema present, this adds essential 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?

Schema coverage is 100%, so baseline would be 3, but the description significantly adds meaning: pregnancy_status only for females, BMI threshold for GLP-1 products, confirmation-before-prefill requirement, and omit-if-unknown guidance. This goes beyond the schema's property descriptions and clarifies how to interact with the server.

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 clear verb phrase, 'Pre-screen a patient's basic eligibility for telehealth prescription services', which conveys exactly what the tool does and its scope. It distinguishes itself from sibling tools like 'medications_*' by focusing on eligibility pre-screening, and from 'intake_*' by being a read-only check.

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 strong usage context: it is for pre-screening before prescription services, and it gives specific parameter-passing rules ('Only pass parameters that apply', 'omit it entirely for males'). It does not explicitly name an alternative tool for a when-not-to-use case, but the unique purpose and sibling list make the usage 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 declare readOnlyHint and openWorldHint, but the description adds significant behavioral detail: two-phase return (pre_checkout/post_checkout), conditional_on predicates, union deduplication for multiple medications, and the requirement not to submit post_checkout answers before payment. This substantially exceeds the annotations' disclosure.

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 sentence earns its place. It starts with a crisp definition, then adds necessary behavioral nuance, and the numbered presentation list is highly structured and scannable. There is no fluff or redundancy.

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

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

Given the tool's complexity (conditional logic, multiple phases, presentation rules) and that an output schema exists, the description is complete. It covers when to use, how to present, sequencing with payment, and provider review, requiring no further inference.

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

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

Although schema coverage is 100%, the description adds meaningful semantics: it explains how the 'medication' slug determines question sets (GLP-1 vs. NAD+), and how 'additional_medications' triggers union/deduplication behavior. This goes beyond the schema's bare parameter descriptions and helps the agent choose correct values.

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 and resource: 'Get the medical intake questionnaire for the chosen medication(s).' It clearly distinguishes from siblings like intake_submit and intake_status by emphasizing retrieval of questions, not submission or status. It also explains product-aware behavior (GLP-1 vs. NAD+), further clarifying 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 provides an explicit 5-step protocol for presenting the questionnaire to patients, covering progressive disclosure, conditional logic, quiz formatting, section ordering, and verification before submission. It also names the alternative 'intake_submit' and clarifies sequencing. This goes well beyond implied usage.

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 signals a safe read operation. The description adds valuable context beyond this: it requires authentication and specifies the nature of the returned statuses (under review, approved, denied). It does not contradict annotations and provides meaningful behavioral details.

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 well-structured, with the main purpose front-loaded. Each of the four sentences adds distinct value: what it does, what it returns, when to use it, and a necessary prerequisite (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 output schema exists, the description does not need to fully enumerate return values, but it still provides a clear summary. It covers the input source, the statuses, the use case, and authentication. The context is complete for a user deciding to invoke this tool among many siblings.

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 intake_id and bearer_token have clear descriptions. The description text itself adds minimal parameter-specific information, only reinforcing that intake_id is from a previous submission and that authentication is required. Since the schema already handles parameter semantics, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb 'Check' and resource 'status of a previously submitted intake questionnaire.' It further lists possible statuses and the reviewing entity, distinguishing it from other status tools like consent_status and order_status. The mention of polling before order placement adds workflow 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 explicitly states when to use the tool: 'Use this to poll for provider review completion before proceeding to order placement.' This provides clear context and timing, though it does not name alternative tools or explicitly state when not to use it. It implies use after intake submission.

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, and the description complements this by adding that authentication is required, the tool returns an intake ID and estimated review time, and that a licensed US provider reviews the intake. This extra context is valuable beyond the annotation flags, though it doesn't elaborate on state changes or 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, each providing essential information: the action, prerequisite, return value, and authentication. It is front-loaded with the core purpose and contains 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?

With an output schema present, the description doesn't need to detail return structure. It covers prerequisites, provider involvement, and authentication. The complexity of nested intake_answers is partially addressed via the guidance to complete all fields. It lacks explicit information about error cases or idempotency, but annotations and schema fill some gaps, making it reasonably complete.

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

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

The input schema already documents all four parameters with descriptions and 100% coverage. The description adds minimal extra meaning, only noting that intake_answers must be completed and align with intake_questions. This is helpful but not substantial given the baseline of 3 for 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 the tool's function: submitting a completed medical intake questionnaire. It specifies the resource (intake questionnaire) and the action (submit for provider review), which distinguishes it from sibling tools like intake_questions (retrieving questions) and intake_status (checking status). The verb 'submit' is specific and unambiguous.

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

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

The description provides clear usage context by stating that all fields from intake_questions must be completed, implying this tool should be used after obtaining the questions. It also notes the downstream provider review and prescribing decisions, giving a sense of when in the workflow this applies. However, it does not explicitly name 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 readOnlyHint and openWorldHint, so the description builds on that by adding behavioral context: it explains the reason for state-specific restrictions (pharmacy licensing) and discloses the return content (availability status and reason if unavailable). This adds value beyond annotations without 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 two sentences, front-loaded with the primary action, and includes only relevant context. Every sentence earns its place: the first states the verb and resource, the second explains the restriction and return format. No wasted 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?

Given the relatively simple tool with an output schema and readOnly annotations, the description is sufficiently complete. It covers purpose, restriction context, and return content. It does not mention client_ip's rate-limiting role, but that is in the schema, so the description doesn't need to repeat it.

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

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

Schema coverage is 100%, providing baseline 3. The description adds meaning by explaining why 'state' matters (state-specific licensing restrictions for compounded medications), which is not present in the schema. This clarifies the significance of the parameters beyond their raw 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 states a specific action ('Check if a specific medication is available for shipping') with a clear resource (medication) and scope (patient's state). It distinguishes from sibling tools like medications_list or medications_pricing by focusing on availability and shipping 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 for when to use the tool: to verify shipping availability of a medication for a specific state, especially given compounded medication licensing restrictions. It does not explicitly name alternatives or exclusions, but the context is specific enough for an agent to infer appropriate use.

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 and openWorldHint already present, the description adds value by disclosing the output structure—each category includes a description and medication count. It does not mention pagination or rate limits, but for a simple listing tool the provided context is sufficient 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 a single well-structured sentence that front-loads the action and resource, then provides illustrative examples and output details. No redundant or filler 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?

The tool is a simple read-only listing with an output schema and complete parameter documentation. The description covers the categories included and the structure of each category, making it fully adequate for an agent to select and invoke 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?

The single optional parameter (client_ip) is fully documented in the input schema with a clear description. The tool description adds no additional parameter guidance, so the baseline of 3 applies because schema coverage is high.

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 on the telehealth platform, with specific examples (Weight Loss, Peptide Therapy, Anti-Aging & Longevity). This distinguishes it from sibling tools like medications_list (which lists medications) and medications_pricing, making the purpose unambiguous.

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

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

The description implies the tool is for viewing available categories but provides no explicit guidance on when to choose it over sibling tools such as medications_list or medications_details. There are no stated exclusions or alternatives, leaving the usage context somewhat implied.

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 goes beyond the basic readOnlyHint annotation by detailing the exact type of data returned (dosage strengths, titration schedules, forms, plan pricing, contraindications, side effects). It does not contradict annotations, and it adds useful context about the tool's output scope, though it does not cover potential rate limiting or other hidden behaviors (which are partially indicated by the client_ip parameter).

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

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

The description is detailed and well-organized, starting with the core purpose and then listing contents in a structured way. While it is on the longer side, every sentence adds useful information, and it ends with a clear usage directive. It could be tightened slightly, but it earns a strong score.

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

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

The tool has a rich output schema (not shown but implied by has_output_schema=true), so the description does not need to explain return structure. The description covers all key aspects: what data is included, how to query, and the specific use case for plan durations and pricing. 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 coverage is 100% with parameter descriptions, so the baseline is 3. The description adds extra value by providing concrete example medication names and categories, and by indicating that 'medication' and 'category' are mutually alternative query modes, which goes beyond the schema's simple parameter 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 clearly states the tool's purpose: 'Get detailed information about a specific medication' and enumerates specific content (dosage strengths, titration schedules, forms, plan options, pricing, contraindications, side effects). It also distinguishes from sibling tools like medications_list and medications_pricing by explicitly mentioning lookups for 'exact plan durations and pricing' and supporting queries by name or category.

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: 'Use this to look up exact plan durations and pricing.' It also explains how to query (by medication name or category), but it does not explicitly mention when not to use it or name alternatives, so it misses the 'when-not' aspect that would earn 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 readOnlyHint=true and openWorldHint=true. The description adds valuable context beyond annotations by explaining the source (US-licensed 503A pharmacies), the prescription requirement, and the types of data returned. 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 core purpose in the first words, uses three focused sentences, and wastes no words. Every sentence adds value, including the final context about compounding pharmacies and provider evaluation.

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

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

Given the low parameter count, presence of an output schema, and annotations, the description is complete. It covers what the tool returns, the domain context, and the regulatory setting, making it fully adequate for 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?

There is only one optional parameter, client_ip, and the schema fully covers it with 'Client IP address for rate limiting'. With 100% schema coverage, the description does not need to add parameter details, so baseline 3 is appropriate.

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

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

The description states the specific verb 'List all available prescription medications' and clearly identifies the resource. It also differentiates from sibling tools like medications_details and medications_pricing by emphasizing the all-encompassing list scope and overview return fields.

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 clearly implies this tool is for getting a comprehensive overview of all medications, with category, form, and price summaries. It does not explicitly mention alternatives or exclusions, but the context is strong enough for an agent to select this for broad listing rather than specific details or pricing.

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 safe read nature is covered. The description adds behavioral context about what the price breakdown includes (medication cost, fee, shipping, discounts) and that plan durations vary by medication. This goes beyond annotations, though it doesn't discuss rate limiting or other edge behaviors, but those are in the schema.

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, front-loaded with the purpose. Each sentence adds value: what it does, what is returned, and a prerequisite. No redundant phrases or filler. It's concise and well-structured.

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

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

For a simple read tool with an output schema, the description is complete: it covers purpose, return contents, and a prerequisite. It names supported medications and refers to medications_details for plan durations. It doesn't explain client_ip, but the schema covers that. The openWorldHint and output schema reduce the burden, so this is sufficient.

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 parameters are well-documented in the schema. The description adds some context by identifying the key inputs (medication, form, plan duration) and warning that plan_months values vary by medication, nudging to use medications_details. This is helpful but doesn't significantly deepen parameter understanding 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's purpose with a specific verb ('Get detailed pricing') and identifies the resource (medication, form, plan duration). It distinguishes from siblings by focusing on pricing, not availability or details. The return components are explicitly listed, making it unambiguous.

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

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

The description provides clear usage context by instructing to 'use medications_details first' to see available plan_months values, establishing a prerequisite. It also mentions which medications are supported, implicitly covering scope. However, it doesn't explicitly name alternatives like medications_availability or state when not to use this tool, so it's not fully exhaustive.

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 provides rich behavioral context beyond the annotations: provider review, compounding at a 503A pharmacy, direct shipping, return of order ID and delivery window, and payment processing. It also notes authentication is required, which goes beyond the readOnly/Idempotent/destructive flags. 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 primary action and uses 8 short sentences to cover prerequisites, required fields, workflow, output, payment, and auth. Each sentence adds meaningful detail; however, some information (like required fields) partially duplicates the schema, slightly reducing efficiency. It remains well-structured and appropriately sized for a complex tool.

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 all key aspects: purpose, prerequisites, required parameters, post-order workflow, return values, payment method, and auth. Given the tool has a nested shipping_address and output schema, the description compensates with context like delivery window and provider review time. It is sufficiently complete for an agent to use.

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 meaning by linking intake_id to completed intake/consent, specifying the exact allowed form values (injectable, tablet, drops), and noting the authentication requirement for bearer_token. This adds value beyond the schema's field 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 opens with a specific verb-object pair ('Create a new prescription medication order'), clearly distinguishing it from sibling tools like order_status or checkout_create. It also specifies the medication order context, making its purpose unambiguous.

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

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

It explicitly states that the patient must have completed intake questionnaire and consent before ordering, establishing clear prerequisites. It does not name alternative tools or explicitly state when not to use it, but the context strongly implies usage after intake_submit and consent_submit and before payment via checkout.

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 include readOnlyHint=true, confirming this is a safe read operation. The description adds valuable context beyond the annotation: it requires authentication, and it returns upload status and accepted file formats. This discloses behavioral traits (auth need, return contents) without contradicting the read-only hint.

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

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

The description is two sentences. The first sentence states the core purpose and target, and the second adds return content specifics and the authentication requirement. No filler or repetition; every sentence is purposeful and 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?

Given that an output schema exists (as indicated in context signals), the description does not need to explain return values. It covers the tool's purpose, authentication, and key output elements (documents, upload status, formats). For a read-only tool with well-documented parameters, this is fully complete.

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

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

The input schema has 100% description coverage, with both order_id and bearer_token described. The description does not add extra parameter-specific semantics beyond mentioning the patient context. With the schema already handling parameter meaning, a baseline 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 verb 'Get' and the resource 'documents a patient needs to upload for their order', distinguishing it from sibling tools like 'order_upload'. It also specifies that it returns required documents, upload status, and accepted file formats, making the 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 gives clear context: use this tool to retrieve required documents for a specific order. It does not explicitly name alternatives or exclusions, but the phrase 'needs to upload' implies this is a prerequisite step before uploading. No explicit 'when-not-to-use' is provided, but the context is clear enough for a 4.

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; description adds return details (status list, tracking info, delivery estimate) and prerequisite authentication, which provides context beyond the annotation without 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?

Three concise sentences front-load the purpose, then list return data and auth requirement. No unnecessary 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?

Output schema exists, so return values are covered. Description covers purpose, return content, and auth prerequisite, making it complete for a read-only tool with a single required parameter.

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 order_id described as from order_create and bearer_token as auth token. Description adds no additional parameter semantics but meets baseline.

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

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

The description uses the specific verb 'Get' with resource 'medication order' and explicitly lists possible statuses, distinguishing it from checkout_status, intake_status, and consent_status siblings.

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 for tracking order progress ('current status') and requires authentication, but does not mention when not to use or compare with alternative tools like checkout_status or order_documents.

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

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

Annotations already provide readOnlyHint=false, idempotentHint=true, and destructiveHint=true. The description adds useful behavioral context about base64 encoding, supported formats (PDF, JPEG, PNG), maximum size (10MB), and the authentication requirement. It does not contradict the annotations, but it does not elaborate on the destructive hint (e.g., whether uploads overwrite existing documents), which with annotations present is acceptable.

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, appropriately sized, with the main action and resource stated first. It efficiently communicates key constraints (formats, max size, authentication) without unnecessary words. 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?

Given the complexity (5 parameters), existing output schema, and annotations, the description covers the essential invocation context: purpose, input format, constraints, and authentication. A brief note on the destructive behavior (overwrite?) would have pushed it to 5, but the annotations already signal this and the output schema covers response structure.

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?

All 5 parameters are described in the schema, so the baseline is 3. The description reinforces that document_type can be 'photo_id' or 'selfie' and that file_base64 must be base64-encoded with format/size constraints, but these details are already in the schema. The description adds minimal new meaning beyond what the schema 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 begins with 'Upload a verification document for a medication order,' clearly identifying the action (upload) and the resource (verification document for an order). This distinguishes it from sibling tools like order_documents (likely to list documents) and order_create (to create the order itself).

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 a verification document (photo ID or selfie) must be uploaded for a medication order. It also notes required authentication, formats, and size limit. However, it does not explicitly mention alternatives or when not to use it, though the context makes the primary use case 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 the description adds 'Requires authentication' which is a useful prerequisite. It also lists the data fields to expect, providing behavioral context 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 a single, well-structured sentence that front-loads the primary purpose and then lists the care plan components. Each list item adds value, and there is no redundant information, making it highly concise and 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's simplicity, the presence of an output schema, clear annotations, and full parameter coverage, the description is sufficiently complete. It tells the agent what data will be returned, the authentication requirement, and the tool's read-only nature, so no critical context is missing.

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

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

Schema description coverage is 100%, so the schema already documents both patient_id and bearer_token. The description does not add additional meaning about parameter formats or constraints beyond what the schema provides; it only restates 'patient' and 'authentication' implicitly.

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 with a specific verb and resource: 'Get the patient's current care plan.' It enumerates the included elements, which distinguishes it from sibling tools like portal_refill or portal_log_weight, making the intent 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 implies usage when a care plan is needed, and the sibling list shows other tools for different actions, but it does not explicitly state when not to use this tool or mention alternatives. The context is clear enough for an agent to select it, but it lacks explicit exclusion guidance.

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

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

Annotations already indicate a destructive write operation (readOnlyHint=false, destructiveHint=true). The description adds meaningful context beyond this: severe severity triggers auto-flagging for immediate provider review and returns urgent guidance, plus requires authentication. 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?

Two concise sentences. The first defines the core purpose, the second adds critical behavioral caveats. No unnecessary words, and information 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?

Combined with a rich schema, output schema, and annotations, the description covers the essential points: purpose, severe-case behavior, and authentication. The output schema handles return values, so the description is sufficiently complete for this 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?

Schema has 100% parameter description coverage, so baseline is 3. The tool description enriches the 'severity' parameter by explaining the special severe-case behavior and implicitly references 'bearer_token' through the authentication requirement, adding value beyond the schema.

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

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

States clear verb+resource: 'Log side effects a patient is experiencing.' This distinctly identifies the tool's function and differentiates it from sibling logging tools like portal_log_weight and portal_message by specifying the clinical 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?

Provides clear context for when to use the tool ('a patient is experiencing' side effects) and adds a conditional behavior for severe cases that helps guide decision-making. However, it does not explicitly mention alternatives or when not to use, though the domain specificity makes this less critical.

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/idempotency hints. The description adds the authentication requirement and purpose context, but does not detail side effects, record creation behavior, or error conditions. It neither contradicts nor substantially extends the annotation-provided behavioral security profile.

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 core purpose, and includes only necessary details (required inputs and authentication). No redundant or vague 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 small parameter set, presence of an output schema, and annotations covering destructive behavior, the description sufficiently covers purpose, inputs, and authentication. It could mention whether this creates a new record or overwrites, but the verb 'log' implies appending, so the description is adequate for a simple logging 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 parameter documentation is already complete. The description restates the required parameters but does not add new semantic insight (e.g., units, formats, or constraints) beyond what the schema 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 states a specific verb ('log') and resource ('a patient's weight') for a clear purpose ('tracking progress on their treatment plan'). This clearly differentiates it from siblings like portal_log_side_effects and portal_message.

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 purpose and listing required inputs (patient_id, weight in pounds, date) and authentication. It does not explicitly mention alternatives or exclusions, but the resource-specific purpose makes the usage scenario 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 flag destructiveHint=true, and the description adds extra behavioral context beyond that: it returns confirmation and estimated response time, and urgent messages with specific keywords are prioritized. It also states the authentication requirement. 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 three sentences, front-loaded with the action, then return behavior, urgent handling, and authentication. Every sentence adds value with 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?

The tool is simple, has an output schema, and full schema coverage, so the description is mostly complete. It covers purpose, return behavior, urgent flagging, and auth. It does not mention exclusions or alternatives, but that is more relevant to usage guidelines; overall it is sufficient for a messaging 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 parameters (message, patient_id, bearer_token) are already well-documented. The description does not add parameter-specific semantics beyond what the schema provides, so a 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 ('Send') and resource ('patient's healthcare provider'), clearly distinguishing this from sibling tools like provider_respond or portal_support. It avoids ambiguity and tautology.

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

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

The description gives clear context for when to use this tool (sending a message to a provider) and mentions urgent message handling, but it does not explicitly contrast with sibling tools or state when not to use it. This is sufficient but not as explicit as naming alternatives.

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

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

The description adds context beyond annotations: it states the action creates a refill order, requires authentication, and has a 24-48 hour review window. These details are not in the annotations and align with the readOnlyHint=false and destructiveHint=true flags, providing additional behavioral transparency without 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, front-loaded with the primary purpose, followed by the key behavioral outcome and authentication requirement. Every sentence provides distinct value 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 simple parameter set (2 params, no enums, no nested objects) and the presence of an output schema, the description covers the essential aspects: purpose, creation of an order, provider review timing, and authentication. It is slightly incomplete regarding post-request actions or potential side effects, but these are either covered by annotations or the output schema.

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

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

The schema description coverage is 100%, with both patient_id and bearer_token clearly documented. The description adds no extra parameter-specific meaning beyond saying authentication is required, which is already evident from the bearer_token schema. Baseline 3 is appropriate since 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 explicitly states 'Request a medication refill for the patient's current prescription,' which is a specific verb and resource, and further clarifies that it creates a refill order reviewed by a provider. This distinguishes it from sibling tools like medications_list or order_create.

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 clearly implies the context for use: when a patient needs a refill on an existing prescription. It also mentions the review timeline and authentication requirement, giving actionable context. However, it does not explicitly state alternatives or when not to use the 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 says 'Creates a support ticket', which is a creation action, but annotations set destructiveHint=true, implying destructive behavior. This is a direct contradiction, so the score is 1.

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

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

Two sentences, front-loaded with action and outcome. No wasted words, ideal length for the tool's purpose.

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?

Description covers what it does, what it returns (ticket ID and estimated response time), and notes authentication requirement. However, the destructiveHint contradiction leaves a behavioral gap, so it is not fully complete.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds no new parameter semantics beyond 'message' and 'subject' being part of a ticket, which is self-evident. Baseline 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?

States a specific action ('Contact customer support') with a clear resource ('support ticket'), and explicitly names the resource created. Distinguishes from siblings like portal_message and portal_refill by focusing on support requests.

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?

Indicates the tool is for questions or issues, which gives clear contextual usage. Does not explicitly exclude alternatives, but the purpose is specific enough to infer when 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?

The description adds meaningful behavioral context beyond the readOnlyHint annotation: it specifies the authentication requirement and the conditional return logic (questions if status is 'needs_info', message if none). This is more informative than just the annotation, though it does not cover all edge cases like invalid order IDs.

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 serving a purpose: primary function, context, and return behavior. It is front-loaded with the main action, avoids redundancy, and contains 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?

The description covers core function, conditional return, and authentication, leveraging the output schema (not shown) to handle return details. It is complete for a simple read tool, though it does not specify prerequisites like whether the order must exist or be in a particular state beyond 'needs_info'.

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 clear descriptions for both order_id and bearer_token. The tool description adds minimal parameter-specific meaning; it references 'a specific order' and 'requires authentication,' which aligns with the schema but does not significantly augment it. 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?

Description clearly states the tool retrieves follow-up questions from the healthcare provider for a specific order, distinguishing it from siblings like provider_respond (which likely submits responses) and intake_questions (which handle intake). The verb 'get' and resource 'provider questions' are specific, with scope defined by 'for a specific order'.

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: to fetch pending provider questions for an order, with behavior conditional on order status ('needs_info'). It does not explicitly name alternatives or exclusion criteria, but the context is sufficient for an agent to select it appropriately.

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 that responses are sent to the provider and that it returns confirmation and updated order status, plus requires authentication. However, it does not explain the destructive hint (e.g., overwriting previous responses), leaving some behavioral ambiguity.

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, immediately stating the action and outcome. It is concise, front-loaded, and contains no wasted 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?

With an output schema present, return values are already documented. The description covers the main action, the need for authentication, and the effect (responses sent to provider, order status updated). It omits the prerequisite relationship with provider_questions and the destructive overwrite behavior, but given the tool's simplicity and existing structured hints, 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 description coverage is 100%, with each parameter having a description. The tool description adds no additional parameter-level meaning; for instance, the 'answers' object's keyed-by-question-ID structure is already in the schema. Thus the description does not enhance the schema's parameter semantics.

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 answers' and identifies the resource as 'provider follow-up questions for a specific order.' This clearly distinguishes it from the sibling tool 'provider_questions' (which retrieves questions) and other submission tools like intake_submit.

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 is for submitting answers to a specific order's provider follow-up questions and requires authentication. It does not explicitly name alternatives or state when not to use it, but the context is unambiguous enough for an agent to infer 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.