Chia Health MCP

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

The description states the tool 'upgrade[s] the token to full scope' and performs unlocking actions, which are state mutations. However, annotations declare readOnlyHint: true, indicating a safe, non-mutating operation. This is a direct contradiction regarding the tool's safety profile and 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?

Three compact paragraphs efficiently separate purpose/when-to-use, behavioral mechanics (polling/unlocking), and authentication requirements. No redundant or filler text; every sentence provides actionable guidance.

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?

Comprehensive for a state-transition tool: explains prerequisites (guest token), trigger condition (payment detection), side effects (token upgrade, portal unlocking), and operational pattern (polling). Output schema exists, so return value details are appropriately omitted.

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

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

With 100% schema description coverage, the baseline is 3. The description repeats the schema's explanation that the bearer_token comes from auth.verify_otp without adding syntax details, validation rules, or format specifics beyond the structured 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 explicitly states the dual purpose: checking payment completion and upgrading the token scope. It clearly distinguishes this from sibling checkout tools (which handle payment creation) and portal tools (which require the upgraded 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?

Provides explicit temporal guidance ('Call this after sharing the checkout payment link'), polling frequency ('every 10-15 seconds'), and outcome expectations ('unlocking portal tools'). Clear sequence relative to auth.verify_otp and checkout workflow.

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

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

Adds critical behavioral context beyond annotations: specifies the 5-minute expiration window and email delivery mechanism. Does not explicitly detail the destructive impact on previous codes, but annotations cover the safety profile (destructiveHint: true).

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

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

Three sentences with zero waste: first defines action, second states conditional usage with specific timing, third specifies prerequisites. Front-loaded with verb and efficiently structured.

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

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

Given presence of output schema and clear annotations, description is complete. It covers the auth flow sequence, timing constraints, and parameter sourcing—sufficient for an agent to invoke correctly in the context of sibling tools.

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?

While schema has 100% coverage, description adds semantic value by specifying the session_id's provenance ('from auth.start') and clarifying that email is handled implicitly rather than via parameter ('no email needed').

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

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

