Rust-first tooling for the Healthpoint HL7 FHIR® API: a typed client, CLI, read-only MCP server, and future open-social-data adapter.
This repository is intentionally code-first and data-light:
Users bring their own Healthpoint API key/licence.
No real Healthpoint API payloads are committed as fixtures.
Synthetic FHIR fixtures live in crates/healthpoint-testkit/fixtures/.
Local exports are marked with provenance and redistribution status.
Open-data publication is opt-in and disabled until licensing/access terms explicitly permit it.
healthpoint-rs/
crates/
healthpoint-core/ # domain model, query model, provenance, provider traits, URI parsing
healthpoint-fhir/ # FHIR Bundle/Resource mapping and typed projections
healthpoint-client/ # HTTP client, auth, request policy, pagination hooks
healthpoint-export/ # JSON/JSONL/CSV/export manifests
healthpoint-cli/ # `healthpoint` CLI
healthpoint-mcp/ # read-only MCP server over the same core/client
healthpoint-osd-adapter/ # future open_social_data bridge, no hard dependency yet
healthpoint-testkit/ # synthetic fixtures and offline fixture provider
conductor/ # context-management state, decisions, checkpoints, tracks
docs/ # access, licensing, MCP, exports, integration roadmapRelated MCP server: Medplum
Install from crates.io after Rust is available:
cargo install healthpoint-mcp healthpoint-cliInstall from source checkout:
git clone https://github.com/edithatogo/healthpoint-rs.git
cd healthpoint-rs
bin/conductor-setup
cargo install --path crates/healthpoint-mcp
cargo install --path crates/healthpoint-cliInstall through Smithery from the published listing: edithatogo/healthpoint-rs. The Smithery package starts in synthetic mode unless live Healthpoint credentials are supplied.
First commands
cp .env.example .env
$EDITOR .env
bin/conductor-setup
cargo run -p healthpoint-cli -- doctor
cargo run -p healthpoint-cli -- fixture services --format json
cargo run -p healthpoint-cli -- inspect search-url --text "cervical screening" --snomed 171149006
cargo run -p healthpoint-cli -- search services --text "cervical screening" --format json
cargo run -p healthpoint-cli -- search services --snomed 171149006 --format json
cargo run -p healthpoint-cli -- get service <id> --format json
cargo run -p healthpoint-cli -- get uri healthpoint://service/<id> --format json
cargo run -p healthpoint-mcpThe MCP server is a separate binary so CLI and MCP can evolve independently while sharing the same crates. It starts in synthetic fixture mode when no API key is supplied; set HEALTHPOINT_MODE=live and provide HEALTHPOINT_API_KEY for licensed live API calls.
export HEALTHPOINT_MODE="synthetic" # synthetic | live
export HEALTHPOINT_API_KEY="..." # optional; required only for live mode
export HEALTHPOINT_BASE_URL="https://uat.healthpointapi.com/baseR4/"
export HEALTHPOINT_AUTH_SCHEME="x-api-key" # bearer | x-api-key | header:<name> | none
export HEALTHPOINT_GEO_SEARCH_MODE="healthpoint-lat-lon" # healthpoint-lat-lon | fhir-near
export HEALTHPOINT_TIMEOUT_SECS="30"
export HEALTHPOINT_EXPORT_POLICY="local-only" # local-only | licensed-share | open-approvedHealthpoint portal validation on 2026-06-30 confirmed UAT calls use the x-api-key header against https://uat.healthpointapi.com/baseR4/. See docs/healthpoint-api-access.md for observed endpoint and license notes.
healthpoint doctor
healthpoint policy show
healthpoint fixture services --format human
healthpoint schema service-record
healthpoint schema resource-uri
healthpoint inspect search-url \
--text "cervical screening" \
--snomed 171149006 \
--limit 10
healthpoint search services \
--text "cervical screening" \
--snomed 171149006 \
--limit 10 \
--format json
healthpoint search services \
--lat -36.8485 \
--lon 174.7633 \
--radius-km 10 \
--format csv
healthpoint get service <service-id> --format json
healthpoint get location <location-id> --format json
healthpoint get organization <organization-id> --format json
healthpoint get uri healthpoint://service/<service-id> --format json
healthpoint export manifest --output .healthpoint/manifest.json
healthpoint export services \
--text "cervical screening" \
--limit 25 \
--format jsonl \
--output .healthpoint/cervical-screening.jsonlTool | Purpose |
| Show redacted runtime mode, configuration, and readiness. |
| Show non-secret endpoint, auth, and documentation notes. |
| Show the conservative access/export policy before reuse. |
| Search HealthcareService records by text, codes, region filters, cursor, and limit. |
| Search HealthcareService records by SNOMED CT code in type, category, or specialty. |
| Find HealthcareService records near a latitude/longitude point. |
| Read one HealthcareService by FHIR id. |
| Read one Location by FHIR id. |
| Read one Organization by FHIR id. |
| Read a supported |
The MCP server also exposes 3 static resources, 4 resource templates, and 2 prompts. See docs/mcp-tools.md and docs/integrations/mcp-client-configs.md for launch examples.
Claude Desktop source-checkout example:
{
"mcpServers": {
"healthpoint-dev": {
"command": "cargo",
"args": ["run", "-p", "healthpoint-mcp"],
"env": {
"HEALTHPOINT_MODE": "synthetic"
}
}
}
}Live Healthpoint mode requires a licensed API key:
{
"mcpServers": {
"healthpoint-live": {
"command": "healthpoint-mcp",
"env": {
"HEALTHPOINT_MODE": "live",
"HEALTHPOINT_API_KEY": "...",
"HEALTHPOINT_BASE_URL": "https://uat.healthpointapi.com/baseR4/",
"HEALTHPOINT_AUTH_SCHEME": "x-api-key"
}
}
}
}The CLI can emit JSON Schema for the core contracts:
healthpoint schema access-policy
healthpoint schema service-query
healthpoint schema service-record
healthpoint schema service-page
healthpoint schema location-record
healthpoint schema organization-record
healthpoint schema resource-uri
healthpoint schema export-manifestThose schemas are intended to help future integration with open_social_data, MCP clients, and any cross-repo data catalogue layer without prematurely forcing Healthpoint's FHIR graph into a dataframe-first shape.
These commands work before any live Healthpoint validation and are useful in sandboxes or CI metadata jobs:
CONDUCTOR_ALLOW_NO_CARGO=1 bin/conductor-setup
bin/conductor-status
scripts/static-preflight.py
scripts/generate-contract-schemas.py
bin/mock-healthpoint-server --port 8787After Rust is available, the mock server gives the CLI a synthetic HTTP target:
export HEALTHPOINT_BASE_URL="http://127.0.0.1:8787/"
export HEALTHPOINT_AUTH_SCHEME="none"
cargo run -p healthpoint-cli -- search services --snomed 171149006 --format jsonSee docs/mock-server.md, docs/static-preflight.md, and docs/live-contract-capture.md.
See docs/development-environment.md for native Rust and devcontainer setup.
FHIR-first: preserve raw FHIR while exposing typed domain records.
Read-only by default: no writes, no scraping fallback, no public proxy mode.
Bring-your-own-key: releasing code does not bundle access or data rights.
Provenance everywhere: exports carry retrieval time, source, licence status, and tool version.
Integratable later: stable Rust traits make it possible to plug into open_social_data, MCP clients, and future data/catalog engines.
Conductor-managed context: implementation tracks, decisions, and repo state live alongside the code.
Synthetic fixtures only: offline testing is done with testkit resources, never real Healthpoint payloads.
MCP Registry name: mcp-name: io.github.edithatogo/healthpoint-rs
This visible marker is required for Cargo/crates.io ownership verification by the official MCP Registry.
This is not a clinical decision-support system. It retrieves and formats directory/service information from Healthpoint for licensed users. Any downstream use should preserve Healthpoint attribution, currency, caveats, and licensing obligations.
Implementation spike after initial scaffold. Synthetic mapping exists for HealthcareService, Location, and Organization, including richer service fields such as eligibility, availability, service provision codes, characteristics, comments, endpoints, identifiers, and response provenance. The public Healthpoint material confirms HL7 FHIR and SNOMED CT orientation, but full endpoint/auth details are intentionally treated as configurable until validated against licensed API documentation.
Show conservative Healthpoint access/export policy. Use before exporting or reusing data.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a read-only operation ('Show... policy'). With no annotations, this is adequate. It does not elaborate on output format, but given the simplicity, it's acceptable.
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?
A single, well-structured sentence conveys the purpose and usage guideline without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with no output schema, the description fully captures the tool's function and appropriate usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100% by default. The description appropriately adds no parameter info as none are needed, meeting the baseline for zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it shows the conservative Healthpoint access/export policy, distinguishing it from sibling tools that perform searches, lookups, or diagnostics.
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 advises to use 'before exporting or reusing data', providing clear context. No exclusion criteria are given, but the guidance is sufficient for this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show Healthpoint API access notes discovered from the portal. Does not include secrets.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the burden but only discloses that it 'does not include secrets', adding some behavioral insight but lacking details on read-only nature or authentication requirements.
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?
Single sentence, no fluff, front-loaded with action and resource. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with no output schema, the description is mostly complete: it states the purpose and a key behavioral note. However, it could mention the nature of the notes (e.g., plain text) or format.
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?
No parameters exist; schema coverage is 100%. The description adds no parameter info but that is unnecessary. The constraint on output (no secrets) is a plus.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Show' and resource 'Healthpoint API access notes', distinguishing it from siblings like healthpoint_access_policy which likely deals with policy rather than notes.
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?
No guidance on when to use this tool vs alternatives; the description only states what it does without indicating prerequisites or when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show redacted Healthpoint client configuration and readiness. Never returns the API key.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries full burden. It discloses a key behavioral trait: it never returns the API key, implying safety. However, it does not mention other aspects like execution speed or side effects, but for a simple status tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and concise. Every word serves a purpose, with no redundancy or 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?
Given the tool has zero parameters and no output schema, the description is complete. It explains the tool's purpose and a critical constraint (never returns API key), sufficient for an agent to understand and 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?
There are no parameters, so schema coverage is effectively 100%. The description adds no parameter details because none exist. A baseline of 4 is appropriate given no need for parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Show redacted Healthpoint client configuration and readiness', specifying the verb 'Show' and the resource 'client configuration and readiness'. It distinguishes from sibling tools by noting redaction and that it never returns the API key, implying a safe diagnostic status tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking configuration and readiness, but does not explicitly state when to use this tool versus alternatives or when not to use it. No guidance on prerequisites or context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find nearby Healthpoint HealthcareService records by latitude/longitude. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | Latitude. | |
| lon | Yes | Longitude. | |
| text | No | Optional full-text search term. | |
| limit | No | Maximum results. Clamped to 1..100. | |
| radius_km | No | Optional radius in kilometres. | |
| service_type | No | Optional service type code or system|code token. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description declares 'Read-only', which is a key behavioral trait, especially with no annotations provided. However, it does not disclose other behaviors like result ordering, pagination, or default radius, leaving some uncertainty for a tool with 6 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and contains no filler. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, no output schema, and no annotations, the description provides minimal context. It covers the basic intent but lacks details on return format, default behavior for radius, or how text search interacts with location, making it adequate but not thorough.
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 parameters. The description adds no additional meaning beyond the schema, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Find', the resource 'nearby Healthpoint HealthcareService records', and the method 'by latitude/longitude'. It distinguishes from sibling tools like healthpoint_get_service (single resource) and healthpoint_search_services (likely text-based).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for location-based proximity searches but provides no explicit guidance on when to use this tool versus alternatives such as healthpoint_search_services. No exclusion criteria or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single Healthpoint Location record by FHIR id. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | FHIR resource id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It correctly notes 'Read-only,' which is essential, but does not mention potential error handling, permissions required, or the structure of the returned record.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two sentences with no wasted words. The purpose is front-loaded in the first sentence, and the read-only trait is immediately clarified.
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 simple one-parameter read tool, the description is adequate but could be improved by indicating the output format, especially since no output schema is provided. It does not mention what fields the returned location record contains.
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 input schema fully documents the single 'id' parameter with description 'FHIR resource id.' The description redundantly states 'by FHIR id,' adding no new semantics. With 100% schema coverage, a baseline score 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?
The description clearly states the action (Get), resource (Healthpoint Location record), and method (by FHIR id). The name reinforces the resource. However, it does not explicitly differentiate from sibling tools like healthpoint_get_organization or healthpoint_get_service, which is a minor gap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as healthpoint_search_services or healthpoint_get_organization. It simply states what it does without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single Healthpoint Organization record by FHIR id. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | FHIR resource id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only says 'Read-only.' Does not disclose error behavior (e.g., invalid id), return format, or any side effects. For a simple read, more detail could be useful.
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?
Single sentence, no fluff, front-loaded with purpose. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given it's a simple get-by-id tool with no output schema, description is mostly complete. Could mention handling of missing records, but sufficient for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description adds no new meaning beyond the schema's 'FHIR resource id'. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get', resource 'Healthpoint Organization record', and method 'by FHIR id'. Distinguishes from siblings like healthpoint_get_location and healthpoint_get_service.
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?
No explicit guidance on when to use vs alternatives such as healthpoint_search_services. Implied usage for a single record by id, but lacks context on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single Healthpoint HealthcareService record by FHIR id. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | FHIR resource id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states 'Read-only', which is a key behavioral trait indicating no side effects. However, it does not disclose other important behaviors such as error handling for invalid ids, response format, or any access restrictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It front-loads the main action and scope, making it 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?
For a simple one-parameter get operation with no output schema, the description covers the essential purpose. It could optionally mention return behavior, but given the low complexity, it is sufficiently complete.
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% as the single parameter 'id' is described as 'FHIR resource id.' The description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'single Healthpoint HealthcareService record', and the method 'by FHIR id'. Adding 'Read-only' distinguishes it from mutating tools. Among siblings like healthpoint_get_location and healthpoint_get_organization, it uniquely identifies the service type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing a specific service by FHIR id, providing clear context. However, it lacks explicit guidance on when not to use this tool (e.g., if searching is needed) or mention of alternative sibling tools like healthpoint_search_services.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a supported healthpoint:// resource URI. This mirrors planned MCP resources while keeping the operation explicit and read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| uri | Yes | Resource URI such as healthpoint://service/<id>. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It adds that the operation is explicit and read-only, which is useful, but does not disclose other behavioral traits such as error handling, rate limits, or authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences that convey the purpose and key characteristic (read-only) without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description does not explain return values, which is a gap for a read operation. It also lacks error case details, making it adequate but not fully complete.
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 description does not add significant meaning beyond the schema's description of the 'uri' parameter. 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?
The description clearly states the tool reads a healthpoint:// resource URI, specifying the verb 'read' and the resource type. It distinguishes from siblings by being a generic reader rather than specific endpoints like get_service.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading any healthpoint:// URI but does not explicitly state when to use this tool over more specific siblings like healthpoint_get_service or healthpoint_get_location. No exclusion criteria or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Healthpoint HealthcareService records by SNOMED CT code. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | SNOMED CT code. | |
| field | No | Search field: type, category, or specialty. Defaults to type. | |
| limit | No | Maximum results. Clamped to 1..100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully disclose behavior. It only states 'Read-only', but omits details about authentication, rate limits, error handling, pagination behavior, or what happens when no results are found. This is insufficient for an AI agent to understand side effects or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences with no unnecessary words. It is front-loaded with the essential action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool outputs no schema and has three parameters, the description is minimally complete. It lacks details on the return format, result set size limits (beyond the schema-specified clamp), and how results relate to sibling tools. However, for a simple search tool, it meets basic needs.
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 input schema covers 100% of parameters, so the description adds no extra meaning beyond what is already defined. The description mentions SNOMED CT codes but does not elaborate on format or usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search'), the resource ('Healthpoint HealthcareService records'), and the search criterion ('by SNOMED CT code'). It effectively distinguishes from siblings like healthpoint_search_services which likely performs broader searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Read-only' which implies no destructive side effects, but it lacks explicit guidance on when to use this tool versus alternatives such as healthpoint_search_services. No prerequisites or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Healthpoint HealthcareService records. Read-only; requires a user-provided API key.
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Full-text search term. | |
| limit | No | Maximum results. Clamped to 1..100. | |
| cursor | No | Pagination cursor from a previous response. | |
| region | No | Healthpoint region, e.g. Southland. | |
| snomed | No | Convenience SNOMED CT service type codes. Repeatable. | |
| category | No | FHIR category code or system|code token. Repeatable. | |
| specialty | No | FHIR specialty code or system|code token. Repeatable. | |
| subregion | No | Healthpoint subregion, e.g. Ashburton. | |
| dhb_region | No | Healthpoint DHB region, e.g. Southern. | |
| branch_code | No | Healthpoint branch code, e.g. primary. | |
| service_type | No | FHIR service type code or system|code token. Repeatable. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature and API key requirement, which adds value beyond annotations (none provided). However, it does not explain pagination behavior, rate limits, or how multiple filter parameters interact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and front-loaded with the purpose. However, it could be slightly more informative without sacrificing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (11 parameters, no output schema), the description is too minimal. It does not mention return format, pagination details, or how filters combine, leaving significant gaps for an AI agent.
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. The description adds no additional meaning to parameters beyond what is already in the input schema (e.g., no explanation of filter combination logic or examples).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Search Healthpoint HealthcareService records.' It is specific but does not differentiate from sibling search tools such as 'healthpoint_search_by_snomed' or 'healthpoint_find_nearby_services', which also perform searches.
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?
No explicit guidance on when to use this tool versus alternatives. There is no mention of contexts where other tools might be preferred or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: policy display, API notes, diagnostic status, nearby search, individual record retrieval for location/organization/service, URI reading, SNOMED search, and general search. No overlapping functionality.
All tools follow a consistent 'healthpoint_' prefix with snake_case verb_noun pattern (e.g., find_nearby_services, get_location). No mixing of conventions.
With 10 tools covering metadata, search, and retrieval for a healthcare data domain, the count is well-scoped. Each tool serves a specific purpose without redundancy or bloat.
The tool set covers all necessary read-only operations for Healthpoint data: metadata about access and diagnostics, searching by proximity and SNOMED, retrieving individual resources, and parsing URIs. As a read-only server, there are no missing write operations.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Hosted MCP server for the Healthie EHR & telehealth API: patients, appointments, charting, tasks.
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Public read-only MCP server for HODLXXI agent identity, trust, receipts, and verification.
Read-only MCP server for Sandwich aging-parent care resources and cost data.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/edithatogo/healthpoint-rs'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
