Aspire Insurance MCP connects any MCP-compatible assistant or agent to real-time, multi-carrier quotes, carrier eligibility questionnaires and consent-backed application submission.
Scored across 4 tools
Each tool targets a distinct step in a linear pipeline: resolve_zip_counties (location), quote_carriers (pricing), get_eligibility_questionnaires (knockout screening), and submit_enrollment (write). Their purposes do not overlap, so an agent can select unambiguously. The heavy cross-referencing in descriptions reinforces ordering rather than creating confusion.
All four names use the same snake_case verb_noun convention: resolve_zip_counties, quote_carriers, get_eligibility_questionnaires, submit_enrollment. The verb styles (resolve/quote/get/submit) match each tool's action clearly. No style mixing or vague names.
Four tools is on the lean side but each maps to an essential stage of the quote-to-enroll workflow. Nothing appears redundant, though the surface is minimal enough that it could feel thin if more read-only operations were expected. Reasonable for a narrow, high-stakes domain.
The core lifecycle is covered: resolve location, quote, screen eligibility, and file enrollment, including retry/idempotency guidance for submission. Minor gaps remain, such as no standalone plan-detail retrieval beyond compact summaries or an explicit submission-status check, but agents can work around these via the returned fields.
Fetches each carrier's eligibility questionnaire for the plans the applicant selected. Pass selectedPlans as {carrier, planId} from quote_carriers, with the SAME applicants (primary, spouse, dependents), location, household and effectiveDate used for the quote. UHC and ONESHARE have no questionnaires and are simply absent from the result (not an error); carriers with no questions are also absent. An empty categories list with a message means nothing to ask or a rejected selection. A question with expectedAnswer is a knockout: any other answer means the carrier will decline, so do not enroll in that carrier's plans. Failed carriers appear in errors[] (TIMEOUT/CIRCUIT_OPEN/UNAVAILABLE retryable; CARRIER_ERROR not). Show the user questionTextPlain when present (questionText may contain HTML), but send questionText and answerText back VERBATIM in submit_enrollment's answers, with questionsId. PLAN_NOT_FOUND means the plan is no longer offered for these details: quote again.
| Name | Required | Description | Default |
|---|---|---|---|
| spouse | No | ||
| primary | Yes | ||
| location | Yes | ||
| household | No | ||
| dependents | No | ||
| effectiveDate | No | Coverage start date YYYY-MM-DD. Omit for each carrier's default; only some carriers honor it, others silently ignore it. | |
| selectedPlans | Yes | The plans the applicant chose, as {carrier, planId} exactly as returned by quote_carriers. | |
| childOnlyPlans | No | Same value as the quote, if one was sent. | |
| subsidyEligible | No | Same value as the quote, if one was sent. Ancillary carriers ignore it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so richly: absent carriers are not an error, empty categories signal nothing-to-ask-or-rejected, expectedAnswer is a knockout, and errors[] entries carry TIMEOUT/CIRCUIT_OPEN/UNAVAILABLE (retryable) vs CARRIER_ERROR (not). This is far beyond what any structured field discloses.
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?
Front-loaded with the purpose, then dense but purposeful behavioral detail. Sentences are packed and use semicolons heavily, making it a wall of text, but every clause adds actionable information (verbatim answers, HTML handling, error taxonomy).
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 9-param, nested-object tool with no annotations or output schema, the description covers input sourcing, downstream handoff to submit_enrollment (verbatim questionText/answerText with questionsId), error handling, and re-quote conditions. Nothing needed to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 44% across 9 params, and the description compensates notably: it pins selectedPlans to quote_carriers output and requires the same primary/spouse/dependents/location/household/effectiveDate as the quote. It adds real meaning for the most consequential params, though it doesn't address the remaining undocumented fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetches each carrier's eligibility questionnaire') and scopes it to 'the plans the applicant selected'. This clearly distinguishes it from quote_carriers and submit_enrollment, so an agent can route without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on how to call it (pass selectedPlans as {carrier, planId} from quote_carriers, with the SAME applicants/location/household/effectiveDate used for the quote) plus when-not semantics (UHC/ONESHARE absent, PLAN_NOT_FOUND means re-quote). It names the upstream sibling and the prerequisite consistency condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fans out concurrently to granted carriers for quotes. Requires location (fipsCode, zipCode, state, county = countyName) from resolve_zip_counties and primary applicant (gender, dateOfBirth). Returns carriers[] with compact plan summaries (planId, planName, premium, fees, deductible, key benefits); per-carrier failures are in errors[] (TIMEOUT/CIRCUIT_OPEN/UNAVAILABLE are retryable; CARRIER_ERROR is not). Partial results are normal — do not treat a non-empty errors[] as failure. questionsRequired=true means get_eligibility_questionnaires must be called before enrolling in that carrier's plans. carriers/categories narrow the request; naming one you are not granted fails the whole request (403) — then retry without that filter. Use maxPlansPerCarrier to see only the cheapest few per carrier. To use a plan later, pass {carrier, planId} in selectedPlans, together with the SAME applicants, location, household and effectiveDate used here.
| Name | Required | Description | Default |
|---|---|---|---|
| spouse | No | ||
| primary | Yes | ||
| carriers | No | Omit to quote every granted carrier | |
| location | Yes | ||
| household | No | ||
| categories | No | Omit to get every granted category | |
| dependents | No | ||
| contactInfo | No | ||
| effectiveDate | No | Coverage start date YYYY-MM-DD. Omit for each carrier's default; only some carriers honor it, others silently ignore it. | |
| childOnlyPlans | No | Same value as the quote, if one was sent. | |
| subsidyEligible | No | Same value as the quote, if one was sent. Ancillary carriers ignore it. | |
| maxPlansPerCarrier | No | Show only this many plans per carrier, cheapest first. Omit to see all. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers: concurrent fan-out behavior, partial-result semantics, per-carrier error codes with retryability classification (TIMEOUT/CIRCUIT_OPEN/UNAVAILABLE retryable, CARRIER_ERROR not), the 403-on-ungranted-filter failure mode, and the fact that some carriers silently ignore effectiveDate. This is unusually rich behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core purpose and prerequisites, and every sentence carries operational weight rather than filler. It is a dense single block, though, and would scan faster as discrete assertions, especially the error-code taxonomy.
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 12-param, nested, no-output-schema tool, the description covers what the description should: required inputs and their provenance, return shape (carriers[] plan summaries plus errors[]), and the cross-tool handoff needed to actually enroll. Nothing critical to calling it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%, so the description must compensate, and it does for the high-value params: location fields sourced from resolve_zip_counties, carriers/categories as narrowing filters, and maxPlansPerCarrier as 'cheapest few first'. It also documents the selectedPlans handoff contract (same applicants/location/household/effectiveDate), though several nested fields remain undocumented in both places.
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?
Opens with a specific verb+resource+mechanism ('Fans out concurrently to granted carriers for quotes'), immediately distinguishing it from the sibling enrollment/eligibility/location tools. An agent knows exactly what this produces (carrier quote results) before opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states prerequisites (location from resolve_zip_counties, primary applicant) and routes to a sibling when questionsRequired=true via get_eligibility_questionnaires. It also gives operational guidance — do not treat non-empty errors[] as failure, and retry without a filter on 403 — which is exactly the when/when-not detail most definitions lack.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolves a 5-digit ZIP to one or more {fipsCode, zipCode, countyName, state} rows (returned as counties, with hasMultipleCounties). Call this FIRST before quoting. Most ZIPs return one county; a ZIP straddling a county line returns several and the applicant must choose, because premiums differ by county. Pass the chosen row on every later request as location {fipsCode, zipCode, state, county: countyName}.
| Name | Required | Description | Default |
|---|---|---|---|
| zipCode | Yes | 5-digit US ZIP code (e.g., '64063') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose real behavior: one ZIP can map to several counties, the choice affects premium, and the resolved row must be propagated on every later request. It omits failure modes (unknown/non-US ZIP, invalid format handling) and whether results are cached or authoritative, so it stops short of full disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with the verb and return shape, then sequencing, then the multi-county caveat, then the handoff contract. Each sentence earns its place; the multi-county sentence is slightly long but carries the key decision logic.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must explain return values and it does (counties array, hasMultipleCounties), alongside ordering and the downstream location contract. An agent has everything needed to call it and use the result 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?
Only one parameter and the schema already documents it completely (pattern ^\d{5}$, example '64063'), so the baseline is 3. The description confirms '5-digit ZIP' and adds downstream usage context for the resolved values, but adds no new syntax or edge-case meaning for the input itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Resolves a 5-digit ZIP') and enumerates the exact returned row shape (fipsCode, zipCode, countyName, state) plus the sibling `counties`/`hasMultipleCounties` wrapper. An agent can distinguish this lookup from quote_carriers and get_eligibility_questionnaires without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit sequencing ('Call this FIRST before quoting'), explains the ambiguous multi-county case and the requirement that the applicant choose because premiums differ by county, and prescribes the downstream handoff format. Nothing about when or how to invoke it is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
HIGH-STAKES WRITE: Files applicants, contact, selected plans and questionnaire answers for MANUAL completion by an Apollo agent — this is not an enrollment confirmation. Pass selectedPlans as {carrier, planId} from quote_carriers, with the SAME applicants, location, household and effectiveDate used for the quote. Never enroll in a carrier's plans after a knockout answer (an answer other than expectedAnswer). Requires explicitUserConsent=true and consentStatement: the user's own message giving consent, quoted VERBATIM (never paraphrased or written by you). Only call after the user has explicitly agreed to submit. Success only when filed=true (status SYNCED/SKIPPED, or BACKUP_FILED: the API couldn't hand it off, so it went straight to an Apollo agent; don't resubmit). If filed=false (RECEIVED/SYNC_FAILED/upstream unavailable), call again with IDENTICAL arguments — the server derives the idempotency key from them, so an identical retry resumes the same submission and never files twice. PLAN_NOT_FOUND means a plan is no longer offered: quote again. Give the user the submissionId as their reference and relay nextStep verbatim; do not promise anything else.
| Name | Required | Description | Default |
|---|---|---|---|
| answers | No | Answers to get_eligibility_questionnaires, where a carrier has one. | |
| location | Yes | ||
| household | No | ||
| applicants | Yes | ||
| contactInfo | Yes | ||
| effectiveDate | Yes | Coverage start YYYY-MM-DD; today or later | |
| selectedPlans | Yes | The plans the applicant chose, as {carrier, planId} exactly as returned by quote_carriers. | |
| childOnlyPlans | No | Same value as the quote, if one was sent. | |
| subsidyEligible | No | Same value as the quote, if one was sent. Ancillary carriers ignore it. | |
| consentStatement | Yes | The user's message in which they consented to submit, quoted verbatim. Recorded as the consent audit trail. | |
| explicitUserConsent | Yes | Must be true; confirms the user explicitly approved submitting. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the entire burden and does so thoroughly: idempotency-key derivation from identical arguments, the filed=true/false state machine (SYNCED/SKIPPED/BACKUP_FILED vs RECEIVED/SYNC_FAILED/upstream unavailable), and an explicit 'never files twice' guarantee. It also discloses the consent-audit requirement and that filing is handed to a human agent, which no annotation could convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Long, but every clause carries operational weight — the severity flag is front-loaded, then ordering constraints, then success/failure semantics, then user-facing handoff. Nothing is decorative and no sentence repeats what the schema already states in structured form.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter nested-write tool with no annotations and no output schema, the description covers the safety profile, consent prerequisites, failure/retry behavior, and the user-facing follow-up (relay submissionId and nextStep verbatim). Nothing an agent needs to invoke it safely is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Beyond the 64% schema coverage, the description supplies cross-field semantics the schema cannot: selectedPlans must be {carrier, planId} taken from quote_carriers, and applicants/location/household/effectiveDate must match the quote exactly. It also defines the knockout-rule relationship between `answers` and expectedAnswer, and the verbatim-only constraint on consentStatement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (files applicants/contact/plans/answers for manual completion) and immediately disambiguates from the enrollment-confirmation meaning an agent might assume. It also names the upstream sibling (quote_carriers) whose output feeds the parameters, so it is clearly distinguishable from get_eligibility_questionnaires and resolve_zip_counties.
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 ('only call after the user has explicitly agreed to submit'), explicit when-not ('never enroll in a carrier's plans after a knockout answer'), and explicit alternatives on failure (PLAN_NOT_FOUND → quote again). Routing conditions are stated, not inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_eligibility_questionnairesquote_carriersresolve_zip_countiessubmit_enrollment
Add one secure layer between your agents and this server.