Description states specific action ('Resend the verification code'), recipient ('patient's email'), and clearly distinguishes this from auth.start (initiation) and auth.verify_otp (verification) by positioning it as a retry mechanism.

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

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

Explicitly states when to use ('if the original code expired (5-minute window) or was not received'), references prerequisite sibling tool ('Requires the session_id from auth.start'), and clarifies negative constraints ('no email needed').

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

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

While annotations indicate destructive/write behavior, the description adds crucial behavioral context: the exact email subject line format ('Chia Health: Your code is XXXXXX'), the fact that it sends a 6-digit code, and the Gmail MCP integration tip. It does not explicitly clarify what makes the operation 'destructive' (e.g., if it invalidates previous sessions), preventing a perfect score.

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

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

Every sentence earns its place: purpose (sentence 1), side effect (2), return value clarification (3-4), email format (5), integration tip (6), prerequisites (7), and workflow timing (8). Information is front-loaded and logically ordered despite the length.

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 complex multi-step authentication flow and presence of output schema, the description provides excellent completeness: it explains the session_id vs. token distinction, the OTP delivery mechanism, integration with email providers, and exact placement in the patient journey (after eligibility, before intake).

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

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

With 100% schema description coverage, the baseline is 3. The description refers to the parameters collectively as 'contact information,' which provides conceptual grouping, but does not add significant semantic details (format constraints, validation rules) beyond what the schema already documents for email, phone, first_name, and last_name.

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 'Start[s] a patient session' and distinguishes it from auth.verify_otp by explicitly noting it returns 'a session_id (NOT a token)' and that verify_otp is needed to get the bearer token. Specific verb, resource, and scope are all present.

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 explicit temporal guidance: 'Call this when the patient is ready to proceed with their medical intake — after browsing medications and checking eligibility.' Also notes prerequisites ('No authentication required') and explicitly names the sibling tool (auth.verify_otp) for the next step in the workflow.

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

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

Annotations indicate destructive/non-idempotent operation; description adds crucial behavioral context about the dual-scope token system (guest-scope vs full scope) and the specific workflow sequence. Could improve by explicitly stating that the OTP code is consumed/invalidated upon verification (the destructive aspect).

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

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

Three sentences perfectly structured: (1) core action and return value, (2) input requirements, (3) workflow continuation. Every sentence carries essential information with zero redundancy. Excellent information density.

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

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

Given the presence of an output schema, the description appropriately focuses on workflow context rather than return value structure. Covers the complete auth sequence (start → verify → checkout → check_payment) and token scoping. Minor gap: could mention token expiration or that the code is single-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?

With 100% schema coverage, baseline is 3. Description adds value by clarifying workflow dependency ('Requires the session_id from auth.start') and explicitly noting that no email parameter is required despite mentioning email as the delivery channel, preventing confusion.

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 specific action (Verify the 6-digit code), identifies the resource (OTP code sent to patient's email), and clearly distinguishes its role in the auth flow from siblings like auth.check_payment by specifying it returns a 'guest-scope' token vs full 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?

Explicitly states prerequisite ('Requires the session_id from auth.start'), clarifies what input is NOT needed ('no email needed'), and provides clear workflow guidance ('After checkout and payment, call auth.check_payment to upgrade'). Also specifies which tools work with the returned token.

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?

Excellent disclosure of side effects beyond annotations: explicitly states that held inventory is released and Stripe PaymentIntents are canceled (conditioned on capture status). The 'Requires authentication' text also adds context not present in annotations. Matches the destructiveHint annotation appropriately.

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

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

Three sentences with zero waste: first establishes core action, second details specific side effects (inventory/PaymentIntent), third states auth requirement. Front-loaded and efficient.

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

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

Given the presence of output schema and comprehensive annotations (destructive, idempotent), the description covers the essential behavioral contract. It appropriately omits return value details (covered by output schema) but could explicitly mention idempotency to align with the idempotentHint annotation.

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%, establishing a baseline of 3. The description adds valuable semantic context: 'in-progress' characterizes the checkout_id state requirement, and 'Requires authentication' reinforces the bearer_token's purpose. It does not add syntax examples or format details, but the state context lifts it above baseline.

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

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

The description clearly states the core action using a specific verb ('Cancel') and resource ('in-progress checkout session'). It implicitly distinguishes from siblings like checkout.complete by emphasizing 'in-progress' and 'cancel', but does not explicitly contrast usage against alternatives in the text.

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 notes the target state ('in-progress') which provides implicit context, but lacks explicit guidance on when to prefer this over checkout.complete, prerequisites for cancellation, or conditions where cancellation might fail.

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

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

Annotations indicate idempotent/destructive, while description adds critical context: Stripe ACP protocol specifics, SPT provisioning requirement, and authentication needs ('Requires authentication'). Does not contradict annotations; destructive nature aligns with completing payments.

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

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

Four efficient sentences total. Front-loaded with purpose ('Complete payment...'), followed by conditional usage, alternative path, and auth requirement. No redundant text; every sentence clarifies selection or invocation constraints.

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

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

Given destructive annotations, output schema existence, and 100% param coverage, description adequately covers the ACP-specific flow and prerequisites. Could briefly mention idempotency behavior, but sufficient for a payment completion tool with these structured fields.

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% description coverage, establishing baseline 3. Description references parameters contextually ('Shared Payment Token', 'Requires authentication') but does not add significant semantic detail beyond what the schema already provides for each property.

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 specific action ('Complete payment'), mechanism ('Stripe ACP'), and resource ('Shared Payment Token'). Clearly distinguishes from sibling tools checkout.create and checkout.status by specifying this is for ACP-capable platforms only.

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 explicit conditional logic: 'Only use this if...' followed by the alternative workflow using checkout.create's payment_url and checkout.status for non-ACP platforms. Names specific sibling tools as 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 indicate idempotent/destructive hints; the description adds valuable workflow context (SPT provisioning, payment_url presentation, polling requirements) and authentication requirements. Could explicitly acknowledge the idempotent nature or destructive side effects (financial transaction creation) to reach 5.

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

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

Perfectly structured with zero waste: opening sentence establishes purpose, second sentence previews return values, clearly labeled 'TWO PAYMENT PATHS' section uses numbered list for workflow clarity, and ends with brief auth requirement. Every sentence earns its place.

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

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

For a complex financial tool with destructive/idempotent annotations and output schema, the description comprehensively covers return values (line items, total, payment options), workflow integration points, and next-step tool invocations. No gaps given the structured schema richness.

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

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

Schema coverage is 100%, establishing baseline 3. The description implicitly references 'order_id' via 'medication order' context and mentions authentication requirements mapping to 'bearer_token', but doesn't add semantic details beyond the complete schema 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 uses a specific verb ('Initiate') with clear resource ('checkout session') and domain context ('medication order'). It clearly distinguishes this creation step from sibling tools like checkout.complete and checkout.status by focusing on session initialization.

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?

Excellent explicit guidance: it names sibling tools directly ('call checkout.complete', 'call checkout.status'), explains the two distinct payment workflows (Stripe ACP vs payment link), and clarifies when to use each path (preferred vs fallback).

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?

Description states 'this tool... triggers order fulfillment' indicating a write side effect or state mutation, but annotations declare readOnlyHint=true (no modifications). This is a direct contradiction regarding the tool's safety profile and mutativeness.

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

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

Four sentences with logical flow: purpose statement, workflow initiation, behavioral outcome, operational constraints. No redundancy; dense with actionable guidance including specific polling interval and cross-reference to checkout.create.

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?

Comprehensive coverage of the asynchronous payment workflow, including polling timing, auth needs, relationship to checkout.create, and side effects. Output schema exists so omitting return value descriptions is appropriate.

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

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

With 100% schema description coverage, baseline is 3. Description adds workflow context linking the checkout_id to checkout.create's payment_url, and emphasizes the bearer_token requirement via 'Requires authentication' without repeating schema text.

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

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

Specific verb 'Check' + resource 'payment status of a checkout session'. Clearly distinguishes from sibling checkout.create by referencing its output (payment_url) and establishes the polling use case distinct from checkout.complete or checkout.cancel.

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

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

Explicit when-to-use: 'poll for completion after sending the patient a payment link'. Identifies prerequisite tool checkout.create. Provides concrete polling frequency (5-10 seconds) and states authentication requirement.

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 idempotentHint=true and destructiveHint=true, covering the mutation safety profile. The description adds valuable context about the authentication requirement and the pre-payment lifecycle constraint, though it doesn't explain the idempotent behavior or failure modes.

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 compact sentences with clear front-loading of the primary action. The structure is efficient, though 'Requires authentication' stands as a fragment that could be smoother (e.g., 'Requires bearer_token authentication').

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 output schema, annotations, and 100% parameter coverage, the description appropriately covers the essential domain context: the update scope, authentication requirement, and lifecycle timing (pre-payment). It satisfies the completeness needs for this complexity level.

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

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

With 100% schema description coverage, the schema fully documents all three parameters (checkout_id, updates, bearer_token). The description mirrors this information by mentioning what can be updated without adding syntax details or constraints beyond the schema, meeting the baseline for high-coverage schemas.

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

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

The description clearly states the specific action ('Update an existing checkout session') and enumerates exactly what can be modified (shipping method, promo codes, customer details). This effectively distinguishes it from siblings like checkout.create (which initiates) and checkout.complete (which finalizes).

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 implicit usage context via 'before payment is completed,' establishing when in the lifecycle this tool applies. However, it lacks explicit guidance contrasting when to use this versus checkout.create or checkout.complete for session management.

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

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

While annotations declare readOnlyHint=true, the description adds substantial behavioral context: specific return fields (IDs, titles, summaries, order), enumeration of expected consent types (telehealth, HIPAA, etc.), and workflow constraints that these must be accepted before ordering. Could mention rate limits or caching, but strong coverage otherwise.

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

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

Four sentences with logical flow: purpose → return values → specific examples → workflow/next steps. The enumeration of five specific consent types adds length but provides useful expectations. 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?

Comprehensive for a read-only list operation. Covers purpose, return structure, specific content examples, authentication needs, and integration with the broader consent workflow using sibling tools. Output schema exists, so needing less detail on return values is appropriate.

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

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

With 100% schema coverage, baseline is 3. Description adds semantic value by contextualizing 'intake_id' within the medication ordering workflow ('before ordering medication') and reinforcing the authentication requirement mentioned in the parameter 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 opens with a specific verb+resource ('Get the list of all consent documents') and clear scope ('a patient must accept before ordering medication'). It distinguishes from siblings by explicitly mentioning 'consent.text' for individual fetching and implies this is for listing only.

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 documents the workflow sequence: use this tool first to get required consents, then fetch text via 'consent.text', and confirm before proceeding. Names the sibling tool directly as the next step and establishes the temporal context ('before ordering medication').

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 adds critical workflow context: it declares the tool is a 'gate', explains the rejection behavior of downstream order.create, and discloses 'Requires authentication' which clarifies the bearer_token parameter's necessity.

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

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

Four sentences with zero waste: purpose first, return value second, critical workflow warning third, and authentication requirement fourth. Every sentence earns its place 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?

With readOnlyHint annotation and existing output schema, the description provides complete workflow context (gate behavior, ordering prerequisite) and security requirements without needing to detail return 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?

Schema coverage is 100%, establishing a baseline of 3. While the description mentions 'patient intake' and 'authentication' providing semantic context for intake_id and bearer_token, the schema already fully documents both parameters with clear descriptions.

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

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

The description uses specific verb 'Check' with resource 'consents' and scope 'patient intake'. It distinguishes from siblings like consent.submit (write) and consent.list (enumerate) by focusing on completion status validation.

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

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

Explicitly states the workflow relationship: 'This is a gate — order.create will reject if consents are incomplete.' This tells the agent exactly when to invoke the tool (before ordering) and warns of the dependency on sibling tool order.create.

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 idempotentHint=true and destructiveHint=true. Description adds valuable behavioral context beyond these flags: HIPAA retention policy (10 years), authentication requirements, and return value structure (timestamp, audit trail, remaining consents). Could explicitly clarify destructive nature (irreversibility of consent recording) but retention policy implies permanence.

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?

Six sentences each earning place: purpose, prerequisites, parameters, return values, compliance, auth. Parameter enumeration is lengthy but necessary for legal-sensitive operation. Front-loaded with clear purpose statement. No redundant 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?

Exceptionally complete for compliance-critical tool. Covers workflow prerequisites, specific parameter guidance with examples, return value description, HIPAA retention requirements, and authentication needs. Output schema exists but description appropriately summarizes return structure without redundancy.

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% (baseline 3). Description adds significant semantic value: specific example values for patient_confirmation ('I agree'), enumerated values for agent_platform ('chatgpt', 'claude', 'gemini'), and purpose context for agent_session_id ('for audit trail'). Explains consent_method default value even though schema lists it.

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

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

Description opens with specific verb 'Record' and resource 'patient's consent confirmation', clearly distinguishing from sibling tools consent.text (which presents text), consent.list (which lists consents), and consent.status (which checks status). Explicitly identifies it submits consent for a specific document.

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

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

Explicitly states prerequisite workflow: agent must have already presented full consent text from doctormcp_get_consent_text (referencing the consent.text sibling) and received explicit confirmation. This creates clear sequencing guidance distinguishing when to use consent.text vs consent.submit.

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

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

Annotations only declare readOnlyHint=true. Description adds critical behavioral constraints: MUST present verbatim without paraphrasing, lists document contents (version, date, sections), enumerates available consent types, and specifies authentication needs. Lacks minor details like idempotency or caching for a 5.

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

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

Six sentences each deliver distinct value: purpose, presentation constraint, content structure, available types, workflow prerequisite, and auth requirement. Front-loaded and efficient for a high-stakes domain, though dense.

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?

Comprehensive for consent retrieval: covers retrieval purpose, presentation obligations, workflow integration with submit sibling, and prerequisites. Output schema exists, so detailed return structure documentation is unnecessary beyond the content listing provided.

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

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

Schema has 100% description coverage (consent_id source and bearer_token purpose already documented). Description mentions 'Requires authentication' generally and references 'specific consent document' but adds no new semantic details about parameter format or validation 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?

Uses specific verb 'Fetch' with clear resource 'full text of a specific consent document'. Explicitly distinguishes workflow from sibling consent.submit by stating this retrieves text for review prior to confirmation.

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 maps the workflow sequence: present text verbatim → patient confirms → only then call consent.submit. Includes prerequisite 'Requires authentication' and prohibits summarization, giving clear when-to-use and behavioral constraints.

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?

Excellent disclosure beyond annotations. While annotations declare readOnlyHint=true and openWorldHint=true, the description adds specific business logic (age 18+, BMI 20+, pregnancy exclusions, disqualifying conditions like medullary thyroid carcinoma/MEN2) and explicitly states return values (eligibility status, available medications, disqualifying reasons). No contradictions with annotations.

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

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

Two dense sentences with zero waste. First sentence establishes purpose; second enumerates specific validation rules and return payload. Every clause earns its place by conveying critical business constraints or response structure.

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 complex 7-parameter medical eligibility tool with business-critical validation rules, the description is comprehensive. It covers purpose, specific criteria logic, and return value semantics. Since an output schema exists, the brief mention of return contents is sufficient without detailing the full schema 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?

With 100% schema description coverage, the baseline is 3. The description adds valuable specificity about disqualifying medical conditions (medullary thyroid carcinoma, MEN2 syndrome) that is not present in the schema's generic 'List of diagnosed medical conditions' description, providing crucial context for the 'conditions' 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 uses specific verbs ('Pre-screen', 'Checks') with the exact resource ('eligibility for telehealth prescription services'). It clearly distinguishes from siblings like intake.questions, medications.availability, and order.create by focusing specifically on pre-screening eligibility criteria rather than gathering full intake data or processing orders.

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 term 'Pre-screen' implies this should be used early in the patient flow before prescription services, but there are no explicit when-to-use guidelines (e.g., 'Call this before order.create') or when-not-to-use exclusions. The agent must infer usage timing from the 'pre-screen' label alone.

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?

Substantially augments the readOnlyHint and openWorldHint annotations by disclosing the two-phase structure (pre_checkout/post_checkout), detailed content categories (GLP-1 history, MTC/MEN2, etc.), completion requirements, and the human review process by licensed providers.

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?

Well-structured with four information-dense sentences that front-load the core purpose. The detailed phase breakdown, while lengthy, is essential behavioral context for a medical workflow tool and 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?

Complete for a high-complexity medical domain tool. Covers regulatory context (licensed US provider), workflow phases, completion requirements, and content structure. Since output schema exists, the description appropriately focuses on behavioral semantics rather than return value documentation.

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

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

With 100% schema description coverage, the structured documentation already explains 'medication' and 'client_ip'. The description implies the medication parameter through prescription context but adds no explicit syntax guidance beyond what the schema provides, warranting the baseline score.

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 the specific verb 'Get' and resource 'full medical intake questionnaire', clearly distinguishing it from sibling tools like 'intake.submit' (which submits answers) and 'provider.questions' (which handles provider-side queries). The scope is well-defined as pre-prescription evaluation.

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 workflow context indicating when to use the tool ('before a provider can evaluate them for a prescription'), but stops short of explicitly naming sibling alternatives like 'intake.submit' for submitting responses or contrasting with 'provider.questions'.

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=true annotation, description adds valuable context: specific return states (under review/approved/denied), that a licensed healthcare provider reviews it, authentication requirement, and polling pattern. 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?

Four sentences, each earning its place: purpose, return values, usage guidance, auth requirement. Front-loaded with core action, no filler. Optimal density for a status-checking 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?

Comprehensive for a read-only status tool: covers workflow position, return states, auth needs, and polling behavior. Given output schema exists and annotations declare readOnly, this is sufficient; minor gap on error conditions (e.g., invalid intake_id handling).

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

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

Schema coverage is 100% with clear descriptions (intake_id references doctormcp_submit_intake, bearer_token describes auth). Description adds workflow context ('previously submitted') and reinforces auth requirement, but schema carries the primary documentation load.

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

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

Specific verb 'Check' + resource 'intake questionnaire status' + return values 'under review, approved, or denied'. Clearly distinguishes from sibling intake.submit (which creates) and intake.questions (which retrieves questions).

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

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

Explicit workflow guidance: 'Use this to poll for provider review completion before proceeding to order placement.' establishes when to use (polling) and sequence (before order placement). Would be perfect if it explicitly mentioned intake.submit as prerequisite, though this is partially covered in schema parameter description.

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

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

Adds significant context beyond annotations (destructiveHint=true, readOnlyHint=false): explains return values ('intake ID and estimated provider review time'), discloses the medical review process ('reviewed by a licensed US healthcare provider who makes all prescribing decisions'), and notes authentication requirement. Does not contradict annotations.

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

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

Four high-value sentences with zero redundancy: purpose statement, prerequisite validation, return value disclosure, and medical reviewer context. Information is front-loaded and every sentence earns its place. Appropriate length for a medical workflow tool with compliance implications.

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?

Comprehensive for a regulated medical tool. Covers workflow prerequisites (sibling tool usage), output expectations (ID and timing), compliance context (licensed US provider, prescribing decisions), and access control (authentication). With destructiveHint annotations and implied output schema, description provides sufficient operational 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%, establishing baseline 3. Description adds validation semantics: 'All fields from intake.questions must be completed' imposes a completeness constraint on the intake_answers object not explicit in the schema. No additional parameter format details provided, but sufficient given comprehensive 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?

Excellent specificity: 'Submit a completed medical intake questionnaire for provider review' clearly identifies the verb (submit), resource (intake questionnaire), and destination (provider review). The scope immediately distinguishes this from sibling intake.questions (which retrieves questions) and intake.status (which checks 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?

Explicit prerequisites state when to use this tool: 'All fields from intake.questions must be completed' directly references the sibling workflow tool. Also notes 'Requires authentication,' stating an access prerequisite. Clear sequencing guidance: use intake.questions → complete fields → then intake.submit.

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

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

Adds valuable domain context beyond annotations: explains the external dependency on 'pharmacy licensing' (complementing openWorldHint) and clarifies return structure ('availability status and reason if unavailable'). Does not contradict readOnlyHint=true since it frames the action as checking/verifying rather than modifying.

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 efficient sentences: first states core purpose, second provides essential regulatory context about compounded medications, third describes output structure. Every sentence earns its place with 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?

Complete for a read-only lookup tool with 100% parameter coverage. Since an output schema exists (per context signals), the brief mention of return values ('availability status and reason') is sufficient. Covers the critical domain-specific constraint (pharmacy licensing) that an agent needs to interpret results 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?

With 100% schema description coverage, the schema already fully documents all parameters (including format examples for state abbreviations and rate limiting purpose for client_ip). The description references 'medication' and 'state' but does not add syntax, validation rules, or semantics beyond the schema-defined 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 uses specific verb 'Check' with clear resource 'medication availability' and scope 'shipping to the patient's state'. It clearly distinguishes from sibling tools like medications.list (enumeration) and medications.details (attributes) by focusing on shipping eligibility and geographic 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?

Provides clear context that the tool handles 'compounded medications' with 'state-specific restrictions based on pharmacy licensing', implying when it's needed (regulatory checks). However, it does not explicitly contrast with alternatives like medications.list or state when NOT to use it (e.g., 'don't use for non-compounded drugs').

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 covered by annotations, the description adds valuable behavioral context by disclosing specific category examples and stating that each category includes a 'description and count of available medications'—helpful context about the data structure returned without duplicating the output 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 single compound sentence is efficiently structured with the core action front-loaded ('List all medication categories'), followed by specific examples and return-value metadata. No repetition of schema fields or annotation data; content 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 presence of annotations and an output schema, the description appropriately focuses on domain context (specific category types) rather than return value mechanics. It adequately covers the simple single-parameter interface, though it could optionally note the authentication implications suggested by the auth.* 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 coverage is 100% for the single optional 'client_ip' parameter, which is fully documented in the schema itself. The description adds no parameter-specific guidance, but the baseline score of 3 is appropriate given the schema's complete self-documentation.

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 ('List') and resource ('medication categories'), specifies the platform context ('telehealth platform'), and clearly distinguishes itself from sibling tools like 'medications.list' (which returns individual medications) by focusing on category-level aggregation.

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 implied usage context through concrete category examples (Weight Loss, Peptide Therapy), suggesting when users might invoke this tool. However, it lacks explicit workflow guidance on when to use this versus 'medications.list' or 'medications.details' in a multi-step discovery process.

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=true in annotations, the description appropriately focuses on detailing the comprehensive data payload rather than safety warnings. It successfully discloses the breadth of returned information (including medical safety data like contraindications) that is not evident from the annotations alone.

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?

Information-dense and front-loaded with the comprehensive data list in the first sentence. The structure efficiently packs specific enumerations (dosage forms, inclusion items) into readable comma-separated lists. Minor deduction for the length of the first sentence, though every clause conveys necessary domain specificity.

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 existence of an output schema and the complex medical domain, the description is complete. It thoroughly covers the tool's scope, query methods (by name or category), and specific use cases without needing to duplicate return value documentation.

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

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

Schema description coverage is 100%, providing baseline documentation for all parameters. The description echoes the example values present in the schema (e.g., 'semaglutide', 'weight loss') but does not add semantic information about parameter interactions or constraints beyond what the schema already provides.

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

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

The description explicitly states the tool 'Get detailed information about a specific medication' and comprehensively enumerates the specific data returned (dosage strengths, titration schedules, forms, plan options, pricing, contraindications, side effects), clearly distinguishing it from sibling list/availability tools.

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

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

Provides explicit positive guidance with 'Use this to look up exact plan durations and pricing,' indicating when to invoke the tool. However, it lacks explicit differentiation from the sibling 'medications.pricing' tool or guidance on when to prefer 'medications.list' 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?

The description adds crucial behavioral context beyond annotations: it discloses that medications require evaluation by a licensed US healthcare provider before prescribing (authorization requirement) and that they are compounded by US-licensed 503A pharmacies (data provenance). It also previews the return structure.

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 information-dense and front-loaded with the main action. While lengthy due to specific medication examples, each sentence earns its place — the examples clarify domain scope, the return value sentence clarifies output, and the final sentence adds critical compliance context.

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 existence of an output schema (per context signals), the description appropriately focuses on domain context (compounded wellness treatments) and regulatory requirements rather than exhaustively detailing return values. It covers the medical/pharmacy compliance context necessary for safe usage.

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

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

With 100% schema description coverage, the schema fully documents the optional 'client_ip' parameter for rate limiting. The description does not mention parameters, but this is acceptable given the schema's completeness; it meets the baseline of 3.

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 'List' with the resource 'prescription medications' and clearly distinguishes this from siblings by stating it returns 'names, categories, available forms, and starting prices' — implying a catalog/overview function versus medications.details or medications.pricing which would serve different specific needs.

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?

While the description clearly defines what the tool returns (implying it should be used for browsing the medication catalog), it lacks explicit guidance on when to use sibling tools like medications.details or medications.availability instead. The differentiation is implicit rather than stated.

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

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

Annotations indicate read-only (safe) and open-world (external data). Description adds valuable disclosure of return structure (medication cost, consultation fee, shipping, discounts) and business logic ('discounts for longer plans'). Clarifies parameter dependency behavior (plan_months varies by medication).

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

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

Four efficient sentences: purpose upfront, output structure, workflow prerequisite, and valid examples. Each sentence earns its place. No redundancy with schema annotations. Well-structured and appropriately sized.

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?

Comprehensive coverage for a pricing tool: prerequisites, output structure breakdown, valid input examples, and discount logic. Output schema exists per context signals, so detailed return value explanation in description is bonus value, not requirement. Addresses all key workflow questions.

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% (baseline 3). Description adds meaningful concrete medication examples (semaglutide, tirzepatide, etc.) beyond generic 'Medication name' in schema. Clarifies the conditional relationship between medication and valid plan_months values, compensating for schema's static example list.

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?

Clear specific verb 'Get' + resource 'pricing' + scope 'for a specific medication, form, and plan duration'. Explicitly distinguishes from sibling medications.details by stating to use that tool first for plan values, and implicitly from medications.list/availability by focusing on detailed price breakdowns vs catalog listings.

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?

Excellent explicit sequencing guidance: 'use medications.details first to see available plan_months values'. Establishes clear prerequisite workflow. Minor gap: doesn't explicitly contrast with checkout tools for actual purchasing flow.

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

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

Annotations indicate destructiveHint=true (write operation), but the description adds substantial workflow context: provider review process, compounding at 503A pharmacy, Stripe ACP payment processing, and specific return values (order ID, review time, delivery window). No contradictions with annotations.

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

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

Appropriately detailed for a complex healthcare transaction. Information is front-loaded with purpose and prerequisites, followed by parameters, workflow steps, and returns. No redundant phrases, though information density is high.

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?

Comprehensive coverage for a complex 6-parameter transactional tool with nested objects. Addresses prerequisites (intake/consent), business logic (provider approval), fulfillment (pharmacy/shipping), payment method, and output values despite the existence of an output schema.

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

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

Schema coverage is 100%, establishing a baseline of 3. The description adds valuable semantic grouping by listing required fields upfront and linking the intake_id prerequisite to the business logic ('completed intake questionnaire'). It also reinforces the authentication requirement contextually.

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

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

The description clearly states the specific action (Create) and resource (prescription medication order), distinguishing it from sibling tools like order.status or order.upload which manage existing orders. It specifies this is for 'new' orders and contextualizes it within the healthcare workflow.

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

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

Explicitly states prerequisites ('patient must have completed intake questionnaire and consent before ordering'), providing clear conditions for invocation. It also notes authentication requirements. Does not explicitly name alternative tools for failed prerequisites, but provides strong guardrails on when the tool is valid to 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?

Beyond readOnlyHint=true, description adds valuable context: specific document examples (photo ID, selfie), return data details (upload status, accepted formats), and explicit authentication requirement.

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 well-structured sentences with zero waste: purpose front-loaded, return values specified, and auth constraint stated. 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?

Appropriately complete for a 2-parameter read operation with output schema. Covers auth requirement (critical for bearer_token) and exemplifies return content without redundantly documenting the output schema 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?

Schema coverage is 100% with complete descriptions for both order_id and bearer_token. Tool description mentions 'Requires authentication' reinforcing bearer_token's purpose but does not add syntax or format details beyond 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 uses specific verb 'Get' with resource 'list of documents' and clearly distinguishes from sibling 'order.upload' by specifying this retrieves requirements rather than performing uploads.

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 implied usage context ('documents a patient needs to upload') suggesting workflow sequence, but lacks explicit guidance on when to use this vs order.upload or prerequisites 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?

Annotions declare readOnlyHint=true, confirming safety. Description adds valuable behavioral context: enumerates specific status values (pending_review through delivered), discloses inclusion of tracking/delivery estimate data, and states authentication requirement. Does not contradict 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?

Three information-dense sentences: purpose, return specification (with enum), and auth requirement. No filler words. Perfect front-loading with verb-first structure.

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?

Excellent completeness given output schema exists. Description enumerates status values and return contents (tracking, estimates) which helps LLM interpret responses. Mentions auth requirement. Only minor gap: doesn't explicitly contrast with sibling status tools (e.g., checkout.status).

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

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

Schema description coverage is 100%, with both order_id and bearer_token fully documented in the input schema. Description doesn't add parameter semantics beyond schema, but doesn't need to given complete coverage. Baseline score 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?

Clear specific verb ('Get') + resource ('medication order status') + scope. Explicitly distinguishes from sibling mutation tools (order.create, order.upload) by stating this retrieves status, and from other status tools (checkout.status, intake.status) by specifying 'medication 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?

Implies temporal workflow via schema reference ('Order ID from doctormcp_create_order'), suggesting use after order creation. However, lacks explicit when-to-use guidance versus alternatives like order.documents, and doesn't state prerequisites (e.g., valid order_id required) in the description text.

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 indicate mutability and idempotency), the description adds critical behavioral context: required authentication, base64 encoding requirement, accepted file formats (PDF, JPEG, PNG), and size constraints (10MB). It does not clarify the destructive nature of the operation (e.g., whether uploads overwrite existing documents).

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, followed by specific technical constraints in a logical progression. Each sentence adds distinct value (purpose → encoding → formats → size → auth). Slightly list-like but efficient with no redundant language.

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

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

Given the presence of an output schema and 100% input schema coverage, the description appropriately focuses on operational constraints (formats, auth, size) rather than return values. It provides sufficient context for an upload operation, though explicit mention of idempotent behavior would further enhance 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?

With 100% schema coverage, the baseline is 3. The description adds value by specifying concrete format constraints and document type examples ('photo ID and selfie') that complement the schema's technical descriptions, helping agents understand valid inputs beyond the structural schema 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 clearly states the specific action (upload), resource (verification document), and context (medication order). It distinguishes from siblings by specifying 'verification document' versus general document management, and clarifies acceptable document types (photo ID and selfie).

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

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

The description establishes the functional context (uploading for medication orders) but lacks explicit guidance on when to use this versus order.documents, or prerequisites such as requiring an existing order from order.create. Usage is implied but not explicitly contrasted with 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 declare readOnlyHint=true; description adds crucial authentication context ('Requires authentication') and previews return value structure (medication, dosage, weight progress). No contradictions with annotations. Could improve by noting data sensitivity or caching behavior, but adequately covers auth needs.

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

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

Two-sentence structure with zero waste. First sentence front-loads the core purpose with comprehensive colon-delimited list of return fields. Second sentence states authentication requirement. Every word earns its place; no redundant 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?

Excellent completeness for a complex medical data tool. Despite output schema existing (which reduces description burden), description proactively enumerates expected data fields (provider notes, titration schedule, etc.), giving agents clear expectations of return richness. Covers authentication prerequisite.

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 bearer_token adequately described as 'Authentication token for the patient session'. Description mentions 'Requires authentication' which loosely contextualizes the bearer_token parameter but adds no additional syntax, format, or usage details beyond the schema. Baseline 3 appropriate given schema completeness.

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 uses specific verb 'Get' with clear resource 'care plan' and distinguishes from action-oriented siblings (portal.refill, portal.log_side_effects) by emphasizing comprehensive data retrieval. Lists specific data points (titration schedule, provider notes, weight progress) that clearly differentiate it from narrower tools like medications.list.

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

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

Provides clear context about scope (comprehensive care plan vs. simple medication lookup) which helps select over medications.details or medications.list. However, lacks explicit 'when not to use' guidance or named alternatives for specific use cases like 'use medications.availability to check stock levels'.

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 destructiveHint=true annotation, the description adds critical behavioral context: severe cases trigger auto-flagging for provider review and the tool 'returns urgent guidance'—explaining the non-idempotent workflow and response semantics. It also surfaces the authentication requirement, aligning with the bearer_token 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?

Three efficient sentences with zero redundancy. The description front-loads the core action, tucks the conditional severity logic in the middle, and ends with the auth requirement. Each sentence earns its place by conveying distinct information not found in structured fields.

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 (not shown but indicated), the description appropriately hints at return behavior ('returns urgent guidance') without duplicating the output contract. It covers authentication needs, severity escalation logic, and the medical domain context sufficiently for a patient-facing portal 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?

With 100% schema description coverage, the schema already documents all four parameters (patient_id, effects, severity, bearer_token) including examples. The description mentions severity specifically, but adds no semantic depth (format constraints, array item limits) beyond what the structured schema provides. 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 opens with the specific transitive verb 'Log' and clear resource 'side effects', immediately establishing the write operation. It effectively distinguishes from siblings like portal.log_weight (metrics), portal.message (communication), and portal.refill (medication orders) by focusing on adverse event reporting.

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 implied usage guidance through the severity conditional ('If severity is severe...'), alerting agents to the escalated workflow. However, it lacks explicit guidance on when to prefer this over portal.support (general help) or provider.questions (clinical Q&A), or when logging is inappropriate.

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

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

The description adds valuable context beyond annotations by specifying authentication requirements and date format (ISO 8601), though it does not elaborate on the destructive nature implied by destructiveHint=true (e.g., whether entries are permanent or overwrite existing data).

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 consists of two efficient sentences with no waste: the first establishes purpose and context, while the second lists requirements, making it well-structured and appropriately sized.

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 exempts describing return values), 100% parameter coverage, and clear annotations, the description provides sufficient context for invocation, though it could clarify the permanence implied by destructiveHint.

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

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

