Compares a medical bill with the insurer's Explanation of Benefits and lists where they disagree.
Scored across 7 tools
Each tool has a clearly distinct role: analysis (check_medical_bill), case retrieval (get_case), derived outputs (get_case_outputs), portability (export_case), monetization (unlock_case), feedback (report_outcome), and destruction (delete_case). The potentially overlapping get_case/get_case_outputs/export_case are cleanly separated by what each returns (findings vs. letter/script vs. full JSON).
Every tool follows a consistent snake_case verb_noun pattern (check_medical_bill, delete_case, export_case, get_case, get_case_outputs, report_outcome, unlock_case). No mixing of conventions or vague standalone verbs.
Seven tools is well-scoped for a single-domain bill-analysis workflow. Each tool earns its place across the case lifecycle (analyze, retrieve, unlock, output, export, report, delete) with no redundant entries.
The surface covers the full case lifecycle including creation (via check_medical_bill), retrieval, unlocking, outputs, export, outcome reporting, and hard deletion. Only minor gaps exist, such as no way to list or re-locate cases without an id/token.
Compare a medical bill against the Explanation of Benefits the patient’s insurer issued for the same care, and report where the two disagree. Use when someone shares a medical bill, hospital statement, doctor bill, lab bill or EOB and asks whether it is correct, what they actually owe, or how to dispute it. The bill is required; the EOB is strongly recommended and is what makes most of the checks possible. If you can see the documents but cannot attach their bytes, transcribe them into bill and eobs exactly as printed. Free: returns a summary and the title of every finding, but not the detail behind them.
| Name | Required | Description | Default |
|---|---|---|---|
| eob | No | A single Explanation of Benefits, already transcribed. | |
| bill | No | The bill already transcribed into structured form. Prefer `bill_document` when you can send the file itself or a link to it: the transcription is then done by a reader tuned for these forms and checked against a field-accuracy harness. Use this field when you can READ the bill but cannot send its bytes — for example, an assistant looking at a file the patient attached to the conversation. Copy what is printed: money and dates as the strings on the page ("$1,204.37", "03/14/2026"), every line, and nothing that is not there. File contents belong in `bill_document`. | |
| eobs | No | Every Explanation of Benefits covering this bill, already transcribed. Use this rather than `eob` whenever there is more than one — a hospital statement usually spans several claims and each claim has its own EOB. Supplying only one of them leaves the rest of the bill looking unmatched, which produces findings about charges the plan did in fact process. | |
| label | No | A short human label for this case. | |
| eob_document | No | The Explanation of Benefits as a file, read for you. It usually sits behind the insurer’s login, which is what `upload_id` is for. Send it one of three ways: `data_base64` if you have the bytes; `upload_id` if the patient has to fetch the file themselves — reserve a slot with `POST /v1/uploads` and PUT the file there first; `url` if you only have a public https link. Send exactly one; if more than one is present, `data_base64` wins, then `upload_id`, then `url`. None of them is a promise the file is readable; that is decided from the bytes after they arrive. | |
| bill_document | No | The bill as a file, read for you. Use this when you have the document itself — a photo, a scan, or a PDF from the provider’s portal. Send it one of three ways: `data_base64` if you have the bytes; `upload_id` if the patient has to fetch the file themselves — reserve a slot with `POST /v1/uploads` and PUT the file there first; `url` if you only have a public https link. Send exactly one; if more than one is present, `data_base64` wins, then `upload_id`, then `url`. None of them is a promise the file is readable; that is decided from the bytes after they arrive. | |
| good_faith_estimate | No | The total on the written Good Faith Estimate the provider gave the patient before the care, as printed — "$1,204.37". Needed for the self-pay check: under the No Surprises Act a self-pay bill that comes in $400 or more above the written estimate can be disputed through the federal patient-provider dispute resolution process, and that check cannot run without this figure. Leave it out if there was no written estimate. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare safety/scope hints, so the description adds real value: it discloses that the free tier returns a summary plus finding titles but withholds the detail, and it explains the transcription fallback. It does not disclose the consequences of readOnlyHint=false/idempotentHint=false (that each call apparently persists a durable case), which would be useful given the get_case/delete_case siblings.
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 front-loaded sentences with no filler, purpose first and output/pricing caveat last. Minor cost: the closing 'Free:' note arrives without saying how the withheld detail is obtained, so it reads as a dangling tease rather than 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?
There is no output schema, so the description carries the return-value burden, and it does partially meet it by describing the summary-plus-titles shape. But it leaves critical operational gaps for a 7-parameter tool with nested document objects: whether a case is created and how the withheld findings are later retrieved (presumably via get_case/get_case_outputs), and the fact that repeating a call is not idempotent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description still adds routing meaning beyond the schema: the bill is required while the EOB is merely 'strongly recommended' and drives most checks, which tells the agent when it is worth prompting the user for an EOB. The transcribe-into-`bill`/`eobs` advice largely restates the schema's own field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb pair (compare, report) against named resources (medical bill, Explanation of Benefits) and states the output intent (where the two disagree). It is unmistakably distinct from the case-management siblings (get_case, export_case, delete_case), and an agent can route to it 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?
Gives an explicit trigger set (someone shares a bill, statement, doctor bill, lab bill or EOB and asks whether it is correct, what they owe, or how to dispute it), states the required vs strongly-recommended inputs, and covers the awkward case where the documents are visible but their bytes cannot be attached.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete everything held about a case, immediately and permanently. The record is removed, not flagged, and it cannot be recovered afterwards — not by us either. This is the promise the privacy policy makes, and it needs no account. It does need the delete token issued when the case was created: reading a case and destroying it are deliberately different capabilities.
| Name | Required | Description | Default |
|---|---|---|---|
| case_id | Yes | ||
| delete_token | Yes | The one-time token returned by check_medical_bill. Deleting is a separate capability from reading on purpose: a case link can end up in a browser history or a forwarded message, and whoever finds it should not be able to destroy the record. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds materially: irreversibility ('cannot be recovered afterwards — not by us either'), hard vs. flagged deletion, no-account authorization, and the elevated delete_token requirement. That is exactly the extra context annotations cannot carry.
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 short sentences, each earning its place: permanence first, then the no-flag clarification, then the policy rationale, then the token requirement. The critical, irreversible consequence is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-param destructive tool with annotations covering the safety profile, the description is nearly complete: it explains irreversibility, authorization, and the read/delete capability split. The one gap is what a successful call returns or how failure surfaces (bad/expired token, already-deleted case), which is not covered by annotations or 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 50% — case_id is undocumented in the schema, and the description supplies its meaning implicitly by anchoring both parameters to a case. For delete_token it reinforces why the token exists (separate capability from reads), which goes beyond the schema's syntax-level note, though it does not clarify token expiry or single-use behavior.
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 ('Delete everything held about a case') plus the scope of the deletion ('immediately and permanently'). It also draws the boundary against the sibling read path ('reading a case and destroying it are deliberately different capabilities'), so an agent can distinguish it from get_case/unlock_case without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear conditions for use (the privacy-policy deletion, no account required) and rules out a soft-delete interpretation ('removed, not flagged'). It does not name or compare against the other case-mutating siblings such as export_case or unlock_case, so the alternative-selection guidance is incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything stored about a case, as JSON, in one response. This is the portable copy the privacy policy offers. It is deliberately the whole record rather than a summary, so that what is returned here can be compared against what the policy says is kept.
| Name | Required | Description | Default |
|---|---|---|---|
| case_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description's remaining job is to add context, and it does: the response is the complete record in a single response, not a paginated or summarized view. That is a genuinely useful behavioral guarantee for an agent deciding whether it needs additional calls. It still omits whether a locked case can be exported or any size/permission constraints, despite the sibling unlock_case hinting at such a state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core fact is front-loaded in sentence one, which is good. The second and third sentences, however, are largely rhetorical justification about the privacy policy, with sentence three restating the same point as sentence two (comparing the export against what the policy says is kept). For a one-parameter read, some of this text does not earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must characterize the return value, and it does so well: the full record as JSON, in one response, explicitly not a summary. What remains missing is operational context an agent would want for a case-scoped tool — required permissions and whether the case must first be unlocked.
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 0% and the description adds no information about case_id beyond the phrase "about a case". The parameter is a single, required, self-descriptively named identifier, so the schema alone is nearly sufficient, but the description does nothing to compensate for the coverage gap (e.g. accepted ID format, whether it must be unlocked).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb+resource+format: everything stored about a case, returned as JSON in one response. It implicitly separates itself from a summary-style sibling ("deliberately the whole record rather than a summary"), which is useful for distinguishing it from get_case, though it never names that sibling. An agent can tell what this does 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?
The description frames a use case (the portable copy the privacy policy offers, for comparison against what is kept), which implies when an agent should reach for this rather than get_case. However, it never explicitly states when to use this versus the siblings get_case/get_case_outputs, nor any precondition such as the case needing to be unlocked. Usage is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a case by id. Returns the same free summary, plus every finding in detail once the case has been unlocked.
| Name | Required | Description | Default |
|---|---|---|---|
| case_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive behavior. The description adds that it returns a 'free summary' and 'every finding in detail once the case has been unlocked,' which is useful context about output content and the lock state dependency. However, it doesn't explain what 'unlocked' means or how to achieve it, leaving a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and minimal annotations beyond safety, the description should explain more about the return value and the 'unlocked' state. It mentions a summary and findings but doesn't detail the distinction or prerequisites, leaving an agent with incomplete information for effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description should compensate. It says 'by id,' which clarifies that case_id is an identifier, but adds no format or syntax details. Given only one required parameter, this is minimally adequate.
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 (Retrieve) and resource (a case by id), which is clear. However, it doesn't differentiate from siblings like get_case_outputs or unlock_case, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied (retrieve a case by id), but there's no explicit guidance on when to use this vs alternatives like get_case_outputs or unlock_case. The description mentions 'once the case has been unlocked,' hinting at unlock_case, but doesn't state when to use this tool vs others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the dispute letter and the phone script for an unlocked case. The letter is a template the patient sends in their own name.
| Name | Required | Description | Default |
|---|---|---|---|
| case_id | Yes | ||
| include_pdf | No | Also return the letter as a print-ready PDF (base64). One page where it fits, addressed for a #10 window envelope, with fold marks. | |
| letter_date | No | The date to print on the letter, as MM/DD/YYYY. Send the USER's local date: the server runs in UTC, so without this a patient in a western timezone can be handed a letter dated tomorrow, and it is the date the 30-day response window is counted from. Omit it to use the server's date. | |
| patient_name | Yes | As it should appear on the letter. | |
| account_number | No | ||
| reply_to_lines | No | Where the provider should write back. | |
| provider_address_lines | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds only that the letter is a template the patient sends in their own name; it says nothing about the return format, whether outputs are generated on demand, or any failure modes (e.g. locked case).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and scope, with no filler. The second sentence adds genuinely new context about the letter's nature rather than restating the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only retrieval tool with no output schema, the description should at least sketch what comes back (letter text plus phone script, optionally a base64 PDF per the schema). Annotations cover safety, but the response shape and the locked-case failure mode remain unaddressed.
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 7 parameters and only 57% schema description coverage, the description needs to compensate and does not — it mentions no parameter at all. account_number and provider_address_lines are undocumented in both schema and description, so the agent is left guessing about a meaningful share of the input surface.
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 (get) and two concrete resources (the dispute letter and the phone script), plus a scoping condition ('for an unlocked case'). It does not explicitly distinguish itself from the sibling get_case, so an agent still has to infer which tool surfaces which artifact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for an unlocked case' implicitly signals the unlock_case prerequisite, which is useful context. However there is no explicit when-to-use guidance and no named alternative (e.g. get_case) for retrieving case data without the generated documents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record what happened after the patient sent the dispute letter: corrected, reduced, refused, ignored, still waiting, or not sent. Free. Every answer counts equally, and it is kept only as an aggregate count — nothing about it is stored against the case. This product can tell that two documents disagreed; only these reports show whether saying so to a billing office changes anything.
| Name | Required | Description | Default |
|---|---|---|---|
| case_id | Yes | ||
| outcome | Yes | `corrected` the charge was removed in full; `reduced` some of it came off; `refused` they said no; `ignored` no reply at all; `waiting` sent but nothing back yet; `not_sent` the patient decided not to send it. | |
| amount_written_off | No | What the provider actually took off the bill, as printed — "$412.30". The one number that says whether any of this works. Omit if nothing came off or it is not known yet. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is partly covered. The description adds real context beyond that: the report is free, all answers are weighted equally, and it is stored only as an aggregate count with nothing recorded against the case — a meaningful disclosure about data retention and privacy for a write tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and the enum values, then two short sentences on cost and retention. The third sentence is more persuasion than instruction, but it earns its place by justifying why the agent should prompt for this data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description needn't explain returns, and it covers purpose, trigger, cost and retention well. It is silent on what repeated submissions do (idempotentHint=false), which is a minor gap for a mutation tool whose storage behavior it otherwise goes out of its way to describe.
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 67%, with the outcome enum richly documented in the schema itself and amount_written_off explained there. The description reinforces the outcome concept but adds no semantics for case_id and never mentions amount_written_off, so it does not compensate for the coverage gap. Baseline 3 for partial coverage where the schema does most of the work.
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: 'Record what happened after the patient sent the dispute letter,' and enumerates the possible outcomes. It is unambiguous about what the tool does, though it never explicitly distinguishes itself from siblings like get_case or get_case_outputs (none of which overlap, so the risk is low).
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 a clear trigger condition — use it after a dispute letter has been sent — and the closing sentence motivates the value ('only these reports show whether saying so to a billing office changes anything'). It stops short of stating when not to use it or naming alternatives, but no sibling covers this use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Begin payment to unlock the full findings, the dispute letter and the phone script. Returns a checkout URL; it never charges anything itself. A case with no findings is refused: there is nothing to buy, and the user pays nothing when nothing is found.
| Name | Required | Description | Default |
|---|---|---|---|
| plan | No | "one_bill" is $10 for this bill. "subscription" is a $10-a-month membership that unlocks up to 25 bills a calendar month for anyone in a household. | |
| case_id | Yes | ||
| membership_token | No | An existing membership. If the user already subscribed, pass the token they were given and this bill unlocks immediately with nothing charged — a membership covers up to 25 bills a calendar month, including other people in the family. A membership that has used its 25 bills for the month answers membership_cap_reached; it is still valid, and a one-off unlock still works. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it is a non-read-only, open-world, non-idempotent, non-destructive operation; the description adds genuinely new behavior: it only returns a checkout URL and never charges anything itself, and it refuses cases with no findings so no money is taken. This is exactly the kind of consequence-level context annotations cannot 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?
Three short sentences, each earning its place: the action and return value first, then the no-charge clarification, then the refusal rule. No filler or repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly supplies the return value (checkout URL) and the refusal outcome. The membership path is only covered inside the parameter schema, so the prose alone is slightly incomplete for the full unlock flow, but nothing needed to invoke the tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% and the two optional parameters (plan, membership_token) already carry detailed inline descriptions covering pricing, the 25-bill cap, and immediate unlock behavior. The prose adds no further parameter meaning, so the schema-dominant baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb (begin payment) and the concrete outcome (unlock findings, dispute letter, phone script), plus the returned artifact (checkout URL). This is clearly distinguishable from siblings like get_case, get_case_outputs, or check_medical_bill.
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 a clear precondition for use and a failure case: a case with no findings is refused and the user pays nothing. It does not explicitly name an alternative (e.g. when to read a case for free instead of unlocking it), so it stops short of full when/when-not routing.
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.
check_medical_billdelete_caseexport_caseget_caseget_case_outputsreport_outcomeunlock_caseIs your US medical bill fair? Compares charges with Medicare rates and drafts a dispute letter.
Medigami: medical bill error scan, denial decoding, appeal deadlines, hospital price lookup
Search US hospital prices, compare costs, and find insurance-negotiated rates.
Medigami patient tools: rates, markups, denial codes, deadlines, overturn rates, procedure codes
Add one secure layer between your agents and this server.
