Find US, New Zealand and France doctors by condition, procedure or place, with sources. No sign-up.
Scored across 9 tools
Each tool has a distinct role: search_doctors returns candidates, get_doctor expands evidence, list_specialties/list_procedures/lookup_terms provide taxonomies or term mapping, and the country-specific tools (public_waitlist, search_gp_practices, hospital_procedure_volumes) target unique datasets. Overlap is minimal and descriptions clarify country scope and level (doctor vs hospital vs practice).
Mostly consistent snake_case with clear verb_noun names such as get_doctor, list_procedures, lookup_terms, and search_doctors. A few are noun phrases (about_database, hospital_procedure_volumes, public_waitlist), but the set remains readable and predictable overall.
Nine tools is well-scoped for a multi-country doctor-finding server, with each tool earning its place. The set avoids both thin coverage and excessive surface area.
Core workflows are covered: search, detail, specialty/procedure lookup, country database info, and auxiliary tools for NZ GP practices/public waitlists and French hospital volumes. Some country-specific asymmetries (e.g., no hospital-volume equivalent for US/NZ, no term lookup for non-US) are minor gaps agents can work around.
What one country's database holds: sources, dates, counts and coverage. Set country: United States (country=US), New Zealand (country=NZ), France (country=FR).
United States (country=US): Sources, build date, coverage counts, scoring method and caveats.
New Zealand (country=NZ): Sources, read dates, coverage counts and known gaps. Free.
France (country=FR): Sources, licences, read dates, coverage counts and known gaps. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| country | Yes | Where the person wants to be seen: United States (country=US), New Zealand (country=NZ), France (country=FR). Decide it before searching; if unclear, ask the person. Older clients that leave it out get United States. |
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). The description adds useful context on what each country's dataset yields and the notable 'Free' designation for NZ/FR, but says nothing about response shape, size, or failure behavior.
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 purpose is front-loaded, which is good, but the country enum mapping is repeated (once in the intro, again in the per-country lines, and a third time in the schema) and the per-country lines are near-duplicates of each other, diluting the value.
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 single-parameter, 100%-covered tool with no output schema, the description usefully outlines what the call returns (sources, dates, counts, coverage, gaps) and flags per-country availability, which is sufficient for an agent to decide to invoke 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 description coverage is 100% and the country enum is fully documented in the schema, so the baseline is 3. The description merely restates the same US/NZ/FR mapping already present in the schema, adding no new meaning such as default behavior or format expectations.
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 opening sentence names a specific resource and enumerates what the database metadata contains (sources, dates, counts, coverage), which is far more concrete than the tautological title 'About database'. It is clearly distinct from the search/list siblings, though it never explicitly says so.
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?
There is no statement of when to call this versus lookup_terms or the other metadata-adjacent siblings, and no exclusions or prerequisites. The per-country lines describe data content, not call conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evidence for doctors from search_doctors, by doctor_id. The id says the country (dr_ = United States, nz_ = New Zealand, fr_ = France), so no country parameter is needed; open one country's doctors per call. Parameters marked (US only), (NZ only) or (FR only) work for that country only.
United States (dr_ ids): Evidence for doctors from search_doctors: pass doctor_ids (up to 10 at once), or one doctor_id, or an npi. Each different doctor you open counts toward a daily limit for your connection (replies show daily_doctor_limit when it matters); opening a doctor again the same day is free. Open the doctors you are seriously considering, not every result. One reply holds about 2-3 doctors (1 with detail='full'); the others come back under not_returned_yet, already counted, so call again with those doctor_ids at no extra cost. Full evidence for one doctor; use it to compare or check doctors the person names (by npi) and before recommending. Every doctor: registered specialty, practice locations with phones (phone_source), medical school, hospitals, medical group, Medicare 2024 patients and patient mix, procedure volumes with national ranks, Medicare opt-out and federal exclusion-list checks, and from official files prescribing_2024 (Medicare Part D 2024 summary and top medicines), industry_payments (2024-2025), industry_research_as_principal_investigator and mips_2024 (detail='full' returns them as one official_extras record). Any doctor whose Part D 2024 claims lean clearly toward one condition's medicines has prescribing_signals_2024 (more such patients, not quality). Doctors whose hospital system's own website was read have hospital_websites (per site: focus as standard MeSH terms, languages, education, board certifications, new-patient status, office phones and addresses, page address and date read; at some hospital systems also insurance_listed, the page's insurance list grouped by insurer, a lead to confirm). detail='full' returns every collected field.
New Zealand (nz_ ids): Evidence for New Zealand doctors from search_doctors: pass doctor_ids (up to 10 at once) or one doctor_id. Each different doctor you open counts toward a daily limit for your connection (replies show daily_doctor_limit when it matters); opening a doctor again the same day is free. Open the doctors you are seriously considering, not every result. Each doctor: specialties, title, qualifications, focus areas and subspecialties they list, further training, languages, whether their services see children; every private and public service with clinic addresses, phone numbers and websites, procedures and conditions the service lists, fee categories and fee lines, ages, hours, how to get referred, and whether it says Southern Cross Affiliated Provider or nib First Choice (insurer_notes also says whether the doctor's own page says so); the Medical Council register entry (status, scope of practice, conditions, qualifications, practising certificate); experience (each vocational scope with the date it was granted and years since, first New Zealand registration, primary medical degree year, New Zealand honours with citation, University of Auckland title and hospital appointments, approximate count of papers with a New Zealand affiliation and a link to the list); hospital website links; and source links with read dates. For a GP, services include the practice's enrolment status and fee table. Profiles are not reproduced: give the person the Healthpoint link (sources.healthpoint) for the doctor's own words.
France (fr_ ids): Evidence for doctors in France from search_doctors: pass doctor_ids (up to 10 at once) or one doctor_id. Each different doctor you open counts toward a daily limit for your connection (replies show daily_doctor_limit when it matters); opening a doctor again the same day is free. Open the doctors you are seriously considering, not every result. Each doctor: RPPS number (check on annuaire.sante.fr), official specialties, official extra competences and university diplomas (DU/DIU), practice modes; every practice from the RPPS register and the Ameli directory with address, phone, setting, role, fee category (Secteur 1/2, OPTAM) and hospital FINESS number; from Maiia or hospital pages when the doctor has one: stated expertise, procedures offered, hospital department and role, qualifications, languages, consultation fees, online booking, video consultations, whether online booking is open to new patients; source pages with read dates; and industry_links: Transparence Santé declarations by drug and device companies (agreements, benefits, payments) by year, company and purpose, shown as declared (licence CC BY-NC-SA 4.0; not evidence of expertise or wrongdoing). Profile text is not reproduced: give the person the source page link for the doctor's own words.
| Name | Required | Description | Default |
|---|---|---|---|
| npi | No | (US only) 10-digit NPI, instead of doctor_id. | |
| detail | No | (US only) Default summary. | |
| doctor_id | No | One doctor_id from search_doctors (dr_... = United States, nz_... = New Zealand, fr_... = France). | |
| doctor_ids | No | Up to 10 doctor_ids from search_doctors, all from one country (dr_... = United States, nz_... = New Zealand, fr_... = France). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, and the description still adds substantial non-obvious traits: per-connection daily limits with daily_doctor_limit surfaced only when relevant, same-day re-opens being free, ~2-3 doctors per reply with overflow under not_returned_yet (already counted, so re-calling is free), and licensing/provenance caveats (CC BY-NC-SA; industry links 'not evidence of expertise or wrongdoing'). It also discloses the legal constraint that profile text is never reproduced.
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-loading is good: the id/country routing and the shared limit/overflow rules come first, then per-country detail under clear headers. However, the daily-limit and 'open the doctors you are seriously considering' paragraph is repeated almost verbatim in all three country sections, and the field inventories are exhaustive; a good chunk of the text could be hoisted into one shared block.
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 full burden and does so thoroughly, enumerating returned fields per country (specialty, locations, Medicare volumes, prescribing_2024, industry_payments, hospital_websites, RPPS/FINESS, insurer notes, source links with read dates). An agent knows what evidence to expect and which fields vary by detail='full'.
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 genuinely adds meaning beyond it: it explains that npi and detail are US-only (matching the schema's parenthetical hints but reinforcing them), that mixing countries in one doctor_ids call is disallowed, and that the id prefix itself encodes the country so no country parameter is needed. Partial credit 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 opening sentence states a specific verb and resource ('Evidence for doctors from search_doctors, by doctor_id') and immediately differentiates from the sibling search_doctors by framing this as the follow-up retrieval step. The country-prefix explanation (dr_/nz_/fr_) further pins down scope so an agent can tell exactly what it gets.
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 when and how to call: pass doctor_ids (up to 10), a single doctor_id, or an npi; all ids must be from one country. It also gives a judgment rule ('Open the doctors you are seriously considering, not every result') and a purpose statement ('use it to compare or check doctors the person names (by npi) and before recommending'), routing the agent correctly relative to search_doctors.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
France only. Which French hospitals and private clinics perform a procedure most, from Open CCAM (ATIH): number of acts per hospital site per year, 2021-2025, public and private. Counts hospital stays and day cases only (PMSI MCO); procedures done in a doctor's office or a hospital outpatient clinic are not counted, and a site with fewer than 11 stays for an act is not listed. procedure = English or French text ('cataract', 'knee replacement', 'prothèse genou', 'coloscopie', 'ablation fibrillation auriculaire') or CCAM codes; the reply lists the CCAM acts it added up, so check they fit the need (add-on codes and pathology are left out of text matches). For 'aneurysm' or 'stent' say where (brain, aorta, heart, carotid). place = city, postcode, Paris/Lyon/Marseille arrondissement, département number or a hospital FINESS number; without place it ranks all of France. Hospital-level only: it does not say which surgeon operates. Then use search_doctors with hospital_finess (salaried hospital doctors) or with the hospital's postcode and the specialty (self-employed surgeons at private clinics). Free.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Default latest (2025). | |
| codes | No | Exact CCAM codes to add up (use instead of procedure to narrow). | |
| limit | No | Default 10. | |
| place | No | City, postcode, arrondissement ('Paris 15'), département number (2A, 2B, 971-976), or hospital FINESS number. | |
| offset | No | For paging (at most 100). | |
| procedure | No | Procedure in English or French, or CCAM codes (e.g. 'BFGA427'; an 8th phase digit is dropped). |
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 adds substantial behavior: it counts PMSI MCO stays and day cases only, excludes office/outpatient-clinic procedures, suppresses sites with fewer than 11 stays, and reports which CCAM acts were summed. This is exactly the kind of operational detail 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?
Front-loaded with the hard constraint 'France only' and dense with useful detail, so most sentences earn their place. However it is a long, run-on paragraph mixing counting rules, input syntax, and tool routing, which slightly hurts scanability.
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: it notes the reply lists the CCAM acts that were summed and that counts reflect hospital stays/day cases. Combined with schema-documented paging (limit/offset/year), an agent has everything needed to call 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%, so baseline is 3, but the description adds real meaning: procedure accepts English or French free text or CCAM codes, examples are given, an 8th phase digit is dropped, add-on codes and pathology are excluded from text matches, and place accepts city/postcode/arrondissement/département/FINESS. It goes beyond the schema's terse 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 and resource: ranking French hospitals/clinics by how often they perform a given procedure, from Open CCAM (ATIH), per site per year. It scopes the source, years, and public/private coverage, making it clearly distinct from siblings like search_doctors and list_procedures.
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 bounds use ('France only') and routes the agent onward: 'Then use search_doctors with hospital_finess ... or with the hospital's postcode and the specialty.' It also clarifies that the tool is hospital-level only and does not identify surgeons, so the agent knows exactly when to stop and switch tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
United States only. The 81 signature procedure groups with Medicare 2024 volumes and national ranks (CPT codes, common names, national median per physician).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds genuinely useful context beyond them: the US-only scope, the fixed set of 81 rows (so no pagination or filtering concerns), and the 2024 data vintage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The hard constraint ('United States only') is front-loaded, then the payload is described compactly and precisely.
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 zero-parameter, fixed-enumeration read tool with no output schema, the description covers scope, cardinality, fields returned, and data vintage — enough to call it correctly. Only the absence of routing guidance to sibling list tools keeps it short of a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly does not invent parameter talk.
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?
Names a specific verb (List) and resource (procedure groups) and adds the payload content (CPT codes, common names, national median per physician). It is distinguishable from siblings like list_specialties by the resource, though it never explicitly contrasts itself with them.
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?
There is no statement of when to use this versus lookup_terms or list_specialties, and no prerequisites or exclusions beyond the geographic constraint. The agent must infer usage from the name and payload description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Specialty names one country's database uses. Set country: United States (country=US), New Zealand (country=NZ), France (country=FR).
United States (country=US): All specialties in the database with ids, families and physician counts.
New Zealand (country=NZ): Specialty names used in this database (Healthpoint categories) with doctor counts. Free.
France (country=FR): Specialty names in this database (official French names from RPPS and Ameli, and English labels) with doctor counts. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| country | Yes | Where the person wants to be seen: United States (country=US), New Zealand (country=NZ), France (country=FR). Decide it before searching; if unclear, ask the person. Older clients that leave it out get United States. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior. The description adds genuinely new context beyond that: return content varies materially by country (ids/families/physician counts for US vs category names/doctor counts for NZ), and the 'Free' tags signal that at least one path may carry a cost.
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 one-line purpose followed by a clean per-country breakdown; each line carries distinct information. There is mild redundancy in restating the country= codes that the schema enum already lists, but overall it is tight and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a single enum parameter, the description does the necessary work of explaining what each country returns and flagging the free/paid distinction. It is nearly complete for a lookup tool, with the only shortfall being no guidance on when to prefer it over sibling lookups.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the enum is already documented, so baseline is 3. The description nevertheless adds real value by spelling out what each enum value actually yields (US = ids/families/physician counts; NZ = Healthpoint categories; FR = RPPS/Ameli official names), which is output semantics tied to the parameter that the schema does not convey and no output schema exists to cover.
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 and resource ('Specialty names one country's database uses') and immediately specifies the three country scopes with what each returns. This is clearly a specialty-listing tool distinct in resource from siblings like list_procedures or lookup_terms, though it never names a sibling to differentiate against.
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 guidance on how to select the country parameter and notes NZ/FR are 'Free', implying a cost consideration for US. However, it never says when to reach for this tool versus list_procedures, lookup_terms, or about_database, so tool-level selection 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.
United States only. Check how a word is understood before searching: matching MeSH condition terms (with how many doctors' hospital-website profiles list each as a focus), procedure groups and specialties.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotent/non-destructive, so safety is covered. The description adds genuinely new context: a geographic restriction ('United States only') and the shape of the return (MeSH terms annotated with counts of doctors' profiles). No auth or rate-limit detail, but the added scope is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste, with the geographic constraint front-loaded before the purpose. The parenthetical about doctor profile counts is dense but earns its place by describing output.
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 single-parameter read-only lookup with no output schema, the description covers scope, intent and return shape adequately. Only the input format for 'text' remains slightly underspecified.
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% — the single 'text' parameter has no schema description — so the description must carry the burden. 'how a word is understood' implies text is a word/term to resolve, which partially compensates, but format expectations (e.g., single term vs. phrase, the 200-char limit) are left implicit.
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: checking how a word maps to MeSH condition terms, procedure groups and specialties, with an indication of what it returns (doctor profile counts). This clearly separates it from siblings like search_doctors or list_specialties, though it never names a sibling explicitly.
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 timing guidance — 'check how a word is understood before searching' — which tells the agent this is a pre-search disambiguation step. No explicit when-not or named alternative, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
New Zealand only. Public-system waiting lists from Health NZ by district and specialty (latest month and the same month a year earlier): people waiting for a first specialist assessment (FSA) and for planned treatment (surgery), and the share waiting over 120 days. Use it when the person is weighing public against private, or which district is faster. Give specialty and/or district. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| district | No | Health NZ district, e.g. 'Auckland', 'Canterbury', 'Capital and Coast'. Part of a name also matches (Canterbury includes South Canterbury); a city or region is read as its district (Wellington → Capital and Coast, Dunedin → Southern), shown in district_read_as. | |
| specialty | No | e.g. 'Orthopaedic', 'ENT', 'General Surgery', 'eye'. An exact name is matched first, then names containing each word, then the same without words like 'surgery' and with common plain words mapped (eye → Ophthalmology, heart surgery → Cardiothoracic, cardiologist → Cardiology, internal medicine → General Medicine), then part of a name; both of Health NZ's names for the same specialty are returned (e.g. Orthopaedics and Orthopaedic Surgery). |
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 non-obvious context beyond that: geographic restriction to NZ, that the data spans the latest month and the same month a year earlier, and that access is free.
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 most important constraint (New Zealand only) and a parenthetical that scopes the time range without a separate sentence. It is dense but every clause carries information; no 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?
With no output schema, the description correctly takes on the burden of describing returns: both waiting-list types, the 120-day share, and the two comparison months. Combined with the rich schema descriptions for district/specialty matching, an agent has what it needs; only response formatting/pagination is unstated.
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, but the description adds a meaningful usage note for a zero-required-parameter tool: "Give specialty and/or district" clarifies that either or both may be supplied and that at least one is expected in practice, which the schema alone does not state.
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 (public waiting lists from Health NZ) plus the exact metrics returned (FSA, planned treatment, share waiting over 120 days) and a scope constraint (New Zealand only). This clearly separates it from siblings like search_doctors and get_doctor, which cover a different domain.
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?
"Use it when the person is weighing public against private, or which district is faster" gives a concrete decision context, and "Give specialty and/or district" tells the agent how to invoke it. It stops short of naming alternatives to prefer in adjacent cases, but the when-to-use is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free short list of doctors for a need in one country; use it first whenever the person needs a doctor. Set country to where the person wants to be seen: United States (country=US), New Zealand (country=NZ), France (country=FR); if that is unclear, ask them before searching. Parameters marked (US only), (NZ only) or (FR only) work for that country only.
United States (country=US): Free short list of US doctors for a need; use it first whenever the person needs a US doctor: a specialist who focuses on a condition near a place (for a metro area use within_miles), who does the most of a procedure (sort='volume': Medicare 2024 counts with national and state ranks), or checking named doctors (name=...). Each result: doctor_id, name, degree, NPI, specialty (with its source) and the specialties their hospital website lists, city, state, distance_miles, warnings (federal exclusion list, Medicare opt-out, probably not a physician) and detail_has (what get_doctor adds for this doctor). With a condition or procedure, match_basis says whether the doctor has direct evidence for it (a listed focus, procedure volume or many such patients) or only a fitting specialty. Results are ranked by evidence of focus and experience for the need, not by quality or outcomes. Then call get_doctor with the doctor_ids you are considering (up to 10 at once) for the evidence. Up to 10 results per search and paging stops at 30: narrow the need or the place instead of paging. Conditions are matched to NLM MeSH terms (narrower terms and the general condition above it count too), common names such as 'afib' and clinical abbreviations such as 'CAD'; use English medical names when you can. Pass medicare_patient=true for anyone 65 or older or on Medicare. language= and accepting_new_patients=true filter by hospital-website pages, which most doctors do not have here; insurance cannot be filtered: if the person needs a specific plan, language or new-patient availability, find candidates on the web first when you can browse, then check them here by name. Read warnings.
New Zealand (country=NZ): Free short list of New Zealand doctors for a need; use it first whenever the person needs a doctor or specialist in New Zealand. Give at least one of need, specialty, place or name. need = a condition, procedure or focus in plain English (e.g. 'ACL reconstruction', 'endometriosis', 'skin cancer', 'cataract surgery'); it is matched against the focus areas doctors list first, then the procedures their services list, their specialty, and their own profile text (not shown here). specialty = a name from list_specialties, a word from one (e.g. 'orthopaedic', 'ENT') or a plain word (e.g. 'eye', 'skin', 'heart'); matched word by word (word endings may differ, e.g. 'cardiologist', 'paediatrician'; not fragments inside words), and the reply's specialty_read_as lists the specialty names used. place = a New Zealand city, suburb, or region or Health NZ district (e.g. 'Christchurch', 'North Shore', 'Hawke's Bay', 'Hutt Valley'); when a town search leaves out doctors listed only on the wider region's page or in its other towns, place_note says how many and which place to use instead. Each result: doctor_id, name, specialties, vocational scope, cities, sectors (private, public), match_basis (with a need: stated_focus, services_listed (the doctor's own or a small practice's service page), shared_service_listed (a hospital department or large group page they are linked to, so not necessarily done by this doctor), specialty, specialty_for_symptom (the need is a symptom few doctors list, and their specialty usually sees it; need_note says which specialties), profile_text or partial), place_match (with a place: city_or_address, city_in_region, address_contains or region_page_only), warnings (e.g. not practising on the Medical Council register), specialist_since (year first on the Medical Council vocational, i.e. specialist, register in New Zealand), recognition (New Zealand honours, University of Auckland title), listing (medical_council_register_only when the doctor has no clinic listing here), possibly_same_person_as (another entry with the same name that may be the same doctor) and detail_has (what get_doctor adds). General practitioners are left out unless specialty is general practice (e.g. 'GP') or a name is given; to find a GP clinic use search_gp_practices. Doctors only on the register are included when practising with a specialist scope (any status with a name). Results are ranked first by how directly the doctor's own listing matches the need (doctors who list all its words; then, when the need is a symptom such as back pain, doctors whose specialty usually sees it; then doctors who list some of the words; then words only in profile text), then by place_match (with a place); with experienced_first, longer as a specialist next. Doctors known only from the Medical Council register (no clinic listing) come after all others. Not ranked by quality or outcomes. Then call get_doctor with the doctor_ids you are considering. Up to 10 results per search and paging stops at 30: narrow the need or the place instead of paging.
France (country=FR): Free short list of doctors in France for a need; use it first whenever the person needs a doctor, specialist or GP in France. Give at least one of need, specialty, place, name or hospital_finess. need = condition, procedure or focus, in French or English (e.g. 'endométriose', 'prothèse genou', 'knee replacement', 'cataract'; common English words are also searched in French); matched against the expertise and procedures doctors state, their official competences and university diplomas, hospital departments and roles, and specialty. specialty = French or English (e.g. 'cardiologie', 'dermatology', 'pédiatre', 'ORL', 'GP', 'généraliste'). place = city ('Lyon', 'Paris' includes all arrondissements), postcode ('75015'), arrondissement ('Paris 15', 'Lyon 3e'), département number ('69', '2A') or a practice or hospital name; a text match on practice addresses, not a distance search. Each result: doctor_id, name, gender, specialties (French, as registered), specialties_en, places (up to 3 practices, the ones matching place first), fee_sectors (Ameli category: Secteur 1 = standard fees; Secteur 2 = may charge extra; Non conventionné = not contracted, little reimbursed), optam (agreed to limit extra fees), match_basis (with a need: stated_expertise, official_competence, hospital_department_or_training, several_fields, specialty, specialty_usually_treats, partial), register (rpps, ameli_only = only in the Assurance Maladie directory, website_only = not matched to the official registers), warnings (e.g. barred from practising) and detail_has (what get_doctor adds). With a need, results are ranked by how directly the doctor's own data matches it: all its words in the expertise or procedures the doctor states, then in official competences or university diplomas, then in hospital department, role or training, then spread over several fields, then in the specialty name; then, when the need is a condition few doctors list, doctors in the specialty that usually treats it (specialty_usually_treats); then doctors matching only some of the words. Without a need, doctors with more data (stated expertise, official competences, profile pages) come first, then in a fixed shuffled order. Not ranked by quality, outcomes, fees or industry links. Then call get_doctor with the doctor_ids you are considering. Up to 10 results per search and paging stops at 30: narrow the need or the place instead of paging.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | (US only) City of a practice location. Alone it matches only that exact city name (suburbs are separate cities); for a metro area add within_miles, e.g. city='Dallas', state='TX', within_miles=25. | |
| name | No | US: Part of the doctor's name. Name searches also return NPI records that are probably not physicians (nurse practitioners, physician assistants, etc.), marked with a WARNING; other searches leave them out. NZ: Doctor's name or part of it, to check a named doctor. FR: Doctor's name or part of it, to check a named doctor. | |
| need | No | NZ: Condition, procedure or focus, plain English. FR: Condition, procedure or focus, in French or English. | |
| sort | No | (US only) evidence (default), volume (best Medicare procedure rank first) or standing (named principal investigator on industry-sponsored research first). | |
| text | No | (US only) Free-text filter over specialty, medical school, hospitals, medical group and procedure groups, e.g. a hospital name. Insurance is not searchable (some hospital-website lists are shown in results, not filtered); for languages use language. | |
| child | No | (NZ only) True when the patient is a child: among doctors in the same place who match the need equally well, those in paediatrics or who list children in their focus come first, then those whose services say they see children; doctors whose services list only adult ages are left out. Most listings do not say, so those doctors stay in. | |
| limit | No | Default 10. | |
| place | No | NZ: New Zealand city, suburb, or region or Health NZ district (e.g. 'Waikato', 'Hawke's Bay', 'Capital and Coast'). FR: City, postcode, arrondissement ('Paris 15'), département number ('69', '2A') or a practice or hospital name. | |
| state | No | (US only) US state, 2-letter code (MA) or full name. With within_miles it only identifies the city (the radius can cross state lines) and is ignored with near_zip. | |
| gender | No | female or male. US: Doctor's gender (NPI registry). NZ: Only when the person asks. Gender is recorded for only a small share of doctors (when their Healthpoint page states it); doctors without it are left out and gender_note says how many. FR: Only when the person asks. From the register's civil title (Madame/Monsieur); recorded for almost all doctors. | |
| offset | No | US: For paging (at most 20, so 30 results in all: narrow the search instead of paging further). NZ: For paging (at most 20, so 30 results in all: narrow the search instead). FR: For paging (at most 20, so 30 results in all: narrow the search instead). | |
| sector | No | (NZ only) private = the doctor lists a private service; public = a public (Health NZ) service. Default any. | |
| country | Yes | Where the person wants to be seen: United States (country=US), New Zealand (country=NZ), France (country=FR). Decide it before searching; if unclear, ask the person. Older clients that leave it out get United States. | |
| patient | No | (US only) adult removes child-only specialties; child lists pediatric specialists and doctors listed on a children's hospital's own website (listed_on_childrens_hospital_website in results) first, unless there is evidence that they mainly treat adults. | |
| language | No | US: Language the doctor speaks other than English, e.g. 'Spanish', 'Mandarin', 'Vietnamese' (several: 'Spanish, Portuguese' = any of them). Keeps only doctors whose hospital website lists it (one site lists office staff's languages too); most doctors have no such page here, so if few results, also search the web. NZ: Language other than English the doctor, or a small clinic (3 doctors or fewer) they work in, lists, e.g. 'Mandarin', 'Hindi', 'Samoan'. FR: Language other than French, e.g. 'English', 'Arabic', 'anglais'. Only known for doctors with a Maiia or hospital profile (about 1,800 list one); many others speak it too. | |
| near_zip | No | (US only) One or more US ZIP codes, comma-separated. With within_miles: practices within that distance of these ZIPs. Without it: practices in the same 3-digit ZIP areas (one area can be only part of a big metro, e.g. Brooklyn 112 but not Manhattan 100-102). | |
| condition | No | (US only) Disease, symptom or problem, e.g. 'atrial fibrillation', 'knee osteoarthritis', 'breast cancer', 'migraine'. | |
| procedure | No | (US only) Procedure or surgery, e.g. 'knee replacement', 'TAVR', 'cataract surgery', 'Mohs surgery'. See list_procedures. | |
| specialty | No | US: Specialty id, name, title or family, e.g. 'cardiology', 'cardiologist', 'ENT', 'GI', 'OB/GYN', 'primary care', 'pediatric neurology', 'palliative care', 'orthopaedic-surgery'. See list_specialties. NZ: Specialty name, a word from one, or a plain word like 'eye' (see list_specialties). FR: Specialty in French or English, e.g. 'cardiologie', 'dermatology', 'ORL', 'GP' (see list_specialties). | |
| fee_sector | No | (FR only) Assurance Maladie fee category. secteur_1 = standard fees, no extra charges; secteur_1_or_optam = standard fees or agreed limits on extra fees; secteur_2 = may charge extra. Kept if ANY of the doctor's practices has it (it can differ by practice): check each practice in get_doctor. Most hospital-only doctors have no category. Default any. | |
| within_miles | No | (US only) Search radius in miles around city (give state too) or near_zip, e.g. 25 for a metro area, 5-10 in a dense city such as New York City, Chicago, San Francisco or Boston (25 there spans the whole metro); includes suburbs and can cross state lines. Each result then has distance_miles. | |
| online_booking | No | (FR only) True keeps doctors whose Maiia or hospital page shows online booking (Doctolib is not covered). | |
| hospital_finess | No | (FR only) Keep doctors whose register address is this hospital site (FINESS number from hospital_procedure_volumes): mostly salaried hospital doctors. | |
| medicare_patient | No | (US only) true for a person 65 or older or on Medicare: leaves out doctors on the CMS Medicare opt-out list (Medicare and Medicare Advantage plans will not pay them except for emergency or urgent care). Without it such doctors carry a WARNING in warnings. | |
| teleconsultation | No | (FR only) True keeps doctors offering video consultations on Maiia. | |
| experienced_first | No | (NZ only) True when the person wants an experienced or senior doctor: among doctors who match equally well, those longer on the New Zealand specialist (vocational) register come first. Time on the register is not quality, and doctors who trained overseas may have practised longer than it shows. | |
| accepting_new_patients | No | (US only) true keeps only doctors listed as accepting new patients by their hospital website (others are unknown, not 'no'; confirm when booking). | |
| southern_cross_affiliated | No | (NZ only) True keeps doctors whose own Healthpoint page or at least one of whose service pages says Southern Cross Affiliated Provider (cover still depends on the policy and often prior approval; confirm). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered, yet the description goes far beyond: ranking logic (evidence-of-focus, place_match, experienced_first), data-source caveats (hospital-website pages most doctors lack; register-only doctors ranked last), the 10-per-search / 30-total paging cap with an instruction to narrow rather than page, and explicit warning semantics (federal exclusion list, Medicare opt-out, not registered). 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?
The core routing sentence is front-loaded, and most of the length is dense, non-redundant country-specific detail. However, boilerplate is triplicated nearly verbatim — 'Free short list of doctors… use it first whenever the person needs a doctor', 'Then call get_doctor with the doctor_ids you are considering', and 'Up to 10 results per search and paging stops at 30' each appear three times. A single shared preamble plus three country blocks would deliver the same information in noticeably less 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?
For a 28-parameter, three-country tool with no output schema, the description supplies everything an agent needs: the result fields to expect per country, match_basis vocabularies, ranking order, warnings, paging limits, and cross-tool handoffs. Nothing material is missing for correct invocation, and there is no output schema whose return values would need separate explanation.
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 and the schema already carries most parameter meaning. The description still adds real value the schema does not: country must be decided before searching (with a default-to-US fallback), medicare_patient applies to anyone 65+, sort='volume' means Medicare 2024 counts, and which filters are exposed as parameters versus left to web search. It stops short of 5 because the per-country parameter narrative is largely a restatement at the tool level of what each schema property already says.
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 opening sentence gives a specific verb+resource+scope: a free short list of doctors for a need in one country, plus an explicit precedence rule ('use it first whenever the person needs a doctor'). It also distinguishes itself from siblings by naming get_doctor, search_gp_practices and list_specialties as separate steps. An agent can place this tool precisely without opening any 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 states when to use it (any doctor/specialist/GP need), when not to (GP clinics go to search_gp_practices), what to do when country is unclear ('ask them before searching'), and what to call next (get_doctor with up to 10 doctor_ids). Alternatives and exclusions are named explicitly for all three countries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
New Zealand only. Free list of New Zealand general practices (GP clinics), or urgent care clinics, near a place, from Healthpoint. Use it when the person needs a GP, wants to enrol with a practice, or needs urgent but not emergency care. Each practice: whether it says it is enrolling new patients (yes; restricted = only some people, e.g. family of patients or people living nearby; no; does not apply = urgent care that does not enrol; unknown = the page does not say), the practice's own enrolment note, its fee table (the first fee table on its page, usually fees for enrolled patients by age, without and with a Community Services Card; with age, the row for that age), addresses, phone numbers, website, online booking link, languages, hours, the doctors listed there (doctor_ids for get_doctor) and the date Healthpoint says the page was last updated. In New Zealand most people enrol with one general practice: visits cost less once enrolled, and a GP referral is the usual way to a public specialist. Give place or name. Practices are not doctors, so this does not count toward the daily doctor limit. Enrolment and fees change often: tell the person to phone the practice to confirm.
| Name | Required | Description | Default |
|---|---|---|---|
| age | No | The patient's age: each result then shows the fee row for that age. | |
| kind | No | gp = general practices (default; also nurse-led, online, student and rest-home practices, named so in each result's kind); urgent_care = accident and urgent medical care and after-hours clinics (no enrolment needed); any = both. | |
| name | No | Practice name or part of it, to check a named practice. | |
| limit | No | Default 10. | |
| place | No | New Zealand city, suburb or region (e.g. 'Papanui', 'Hamilton', 'North Shore', 'Canterbury'). | |
| offset | No | For paging (at most 40). | |
| language | No | Language other than English the practice lists, e.g. 'Mandarin', 'Samoan', 'te reo Maori'. | |
| enrolling | No | yes = only practices that say they are enrolling new patients; yes_or_restricted also keeps practices enrolling only some people (read enrolling_note). Default any (enrolling practices come first). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, non-destructive, idempotent), but the description adds real behavioral context beyond them: NZ-only, free, the daily doctor limit exclusion, and a data-freshness caveat ('Enrolment and fees change often: tell the person to phone the practice to confirm'). It does not describe paging/limit behavior in prose, so it stops short of full marks.
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 leading sentences are well front-loaded (NZ-only, free, when-to-use), but the long middle sentence enumerating every returned field reads as a dense run-on. With no output schema this detail is defensible, yet the structure is heavy and not easy to scan.
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 describe return fields — and it does so thoroughly (enrolment, fees, addresses, phones, hours, doctors, last-updated). Combined with the annotations' safety profile and the usage framing, an agent has enough to call it correctly; only paging/limit prose is thin.
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 a baseline of 3 applies; the description nonetheless adds meaning to the 'enrolling' enum by expanding restricted/no/does-not-apply/unknown, which the schema only partially covers. It also ties doctor_ids to get_doctor and explains the age-to-fee-row relationship.
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: 'Free list of New Zealand general practices (GP clinics), or urgent care clinics, near a place.' It explicitly disambiguates from the sibling search_doctors ('Practices are not doctors'), so an agent can distinguish it 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 clear trigger conditions: 'when the person needs a GP, wants to enrol with a practice, or needs urgent but not emergency care,' plus 'Give place or name.' It implies but never names the alternative tool to use for doctors, so the routing guidance is clear but not fully explicit.
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.
about_database2 fields changedInput schema / properties / country / descriptionPrevious value: -"Where the person wants to be seen: United States (country=US), New Zealand (country=NZ). Decide it before searching; if unclear, ask the person. Older clients that leave it out get United States."New value: +"Where the person wants to be seen: United States (country=US), New Zealand (country=NZ), France (country=FR). Decide it before searching; if unclear, ask the person. Older clients that leave it out get United States."Input schema / properties / country / enumPrevious value: -[
- "US",
- "NZ"
-]New value: +[
+ "US",
+ "NZ",
+ "FR"
+]get_doctor4 fields changedInput schema / properties / doctor_id / descriptionPrevious value: -"One doctor_id from search_doctors (dr_... = United States, nz_... = New Zealand)."New value: +"One doctor_id from search_doctors (dr_... = United States, nz_... = New Zealand, fr_... = France)."Input schema / properties / doctor_id / patternPrevious value: -"^(?:dr_[0-9a-z]{12}|nz_[0-9a-z]{12})$"New value: +"^(?:dr_[0-9a-z]{12}|nz_[0-9a-z]{12}|fr_[0-9a-z]{12})$"Input schema / properties / doctor_ids / descriptionPrevious value: -"Up to 10 doctor_ids from search_doctors, all from one country (dr_... = United States, nz_... = New Zealand)."New value: +"Up to 10 doctor_ids from search_doctors, all from one country (dr_... = United States, nz_... = New Zealand, fr_... = France)."Input schema / properties / doctor_ids / items / patternPrevious value: -"^(?:dr_[0-9a-z]{12}|nz_[0-9a-z]{12})$"New value: +"^(?:dr_[0-9a-z]{12}|nz_[0-9a-z]{12}|fr_[0-9a-z]{12})$"hospital_procedure_volumeslist_specialties2 fields changedInput schema / properties / country / descriptionPrevious value: -"Where the person wants to be seen: United States (country=US), New Zealand (country=NZ). Decide it before searching; if unclear, ask the person. Older clients that leave it out get United States."New value: +"Where the person wants to be seen: United States (country=US), New Zealand (country=NZ), France (country=FR). Decide it before searching; if unclear, ask the person. Older clients that leave it out get United States."Input schema / properties / country / enumPrevious value: -[
- "US",
- "NZ"
-]New value: +[
+ "US",
+ "NZ",
+ "FR"
+]search_doctors13 fields changedInput schema / properties / country / descriptionPrevious value: -"Where the person wants to be seen: United States (country=US), New Zealand (country=NZ). Decide it before searching; if unclear, ask the person. Older clients that leave it out get United States."New value: +"Where the person wants to be seen: United States (country=US), New Zealand (country=NZ), France (country=FR). Decide it before searching; if unclear, ask the person. Older clients that leave it out get United States."Input schema / properties / country / enumPrevious value: -[
- "US",
- "NZ"
-]New value: +[
+ "US",
+ "NZ",
+ "FR"
+]Input schema / properties / fee_sectorAdded value: +{
+ "description": "(FR only) Assurance Maladie fee category. secteur_1 = standard fees, no extra charges; secteur_1_or_optam = standard fees or agreed limits on extra fees; secteur_2 = may charge extra. Kept if ANY of the doctor's practices has it (it can differ by practice): check each practice in get_doctor. Most hospital-only doctors have no category. Default any.",
+ "enum": [
+ "any",
+ "secteur_1",
+ "secteur_1_or_optam",
+ "secteur_2"
+ ],
+ "type": "string"
+}Input schema / properties / gender / descriptionPrevious value: -"female or male. US: Doctor's gender (NPI registry). NZ: Only when the person asks. Gender is recorded for only a small share of doctors (when their Healthpoint page states it); doctors without it are left out and gender_note says how many."New value: +"female or male. US: Doctor's gender (NPI registry). NZ: Only when the person asks. Gender is recorded for only a small share of doctors (when their Healthpoint page states it); doctors without it are left out and gender_note says how many. FR: Only when the person asks. From the register's civil title (Madame/Monsieur); recorded for almost all doctors."Input schema / properties / hospital_finessAdded value: +{
+ "description": "(FR only) Keep doctors whose register address is this hospital site (FINESS number from hospital_procedure_volumes): mostly salaried hospital doctors.",
+ "maxLength": 200,
+ "type": "string"
+}Input schema / properties / language / descriptionPrevious value: -"US: Language the doctor speaks other than English, e.g. 'Spanish', 'Mandarin', 'Vietnamese' (several: 'Spanish, Portuguese' = any of them). Keeps only doctors whose hospital website lists it (one site lists office staff's languages too); most doctors have no such page here, so if few results, also search the web. NZ: Language other than English the doctor, or a small clinic (3 doctors or fewer) they work in, lists, e.g. 'Mandarin', 'Hindi', 'Samoan'."New value: +"US: Language the doctor speaks other than English, e.g. 'Spanish', 'Mandarin', 'Vietnamese' (several: 'Spanish, Portuguese' = any of them). Keeps only doctors whose hospital website lists it (one site lists office staff's languages too); most doctors have no such page here, so if few results, also search the web. NZ: Language other than English the doctor, or a small clinic (3 doctors or fewer) they work in, lists, e.g. 'Mandarin', 'Hindi', 'Samoan'. FR: Language other than French, e.g. 'English', 'Arabic', 'anglais'. Only known for doctors with a Maiia or hospital profile (about 1,800 list one); many others speak it too."Input schema / properties / name / descriptionPrevious value: -"US: Part of the doctor's name. Name searches also return NPI records that are probably not physicians (nurse practitioners, physician assistants, etc.), marked with a WARNING; other searches leave them out. NZ: Doctor's name or part of it, to check a named doctor."New value: +"US: Part of the doctor's name. Name searches also return NPI records that are probably not physicians (nurse practitioners, physician assistants, etc.), marked with a WARNING; other searches leave them out. NZ: Doctor's name or part of it, to check a named doctor. FR: Doctor's name or part of it, to check a named doctor."Input schema / properties / need / descriptionPrevious value: -"(NZ only) Condition, procedure or focus, plain English."New value: +"NZ: Condition, procedure or focus, plain English. FR: Condition, procedure or focus, in French or English."Input schema / properties / offset / descriptionPrevious value: -"US: For paging (at most 20, so 30 results in all: narrow the search instead of paging further). NZ: For paging (at most 20, so 30 results in all: narrow the search instead)."New value: +"US: For paging (at most 20, so 30 results in all: narrow the search instead of paging further). NZ: For paging (at most 20, so 30 results in all: narrow the search instead). FR: For paging (at most 20, so 30 results in all: narrow the search instead)."Input schema / properties / online_bookingAdded value: +{
+ "description": "(FR only) True keeps doctors whose Maiia or hospital page shows online booking (Doctolib is not covered).",
+ "type": "boolean"
+}Input schema / properties / place / descriptionPrevious value: -"(NZ only) New Zealand city, suburb, or region or Health NZ district (e.g. 'Waikato', 'Hawke's Bay', 'Capital and Coast')."New value: +"NZ: New Zealand city, suburb, or region or Health NZ district (e.g. 'Waikato', 'Hawke's Bay', 'Capital and Coast'). FR: City, postcode, arrondissement ('Paris 15'), département number ('69', '2A') or a practice or hospital name."Input schema / properties / specialty / descriptionPrevious value: -"US: Specialty id, name, title or family, e.g. 'cardiology', 'cardiologist', 'ENT', 'GI', 'OB/GYN', 'primary care', 'pediatric neurology', 'palliative care', 'orthopaedic-surgery'. See list_specialties. NZ: Specialty name, a word from one, or a plain word like 'eye' (see list_specialties)."New value: +"US: Specialty id, name, title or family, e.g. 'cardiology', 'cardiologist', 'ENT', 'GI', 'OB/GYN', 'primary care', 'pediatric neurology', 'palliative care', 'orthopaedic-surgery'. See list_specialties. NZ: Specialty name, a word from one, or a plain word like 'eye' (see list_specialties). FR: Specialty in French or English, e.g. 'cardiologie', 'dermatology', 'ORL', 'GP' (see list_specialties)."Input schema / properties / teleconsultationAdded value: +{
+ "description": "(FR only) True keeps doctors offering video consultations on Maiia.",
+ "type": "boolean"
+}about_database2 fields changedInput schema / properties / countryAdded value: +{
+ "description": "Where the person wants to be seen: United States (country=US), New Zealand (country=NZ). Decide it before searching; if unclear, ask the person. Older clients that leave it out get United States.",
+ "enum": [
+ "US",
+ "NZ"
+ ],
+ "type": "string"
+}Input schema / requiredAdded value: +[
+ "country"
+]get_doctor6 fields changedInput schema / properties / detail / descriptionPrevious value: -"Default summary."New value: +"(US only) Default summary."Input schema / properties / doctor_id / descriptionPrevious value: -"doctor_id from search_doctors, e.g. 'dr_4k9m2x7qph3t'."New value: +"One doctor_id from search_doctors (dr_... = United States, nz_... = New Zealand)."Input schema / properties / doctor_id / patternPrevious value: -"^dr_[0-9a-z]{12}$"New value: +"^(?:dr_[0-9a-z]{12}|nz_[0-9a-z]{12})$"Input schema / properties / doctor_ids / descriptionPrevious value: -"Up to 10 doctor_ids from search_doctors, e.g. ['dr_4k9m2x7qph3t', 'dr_8w2c5n1kd7ra']."New value: +"Up to 10 doctor_ids from search_doctors, all from one country (dr_... = United States, nz_... = New Zealand)."Input schema / properties / doctor_ids / items / patternPrevious value: -"^dr_[0-9a-z]{12}$"New value: +"^(?:dr_[0-9a-z]{12}|nz_[0-9a-z]{12})$"Input schema / properties / npi / descriptionPrevious value: -"10-digit NPI, instead of doctor_id."New value: +"(US only) 10-digit NPI, instead of doctor_id."list_specialties2 fields changedInput schema / properties / countryAdded value: +{
+ "description": "Where the person wants to be seen: United States (country=US), New Zealand (country=NZ). Decide it before searching; if unclear, ask the person. Older clients that leave it out get United States.",
+ "enum": [
+ "US",
+ "NZ"
+ ],
+ "type": "string"
+}Input schema / requiredAdded value: +[
+ "country"
+]public_waitlistsearch_doctors25 fields changedInput schema / properties / accepting_new_patients / descriptionPrevious value: -"true keeps only doctors listed as accepting new patients by their hospital website (others are unknown, not 'no'; confirm when booking)."New value: +"(US only) true keeps only doctors listed as accepting new patients by their hospital website (others are unknown, not 'no'; confirm when booking)."Input schema / properties / childAdded value: +{
+ "description": "(NZ only) True when the patient is a child: among doctors in the same place who match the need equally well, those in paediatrics or who list children in their focus come first, then those whose services say they see children; doctors whose services list only adult ages are left out. Most listings do not say, so those doctors stay in.",
+ "type": "boolean"
+}Input schema / properties / city / descriptionPrevious value: -"City of a practice location. Alone it matches only that exact city name (suburbs are separate cities); for a metro area add within_miles, e.g. city='Dallas', state='TX', within_miles=25."New value: +"(US only) City of a practice location. Alone it matches only that exact city name (suburbs are separate cities); for a metro area add within_miles, e.g. city='Dallas', state='TX', within_miles=25."Input schema / properties / condition / descriptionPrevious value: -"Disease, symptom or problem, e.g. 'atrial fibrillation', 'knee osteoarthritis', 'breast cancer', 'migraine'."New value: +"(US only) Disease, symptom or problem, e.g. 'atrial fibrillation', 'knee osteoarthritis', 'breast cancer', 'migraine'."Input schema / properties / countryAdded value: +{
+ "description": "Where the person wants to be seen: United States (country=US), New Zealand (country=NZ). Decide it before searching; if unclear, ask the person. Older clients that leave it out get United States.",
+ "enum": [
+ "US",
+ "NZ"
+ ],
+ "type": "string"
+}Input schema / properties / experienced_firstAdded value: +{
+ "description": "(NZ only) True when the person wants an experienced or senior doctor: among doctors who match equally well, those longer on the New Zealand specialist (vocational) register come first. Time on the register is not quality, and doctors who trained overseas may have practised longer than it shows.",
+ "type": "boolean"
+}Input schema / properties / gender / descriptionPrevious value: -"Doctor's gender (NPI registry)."New value: +"female or male. US: Doctor's gender (NPI registry). NZ: Only when the person asks. Gender is recorded for only a small share of doctors (when their Healthpoint page states it); doctors without it are left out and gender_note says how many."Input schema / properties / gender / enumPrevious value: -[
- "F",
- "M"
-]New value: +[
+ "female",
+ "male"
+]Input schema / properties / language / descriptionPrevious value: -"Language the doctor speaks other than English, e.g. 'Spanish', 'Mandarin', 'Vietnamese' (several: 'Spanish, Portuguese' = any of them). Keeps only doctors whose hospital website lists it (one site lists office staff's languages too); most doctors have no such page here, so if few results, also search the web."New value: +"US: Language the doctor speaks other than English, e.g. 'Spanish', 'Mandarin', 'Vietnamese' (several: 'Spanish, Portuguese' = any of them). Keeps only doctors whose hospital website lists it (one site lists office staff's languages too); most doctors have no such page here, so if few results, also search the web. NZ: Language other than English the doctor, or a small clinic (3 doctors or fewer) they work in, lists, e.g. 'Mandarin', 'Hindi', 'Samoan'."Input schema / properties / medicare_patient / descriptionPrevious value: -"true for a person 65 or older or on Medicare: leaves out doctors on the CMS Medicare opt-out list (Medicare and Medicare Advantage plans will not pay them except for emergency or urgent care). Without it such doctors carry a WARNING in warnings."New value: +"(US only) true for a person 65 or older or on Medicare: leaves out doctors on the CMS Medicare opt-out list (Medicare and Medicare Advantage plans will not pay them except for emergency or urgent care). Without it such doctors carry a WARNING in warnings."Input schema / properties / name / descriptionPrevious value: -"Part of the doctor's name. Name searches also return NPI records that are probably not physicians (nurse practitioners, physician assistants, etc.), marked with a WARNING; other searches leave them out."New value: +"US: Part of the doctor's name. Name searches also return NPI records that are probably not physicians (nurse practitioners, physician assistants, etc.), marked with a WARNING; other searches leave them out. NZ: Doctor's name or part of it, to check a named doctor."Input schema / properties / near_zip / descriptionPrevious value: -"One or more US ZIP codes, comma-separated. With within_miles: practices within that distance of these ZIPs. Without it: practices in the same 3-digit ZIP areas (one area can be only part of a big metro, e.g. Brooklyn 112 but not Manhattan 100-102)."New value: +"(US only) One or more US ZIP codes, comma-separated. With within_miles: practices within that distance of these ZIPs. Without it: practices in the same 3-digit ZIP areas (one area can be only part of a big metro, e.g. Brooklyn 112 but not Manhattan 100-102)."Input schema / properties / needAdded value: +{
+ "description": "(NZ only) Condition, procedure or focus, plain English.",
+ "maxLength": 200,
+ "type": "string"
+}Input schema / properties / offset / descriptionPrevious value: -"For paging (at most 20, so 30 results in all: narrow the search instead of paging further)."New value: +"US: For paging (at most 20, so 30 results in all: narrow the search instead of paging further). NZ: For paging (at most 20, so 30 results in all: narrow the search instead)."Input schema / properties / patient / descriptionPrevious value: -"adult removes child-only specialties; child lists pediatric specialists and doctors listed on a children's hospital's own website (listed_on_childrens_hospital_website in results) first, unless there is evidence that they mainly treat adults."New value: +"(US only) adult removes child-only specialties; child lists pediatric specialists and doctors listed on a children's hospital's own website (listed_on_childrens_hospital_website in results) first, unless there is evidence that they mainly treat adults."Input schema / properties / placeAdded value: +{
+ "description": "(NZ only) New Zealand city, suburb, or region or Health NZ district (e.g. 'Waikato', 'Hawke's Bay', 'Capital and Coast').",
+ "maxLength": 200,
+ "type": "string"
+}Input schema / properties / procedure / descriptionPrevious value: -"Procedure or surgery, e.g. 'knee replacement', 'TAVR', 'cataract surgery', 'Mohs surgery'. See list_procedures."New value: +"(US only) Procedure or surgery, e.g. 'knee replacement', 'TAVR', 'cataract surgery', 'Mohs surgery'. See list_procedures."Input schema / properties / sectorAdded value: +{
+ "description": "(NZ only) private = the doctor lists a private service; public = a public (Health NZ) service. Default any.",
+ "enum": [
+ "any",
+ "private",
+ "public"
+ ],
+ "type": "string"
+}Input schema / properties / sort / descriptionPrevious value: -"evidence (default), volume (best Medicare procedure rank first) or standing (named principal investigator on industry-sponsored research first)."New value: +"(US only) evidence (default), volume (best Medicare procedure rank first) or standing (named principal investigator on industry-sponsored research first)."Input schema / properties / southern_cross_affiliatedAdded value: +{
+ "description": "(NZ only) True keeps doctors whose own Healthpoint page or at least one of whose service pages says Southern Cross Affiliated Provider (cover still depends on the policy and often prior approval; confirm).",
+ "type": "boolean"
+}Input schema / properties / specialty / descriptionPrevious value: -"Specialty id, name, title or family, e.g. 'cardiology', 'cardiologist', 'ENT', 'GI', 'OB/GYN', 'primary care', 'pediatric neurology', 'palliative care', 'orthopaedic-surgery'. See list_specialties."New value: +"US: Specialty id, name, title or family, e.g. 'cardiology', 'cardiologist', 'ENT', 'GI', 'OB/GYN', 'primary care', 'pediatric neurology', 'palliative care', 'orthopaedic-surgery'. See list_specialties. NZ: Specialty name, a word from one, or a plain word like 'eye' (see list_specialties)."Input schema / properties / state / descriptionPrevious value: -"US state, 2-letter code (MA) or full name. With within_miles it only identifies the city (the radius can cross state lines) and is ignored with near_zip."New value: +"(US only) US state, 2-letter code (MA) or full name. With within_miles it only identifies the city (the radius can cross state lines) and is ignored with near_zip."Input schema / properties / text / descriptionPrevious value: -"Free-text filter over specialty, medical school, hospitals, medical group and procedure groups, e.g. a hospital name. Insurance is not searchable (some hospital-website lists are shown in results, not filtered); for languages use language."New value: +"(US only) Free-text filter over specialty, medical school, hospitals, medical group and procedure groups, e.g. a hospital name. Insurance is not searchable (some hospital-website lists are shown in results, not filtered); for languages use language."Input schema / properties / within_miles / descriptionPrevious value: -"Search radius in miles around city (give state too) or near_zip, e.g. 25 for a metro area, 5-10 in a dense city such as New York City, Chicago, San Francisco or Boston (25 there spans the whole metro); includes suburbs and can cross state lines. Each result then has distance_miles."New value: +"(US only) Search radius in miles around city (give state too) or near_zip, e.g. 25 for a metro area, 5-10 in a dense city such as New York City, Chicago, San Francisco or Boston (25 there spans the whole metro); includes suburbs and can cross state lines. Each result then has distance_miles."Input schema / requiredAdded value: +[
+ "country"
+]search_gp_practicessearch_doctors1 field changedInput schema / properties / medicare_patient / descriptionPrevious value: -"true for a person 65 or older or on Medicare: leaves out doctors on the CMS Medicare opt-out list (Medicare and Medicare Advantage will not pay them). Without it such doctors carry a WARNING in warnings."New value: +"true for a person 65 or older or on Medicare: leaves out doctors on the CMS Medicare opt-out list (Medicare and Medicare Advantage plans will not pay them except for emergency or urgent care). Without it such doctors carry a WARNING in warnings."about_databaseget_doctorlist_procedureslist_specialtieslookup_termssearch_doctorsFind New Zealand doctors and GP practices by condition, procedure or place, with sources. No signup.
Find doctors in France by condition, procedure or place, with fee category and sources. No sign-up.
Research 7,400+ US doctors: search, semantic search, profiles, reviews & procedure pricing.
Verify any US doctor, dentist, therapist or clinic by NPI number. Free npi_lookup tool.
Add one secure layer between your agents and this server.