With 100% schema description coverage, the schema already documents all parameters clearly. The description confirms required fields but adds minimal semantic meaning beyond what the schema provides, meeting the baseline expectation.

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

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

The description clearly states the specific action (log), resource (patient's weight), and purpose (tracking progress on treatment plan), effectively distinguishing it from siblings like portal.log_side_effects or 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 implied usage context by referencing 'treatment plan' tracking, but lacks explicit guidance on when to use this versus sibling tools like portal.log_side_effects or prerequisites for invocation.

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 confirm destructive (write) operation. Description adds valuable behavioral context beyond annotations: specifies return values ('sent confirmation and estimated response time'), urgency flagging logic, and side effects (priority queue placement). Also clarifies the authentication requirement which complements the bearer_token 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?

Four efficient sentences with logical ordering: action/return value first, urgency logic second, prerequisite (auth) last. No tautological filler. 'Requires authentication' could potentially be inferred from the bearer_token parameter, but explicit mention is acceptable given the parameter has an empty default.

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?

Comprehensive for a messaging tool despite missing output schema in the provided context (context signals indicate output schema exists). Covers the critical patient-facing concerns: confirmation of delivery, response time expectations, and priority escalation for urgent medical situations. Auth requirements are explicitly stated.

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

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

Schema coverage is 100% so baseline is 3. Description adds meaningful semantic context to the 'message' parameter by documenting urgency keywords that trigger priority handling, which is not evident from the schema description ('Message text to send'). Also clarifies that authentication is required, reinforcing the 'bearer_token' purpose despite its empty default.

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

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

Clear verb ('Send') and resource ('message to the patient's healthcare provider'). The urgency keyword flagging provides specific behavioral detail that distinguishes this from generic messaging tools like portal.support. However, it does not explicitly differentiate from sibling 'provider.questions', which also appears to involve provider communication.

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 implied usage guidance through the urgent keywords list ('emergency', 'chest pain', 'difficulty breathing'), signaling when priority handling occurs. Lacks explicit when-not-to-use guidance or named alternatives to distinguish from 'provider.questions' or 'portal.support'.

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?

Discloses review timeline (24-48 hours) and provider review process not found in annotations. Aligns with destructiveHint=true ('Creates a refill order'). Emphasizes authentication requirement beyond what parameter defaults suggest. Could mention failure modes (e.g., no active prescriptions).

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 well-structured sentences: purpose, behavioral result/timeline, and authentication requirement. Front-loaded with clear intent. No redundant or wasted text relative to the tool's complexity.

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?

Appropriate for a tool with output schema and annotations. Covers creation workflow and review timeline. Minor gap in not describing validation errors (e.g., missing prescriptions) or idempotency warnings despite idempotentHint=false.

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 patient_id and bearer_token fully documented. Description adds minimal semantic value beyond schema—mentions 'patient' implicitly and emphasizes 'Requires authentication', which slightly reinforces the bearer_token purpose. Baseline 3 appropriate for high-coverage 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?

Clear specific verb 'Request' with resource 'medication refill' and scope 'for the patient's current prescription'. Effectively distinguishes from siblings like order.create (new orders) and medications.list (read-only viewing) by specifying this is for existing prescription refills.

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

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

States applicable scenario (patient's current prescription) but does not explicitly name alternatives like order.create for new prescriptions or clarify prerequisites such as having an active prescription. Usage is implied rather than guided.

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

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

Annotations indicate write/destructive operations; the description adds valuable context by specifying exact return values (ticket ID and estimated response time) and authentication requirements. It does not explain the destructive nature (irreversibility) of ticket creation, but does not contradict 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 tightly constructed sentences covering purpose, output, and requirements. No tautology or repetition of the tool name. Information is front-loaded with the primary action, followed by valuable consequence 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?

Adequate for a ticket creation tool with an output schema present. The description summarizes return values and auth needs. While it could explain the destructiveHint (irreversible creation) or side effects (notifications triggered), the core information is sufficiently covered.

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% property description coverage. The description implies the purpose of subject/message ('question or issue') but does not add semantic constraints, validation rules, or format details beyond what the structured schema already provides.

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

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

The description clearly states the tool creates a support ticket for customer issues, specifying outputs (ticket ID, response time). It distinguishes from clinical siblings (portal.message, provider.*) by specifying 'customer support,' though explicit contrast with messaging alternatives would strengthen it further.

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?

Lacks explicit when-to-use guidance or named alternatives (e.g., when to use vs portal.message for clinical vs administrative issues). The 'Requires authentication' statement identifies a prerequisite but does not constitute full usage 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?

With readOnlyHint=true in annotations, description wisely focuses on business context ('before making a prescribing decision') and conditional return behavior ('Returns the questions... or a message that no questions are pending'). Adds authentication requirement not covered by annotations.

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

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

Four sentences, zero waste: (1) Core purpose, (2) Business context/why, (3) Conditional return behavior, (4) Auth requirement. Front-loaded with actionable verb. 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?

Given 100% schema coverage, existing readOnlyHint annotation, and presence of output schema, description provides appropriate completeness. Covers auth needs, state-conditional returns, and prescribing workflow context. Minor gap: could reference sibling 'provider.respond' for the response workflow.

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% (both order_id and bearer_token fully described in schema). Description mentions 'specific order' and 'Requires authentication' which aligns with parameters but does not add significant semantic depth beyond the schema's existing documentation. Baseline 3 appropriate given 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?

Description uses specific verb 'Get' with clear resource 'follow-up questions from the healthcare provider' and scope 'for a specific order'. Effectively distinguishes from sibling 'provider.respond' (which submits answers) and 'intake.questions' (initial intake vs. provider follow-up).

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 contextual trigger: 'if the order status is 'needs_info''. Explains the alternative outcome ('no questions are pending'). Does not explicitly name 'provider.respond' as the follow-up tool for answering these questions, which would have made it a 5.

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

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

The description adds valuable context beyond annotations: it discloses the workflow (responses are sent for review), mentions the return value (confirmation and updated order status) despite the presence of an output schema, and explicitly states the authentication requirement. It aligns with annotations (destructiveHint=true matches 'updated order status').

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 consists of four efficient sentences that are front-loaded with the core purpose. Each sentence earns its place: defining the action, explaining the workflow, describing the return value, and stating the auth requirement. No redundancy or filler text.

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

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

Given the tool has an output schema and complete parameter documentation, the description provides adequate contextual completeness by covering authentication needs and workflow implications. It could be improved by mentioning idempotency or explicitly linking to the provider.questions workflow, but it sufficiently supports tool selection.

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

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

With 100% schema description coverage, the baseline score applies. The description implicitly references the 'answers' and 'order_id' parameters through phrases like 'Submit answers' and 'for a specific order,' but does not add significant semantic detail beyond what the schema already provides for the bearer_token or the structure of answers.

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

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

The description clearly states the specific action (Submit answers), the resource (provider follow-up questions), and the scope (for a specific order). It effectively distinguishes from the sibling tool 'provider.questions' by emphasizing the submission/response action versus retrieval.

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?

While the description implies this tool is for responding to follow-up questions, it lacks explicit guidance on when to use it versus alternatives, such as referencing the sibling 'provider.questions' to first retrieve questions, or stating prerequisites like having pending provider questions.

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