Is your US medical bill fair? Compares charges with Medicare rates and drafts a dispute letter.
Scored across 5 tools
Most tools target distinct actions, but check_price and search_services overlap on plain-language 'what does Medicare pay' queries, and check_price versus check_whole_bill can blur for single versus multiple line items. Descriptions provide guidance, but an agent still has to judge which rate-lookup tool fits.
All tool names use snake_case and follow a clear verb_noun or verb_noun_phrase pattern: check_price, check_whole_bill, draft_bill_letter, look_up_hospital, search_services. The convention is consistent and readable.
Five tools map cleanly to the core workflows of the domain: code/service lookup, single-charge comparison, whole-bill review, letter drafting, and hospital financial-assistance lookup. The set is well-scoped with no redundant or filler tools.
The surface covers the main bill-checking lifecycle: finding codes, comparing charges, reviewing itemized bills, drafting dispute letters, and checking hospital nonprofit status. Minor gaps remain, such as no dedicated dental-cost tool (only a 404 pointer) and no direct way to retrieve a hospital's full financial assistance policy details.
Compare a charge with Medicare's rate for one service. Use when someone asks whether a charge is high or what Medicare pays, for example "I was charged $450 for a 99213 office visit in Texas, is that too high?" or "what does Medicare pay for an MRI of the knee?". Pass the billing code if they have it, otherwise the service in plain words as q. Returns Medicare's 2026 rate for the state (or the city's own pricing area when city is given) in medicare_2026, the amount providers typically billed in 2024, and how many times the Medicare rate the charge is. For care in a hospital, hospital_facility_2026 gives Medicare's national rate for the hospital's own facility fee and comparison.compared_with says what the charge was set against. Dental work has no Medicare rate and returns 404 with a pointer to a free dental cost source
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | The service in plain words, used when there is no code, like "knee MRI" or "ER visit". | |
| city | No | City, for states where Medicare pays big cities differently, like Houston, Chicago, Miami or Los Angeles. Other places use the rest-of-state rate. | |
| code | No | Five-character CPT or HCPCS code from the bill, like 99213, 73721 or G0121. | |
| state | No | US state name or two-letter code, like Texas or TX. Med Bill Check is for US bills; a UK place gets a short answer pointing to UK sources. | |
| charged | No | The amount on the bill in US dollars, like 450. | |
| setting | No | office (clinic, office, imaging center) or facility (hospital or surgery center). Leave out to use the usual setting. | |
| billed_by | No | Whose bill the charge is on when the service was in a hospital: hospital (the hospital's own facility charge) or doctor (the doctor's or physician group's bill). Leave out if not known: the charge is then compared with both together. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it names the returned fields (medicare_2026, hospital_facility_2026, comparison.compared_with), explains the city-vs-rest-of-state pricing switch, and discloses the dental 404 with a redirect. That is substantive behavioral context for a tool with no 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?
Front-loaded with purpose and when-to-use before the longer return-value explanation. Dense and information-rich, though the final sentence runs long with several nested field names; nothing is wasted, but it is not maximally crisp.
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 no required parameters, the description carries the full burden of explaining what comes back and how the comparison is framed, and it does so thoroughly, including edge cases and non-US inputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter logic the schema lacks: pass code if available, otherwise plain words as q, and it explains that omitted billed_by compares against both hospital and doctor amounts.
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+resource+scope: 'Compare a charge with Medicare's rate for one service.' The 'one service' scope cleanly distinguishes it from the sibling check_whole_bill, and the title reinforces it.
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 triggering conditions with two realistic example queries ('I was charged $450 for a 99213...', 'what does Medicare pay for an MRI of the knee?'), plus fallback guidance for missing codes and non-Medicare cases (dental 404, UK bills). An agent knows when to reach for this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check several lines of an itemized bill at once. Use when someone reads out or pastes several lines from an itemized bill, for example "my ER bill has 99284 for $2,500, 85025 twice for $120 and 36415 three times, does anything look off?". Pass the lines as code, optional x and units, then the amount. Returns each line against Medicare's rate, totals, and questions_to_ask: repeated codes, units above Medicare's automated daily limit, the highest visit levels, hospital clinic facility fees and charges far above what providers typically bill. Lines of a hospital bill (any bill with an ER visit on it, or setting=facility) are compared with Medicare's hospital outpatient rate plus the doctor's part; each such line says compared_with.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | City, for big cities with their own Medicare rates. | |
| lines | Yes | Up to 15 bill lines separated by commas: code, then x and units if more than one, then the amount. Example: 99284:2500, 85025x2:120, 36415:45. | |
| state | No | US state name or two-letter code. | |
| setting | No | office or facility. Leave out if not known. | |
| billed_by | No | Whose bill the charge is on when the service was in a hospital: hospital (the hospital's own facility charge) or doctor (the doctor's or physician group's bill). Leave out if not known: the charge is then compared with both together. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond them: the Medicare-rate comparison, the totals output, the questions_to_ask categories flagged (repeated codes, unit limits, high visit levels, facility fees), and the facility-vs-doctor comparison rule with the 'compared_with' per-line field.
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 purpose and a concrete example, then output behavior. The final sentence about hospital bills is dense and long but carries real information; overall efficient with little waste.
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 explain return content and it does: each line vs Medicare's rate, totals, questions_to_ask, and the 'compared_with' field. Combined with the trigger example and format hint, an agent has everything needed to invoke and interpret it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3), but the description adds genuine meaning: the line format 'code, optional x and units, then the amount', and especially the billed_by semantics ('leave out if not known: the charge is then compared with both together'). This clarifies behavior the enum alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('check') and resource ('several lines of an itemized bill') with explicit scope ('at once', 'several lines'), which separates it from the singular sibling check_price. 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?
It gives clear usage context and a realistic triggering example ('my ER bill has 99284 for $2,500...'). It does not explicitly name an alternative like check_price or state when NOT to use this tool, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Draft a letter to a billing office for the user to send. Use for "help me dispute this bill", "write a letter asking for an itemized bill", "can I ask for a discount?" or "how do I apply for charity care?". Returns a letter as plain text with [brackets] for anything not given, tips, and the user's No Surprises Act and Good Faith Estimate rights with official CMS links. It never sends anything.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Billing code of the charge. With amount, a dispute letter adds Medicare's benchmark (for a hospital charge, the hospital outpatient rate as well as the doctor's part). | |
| date | No | Date of service. | |
| name | No | Patient or account holder name. | |
| type | Yes | itemized (ask for an itemized bill), dispute (ask for a charge to be reviewed), discount (prompt-pay or self-pay discount), or assistance (financial assistance or charity care). | |
| state | No | US state, used for the benchmark in a dispute letter. | |
| amount | No | Amount charged or balance due, in US dollars. | |
| reason | No | A sentence on what the user wants checked, for a dispute letter. | |
| account | No | Account or invoice number on the bill. | |
| insured | No | no if paying without insurance (self-pay), for a discount letter. | |
| service | No | The service in plain words. | |
| setting | No | office or facility (hospital or surgery center), for the benchmark in a dispute letter. ER visits and hospital clinic visits count as facility anyway. | |
| provider | No | Hospital, clinic or provider name. | |
| billed_by | No | Whose bill the charge is on when the service was in a hospital: hospital (the hospital's own facility charge) or doctor (the doctor's or physician group's bill). Leave out if not known: the charge is then compared with both together. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive, not openWorld), and the description adds meaningful behavior on top: it discloses the return format (plain text with [brackets] for missing fields, plus tips and CMS rights links) and confirms 'It never sends anything.' With no output schema, this return-shape disclosure is genuinely valuable rather than redundant.
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 purpose, then usage triggers, then output and safety. It is appropriately sized for a 13-parameter tool, though the opening sentence slightly duplicates the title and the quoted trigger phrases consume space that could carry additional routing 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?
For a 13-parameter, single-required-field tool with no output schema, the description covers purpose, triggers, output format, and the critical 'never sends' fact. It leaves the per-parameter nuances to the schema (which is fully documented), so it is complete enough, missing only explicit sibling disambiguation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 13 parameters, including the enums (type, insured, setting, billed_by) and conditional requirements. The description only restates the type categories via example phrases and adds no new syntax or format meaning, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Draft a letter to a billing office') plus the output the user receives. The purpose is distinct from the sibling tools (check_price, check_whole_bill, look_up_hospital, search_services), which compute or look things up rather than compose a letter.
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?
Maps four concrete user phrasings ('help me dispute this bill', 'write a letter asking for an itemized bill', 'ask for a discount', 'apply for charity care') directly onto the tool's letter types, giving strong when-to-use context. It does not, however, name alternative tools or state when NOT to use this one, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Whether a hospital is nonprofit, for financial assistance. Use for "is St. Luke's in Boise a nonprofit?" or "does this hospital have to offer charity care?". Returns how Medicare lists the hospital's ownership (nonprofit, government, for-profit), its city and main phone number, and what that means for financial assistance. Nonprofit hospitals must have a financial assistance policy.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | City, to pick between hospitals with the same name. | |
| name | Yes | Hospital name as on the bill, like St. Luke's Regional Medical Center. | |
| state | No | US state name or two-letter code. Recommended, since many hospitals share names. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, non-open-world behavior, so the safety profile is covered. The description adds genuinely useful non-annotation detail: it returns Medicare's ownership classification, city, main phone, and an interpretation for financial assistance, plus the rule that nonprofit hospitals must have a financial assistance policy. No auth/rate-limit/error behavior is mentioned, but with annotations present the bar is lower.
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 key framing ('Whether a hospital is nonprofit, for financial assistance') is front-loaded and the example queries follow immediately. The final sentence about nonprofit financial assistance policies is slightly redundant with the earlier 'what that means for financial assistance' clause, but it still earns its place as domain 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?
With no output schema, the description carries the return-value burden and does so by enumerating ownership type, city, phone, and the financial-assistance interpretation. Combined with the example queries and the 100%-covered input schema, an agent has everything needed to call and interpret this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter (name, city, state) is documented in the schema itself, including the note that state is recommended because names collide. The description adds no parameter-level guidance beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (hospital ownership status) and the practical question it answers, with concrete examples like 'is St. Luke's in Boise a nonprofit?'. The purpose is unmistakable, though it never explicitly contrasts itself with the billing-oriented siblings (check_price, check_whole_bill, draft_bill_letter).
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?
Two natural-language example questions establish exactly when to reach for this tool, which is strong contextual guidance. It stops short of stating exclusions or naming an alternative when the tool isn't appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find billing codes and Medicare rates by plain words. Use when someone describes a service but has no code, or asks what a code means, for example "what's the code for a colonoscopy?", "how much does Medicare pay for a chest x-ray in Ohio?" or "what is code 99214?". Returns up to eight matching codes with Medicare's typical allowed and billed amounts
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Plain words or a code, like "hernia repair" or 99214. | |
| state | No | US state name or two-letter code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavior beyond that: a result cap ('up to eight matching codes') and the fields returned ('Medicare's typical allowed and billed amounts'), which helps the agent set expectations about coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose followed by usage conditions and examples; every sentence serves selection or expectation-setting. The three inline examples are slightly verbose but each maps to a distinct usage mode, so the space is largely earned.
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 present, the description carries the return-value burden and does so: it states the result cap and the money fields returned. Combined with full param coverage and clear usage triggers, an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both q and state are already documented with examples. The description implicitly references state-scoped pricing ('in Ohio') but adds no syntax or format detail beyond what the schema already supplies, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('find billing codes and Medicare rates') and clarifies the input modality ('by plain words'). It cleanly separates the 'no code yet' and 'decode an existing code' cases, but does not differentiate itself from sibling check_price, which plausibly overlaps on pricing.
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 trigger conditions ('when someone describes a service but has no code, or asks what a code means') plus three concrete query examples, so an agent knows exactly when to reach for it. It stops short of naming alternatives like check_price or look_up_hospital for the exclusion case.
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_pricecheck_whole_billdraft_bill_letterlook_up_hospitalsearch_servicesMedigami: 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
Medicare rates, hospital quality, and dispute scenarios from six federal public-domain datasets.
Add one secure layer between your agents and this server.
