What can you do with this server?

The HawkSoft MCP server lets you read and write HawkSoft insurance agency data from any MCP client (Claude, Cursor, etc.) using natural language or structured tool calls. Read / Query * List agencies & offices — retrieve all agencies and their associated offices * Get a single client — fetch full client details including people, contacts, claims, policies, and invoices * Bulk fetch — retrieve up to 200 clients in a single call * Incremental sync — list clients modified since a given timestamp, with optional office filtering or deleted-record inclusion * Search by policy number — look up a client using an exact policy number match Write * Create log notes — append structured activity notes (phone calls, emails, carrier touchpoints, conversation summaries) to a client record, with optional follow-up task assignment * Create attachments — attach base64-encoded files (PDFs, images, documents) to a client record, optionally linked to a policy * Record receipts — log one or more payments against client invoices, with automatic log note creation Reference / Utility * List channels — access all 56 HawkSoft LogAction channel codes with friendly names and categories (also available as a resource at hawksoft://channels) * Audit logging — every tool call generates a JSONL audit trail for compliance Practical Use Cases * Pre-call client briefs (pull full history before a call) * Auto-documenting carrier or insured touchpoints as structured log notes * Attaching certificates of insurance or declaration pages to the right client record * Batch activity reporting and end-of-day digests * Reconciliation — surfacing clients with outstanding invoices and recording payments

How do I use hawksoft-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hawksoft-mcp Show me clients changed since Monday and group by carrier" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

hawksoft-mcp

by sanjibani

Overview Schema Related Servers Score Discussions

Python

Remote

hawksoft-mcp

Model Context Protocol (MCP) server for HawkSoft Insurance Agency Management.

Talk to your HawkSoft data from Claude, Cursor, or any MCP client — read clients, policies, and claims, and write back log notes, attachments, and receipts in plain English.

Built against the HawkSoft Partner API v3.0. No existing MCP for HawkSoft — this is the first.

What you can do with it

You:  "Show me every HawkSoft client modified since Monday and group them by carrier."

Claude:  *calls list_changed_clients, then get_client for each, then summarises*

You:  "Find the policy POR83741 and log a phone call with the insured about their renewal."

Claude:  *searches by policy → opens client → calls create_log_note with channel=5*

Other things agents do well with this server:

Pre-call briefs — pull the client's full history (policies, claims, prior conversations) before a phone call
Auto-document carrier touchpoints — every email/phone with a carrier becomes a structured log note
Batch activity reporting — "give me a weekly summary of every client I called"
Certificate of insurance / declaration page intake — attach PDFs straight into the right client record
Reconciliation help — surface clients with outstanding invoices, draft follow-ups

Related MCP server: QuickBooks Online MCP Server

Install

pip install -e .

Or just use uv / pipx if you prefer.

Configure

You need HawkSoft Partner API credentials — username + password issued by HawkSoft after your app is approved through their Partner Program.

export HAWKSOFT_USERNAME="your-vendor-username"
export HAWKSOFT_PASSWORD="your-vendor-password"

You can also drop these in a .env file (see .env.example).

Who uses this server?

Two audiences:

Approved HawkSoft API Partners building tools for independent agencies. Your vendor credentials work directly.
Independent agencies doing their own custom integration work. HawkSoft has explicitly opened this path — see the V3.0 launch post:
"any agencies who build their own custom API integrations" can use the V3.0 Partner API directly.
If you're an agency and don't have vendor credentials yet, email opportunities@hawksoft.com to get set up.

Use with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "hawksoft": {
      "command": "hawksoft-mcp",
      "env": {
        "HAWKSOFT_USERNAME": "your-vendor-username",
        "HAWKSOFT_PASSWORD": "your-vendor-password"
      }
    }
  }
}

Restart Claude Desktop. You should see 9 new tools + 1 resource (hawksoft://channels).

Use with Claude Code

claude mcp add hawksoft -- hawksoft-mcp \
  --env HAWKSOFT_USERNAME=your-user --env HAWKSOFT_PASSWORD=your-pass

Use with Cursor

Add a new MCP server in Cursor settings pointing at the hawksoft-mcp command with the same env vars.

Tools

Tool	Type	What it does
`list_agencies`	Read	List agency IDs that have subscribed to your vendor app
`list_offices`	Read	List offices for a given agency
`list_changed_clients`	Read	Incremental sync — clients changed since a timestamp
`get_client`	Read	Full client record (details, people, contacts, claims, policies)
`get_clients_bulk`	Read	Fetch up to 200 clients in one call
`search_client_by_policy`	Read	Find a client by exact policy number
`create_log_note`	Write	Add a log note + optional follow-up task
`create_attachment`	Write	Attach a base64 file (PDF / image / doc) to a client
`create_receipts`	Write	Record one or more payments against invoices
`list_channels_tool`	Reference	All 56 HawkSoft LogAction codes

Plus one resource:

URI	Description
`hawksoft://channels`	Full channel catalog (value / label / category)

Common patterns

Pre-call brief

User:  I'm about to call client 4231. Give me the full picture.
Agent: list_changed_clients(agency_id=1, as_of="2020-01-01")
       → [4231, ...]
       get_client(agency_id=1, client_id=4231)
       → returns details, policies, people, prior claims
       summarise: 2 personal auto policies, 1 umbrella, no recent claims, last contact 2 weeks ago about a billing question...

Document a phone call after it happens

User:  I just got off a call with the Johnsons about their renewal. Auto policy. Renewal looks good, they want to add a teenage driver next month.
Agent: search_client_by_policy(agency_id=1, policy_number="AUTO-7741")
       → finds client
       create_log_note(
           agency_id=1,
           client_id=client_id,
           channel="Phone From Insured",
           description="Renewal discussion; wants to add teen driver next month",
           body="Discussed upcoming renewal. Customer satisfied with current rate. Mentioned adding a teenage driver in ~30 days. Set follow-up task for CSR to send driver addition intake form.",
           task_title="Send teen driver intake form",
           task_description="Customer mentioned adding teenage driver to auto policy next month. Send standard intake form.",
           task_due_date="2026-07-15",
           task_assigned_to_role="CSR",
       )

End-of-day activity digest

User:  What did I do with clients today?
Agent: create_log_note(...) for each touchpoint during the day,
       then for the digest: get_clients_bulk(client_numbers=[recent_ids])
       and summarise.

Channel catalog

Channels use friendly names everywhere in the API — never the integer. Phone From Insured, Email To Carrier, etc. The full 56-entry catalog is exposed via the list_channels_tool tool and the hawksoft://channels resource.

API coverage

HawkSoft endpoint	MCP tool
`GET /vendor/agencies`	`list_agencies`
`GET /vendor/agency/{id}/offices`	`list_offices`
`GET /vendor/agency/{id}/clients`	`list_changed_clients`
`GET /vendor/agency/{id}/client/{id}`	`get_client`
`POST /vendor/agency/{id}/clients`	`get_clients_bulk`
`GET /vendor/agency/{id}/clients/search`	`search_client_by_policy`
`POST /vendor/agency/{id}/client/{id}/log`	`create_log_note`
`POST /vendor/agency/{id}/client/{id}/attachment`	`create_attachment`
`POST /vendor/agency/{id}/client/{id}/receipts`	`create_receipts`

Full HawkSoft Partner API v3.0 docs: https://partner.hawksoft.app/v3/api.html

Development

# install with dev deps
pip install -e ".[dev]"

# run tests
pytest

# run server locally (stdio)
hawksoft-mcp

Security & audit logging

Every tool call emits a structured JSONL audit record (one JSON object per line) to stderr by default. Each record has:

ts, tool, request_id, args, result_size, is_error, error_type, duration_ms

Sensitive fields are redacted before logging: password, api_key, token, access_token, refresh_token, authorization, client_secret. Long string values are truncated to 256 characters.

To redirect to a file (e.g. for shipping to your log aggregator), set:

export HAWKSOFT_MCP_AUDIT_LOG=/var/log/hawksoft-mcp/audit.jsonl
hawksoft-mcp

The audit log is fail-open: if the configured file cannot be opened (missing directory, permission denied), records fall back to stderr and the tool still returns its result.

If you don't have HawkSoft credentials yet, the client will raise a clear error on first call — the server doesn't try to connect at import time.

License

MIT — see LICENSE.

Contributing

Issues + PRs welcome. Two things that always help:

More tools. If you spot a HawkSoft endpoint we missed (or one that needs a friendlier wrapper), open an issue.
Better prompts. The most useful thing you can share is a real example of an insurance workflow this helped you with — we collect these in /examples.

Available Tools

10 tools

create_attachmentA

Attach a base64-encoded file (PDF, image, doc) to a client record.

Args: agency_id: HawkSoft agency ID. client_id: HawkSoft client number. channel: Channel name or LogAction int (use list_channels for the catalog). desc: One-line description of the file. log_note: Log note text tied to this attachment. file_name: File name including extension, e.g. "declaration_page.pdf". file_b64: Base64-encoded file contents — NO data: URL prefix. policy_id: Optional policy GUID to link to. ref_id: Idempotency UUID (auto-generated if omitted). ts: ISO 8601 timestamp (defaults to now). task_title, task_description, task_due_date, task_assigned_to_role, task_assigned_to_email, task_category: Optional follow-up task.

ParametersJSON Schema

Name	Required	Description	Default
`ts`	No
`desc`	Yes
`ref_id`	No
`channel`	Yes
`file_b64`	Yes
`log_note`	Yes
`agency_id`	Yes
`client_id`	Yes
`file_name`	Yes
`policy_id`	No
`task_title`	No
`task_category`	No
`task_due_date`	No
`task_description`	No
`task_assigned_to_role`	No
`task_assigned_to_email`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, so description carries full burden. Discloses important behavioral details: file_b64 must not have 'data:' URL prefix; ref_id is optional and auto-generated; lists all optional task-related fields. Could mention idempotency behavior or side effects, but overall effective.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Starts with a one-sentence purpose, then uses a clear 'Args:' list format. Each parameter is explained concisely. No extraneous text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all 16 parameters with meaningful descriptions. Output schema exists, so return values are not needed. Lacks file size limits or accepted MIME types, but overall complete for an attachment creation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%; the description provides explicit purpose for each of the 16 parameters (e.g., 'channel: Channel name or LogAction int ...', 'file_b64: Base64-encoded file contents — NO data: URL prefix'). This fully compensates for missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the action ('attach'), input type ('base64-encoded file'), allowed file types ('PDF, image, doc'), and target ('client record'). Distinguishes from sibling tools like create_log_note and create_receipts by focusing on file attachment.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Does not explicitly state when to use this tool versus alternatives. The purpose is implied (when attaching a file), but no 'when not to use' or comparison to siblings is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_log_noteA

Append a log note (and optional follow-up task) to a client's record.

The single most useful write tool — call this whenever the agent does anything that should be visible in HawkSoft: a phone call, an email, a conversation summary, a carrier touch.

Args: agency_id: HawkSoft agency ID. client_id: HawkSoft client number. channel: Friendly channel name (e.g. "Phone From Insured") or LogAction int. description: One-sentence summary shown in the activity feed. body: Full note text. May be multi-line. ref_id: Unique UUID for idempotency. Auto-generated if omitted. ts: ISO 8601 timestamp. Defaults to now (UTC). policy_id: Optional policy GUID to link the note to. policy_index: Optional 1-based index on the policy. action: Optional action code. task_title: Set to create a follow-up task. task_description: Task description. task_due_date: ISO 8601 due date. task_assigned_to_role: One of SpecifiedUser, Producer, CSR, Agent1, Agent2, Agent3. task_assigned_to_email: Required when assigned_to_role is SpecifiedUser. task_category: Optional category label.

ParametersJSON Schema

Name	Required	Description	Default
`ts`	No
`body`	Yes
`action`	No
`ref_id`	No
`channel`	Yes
`agency_id`	Yes
`client_id`	Yes
`policy_id`	No
`task_title`	No
`description`	Yes
`policy_index`	No
`task_category`	No
`task_due_date`	No
`task_description`	No
`task_assigned_to_role`	No
`task_assigned_to_email`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It reveals that the tool appends a log note, can create follow-up tasks, and supports idempotency via ref_id. It does not detail auth requirements or failure modes, but provides sufficient behavioral context for an agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is moderately long but well-structured: purpose first, then usage guidance, then parameter list. The parameter list is in plain text but clear. Could be more structured (e.g., bullets), but not verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 16 parameters and 5 required, the description covers each parameter and provides usage context. Since an output schema exists, return values don't need explaining. Some behavioral details are missing but overall complete enough for agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description includes an 'Args' section that explains all 16 parameters with context (e.g., 'Unique UUID for idempotency', 'Friendly channel name'). This fully compensates for the lack of schema descriptions, adding significant value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool appends a log note and optional follow-up task to a client record. It is explicit that this is the primary write tool for logging agent actions, distinguishing it from other tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description explicitly says 'call this whenever the agent does anything that should be visible in HawkSoft' and lists examples (phone call, email, etc.). However, it does not contrast with sibling tools like create_attachment, so some differentiation is missing. Strong guidance overall.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_receiptsA

Record one or more payments received by a client.

Each receipt applies to one or more invoices. A log note is automatically created and linked. Optionally create a follow-up task.

Args: agency_id: HawkSoft agency ID. client_id: HawkSoft client number. receipts: List of receipts. Each item must include: - channel: channel name or int - logNote: text of the log note - total: total amount received - invoices: list of {"invoiceId": "<guid>", "amount": <float>} Optional per receipt: refId, ts, policyId, officeId, payMethod, task.

ParametersJSON Schema

Name	Required	Description	Default
`receipts`	Yes
`agency_id`	Yes
`client_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses that a log note is automatically created and linked, and optionally a task. This is good behavioral disclosure. However, it does not mention potential side effects like idempotency, validation rules, or whether receipts can be modified after creation. Still, the provided information is solid for a 4.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured. The main purpose is front-loaded, followed by a bulleted Args section that organizes parameter details. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (creating multiple receipts with nested objects and side effects) and the presence of an output schema, the description is very complete. It covers all required and optional parameters, the receipt structure, and automatic behaviors. It lacks only minor details like error conditions, but overall it's sufficient for an AI agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It thoroughly describes the `receipts` parameter structure: required fields (channel, logNote, total, invoices) and optional fields (refId, ts, policyId, officeId, payMethod, task). It also explains `agency_id` and `client_id` as HawkSoft identifiers. This provides crucial meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Record one or more payments received by a client.' It specifies that each receipt applies to invoices, automatically creates a log note, and optionally creates a follow-up task. This distinguishes it from sibling tools like create_log_note or create_attachment, which handle different operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the tool does but does not explicitly state when to use it versus alternatives. It implies usage for recording payments, but lacks guidance on when not to use it (e.g., for simple note logging, use create_log_note). Context is clear but no exclusions or alternatives are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_clientA

Fetch full details for a single client.

Returns the full client object — details, people, contacts, claims, policies by default. Use include to narrow the response and save bandwidth.

Args: agency_id: HawkSoft agency ID. client_id: HawkSoft client number. include: Sections to include: details, people, contacts, claims, policies, invoices.

ParametersJSON Schema

Name	Required	Description	Default
`include`	No
`agency_id`	Yes
`client_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that by default it returns all sections and that 'include' can narrow the response. However, it does not mention permissions, rate limits, or any side effects, which limits transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the main purpose. Every sentence adds value, and the Args section provides necessary parameter details. It is well-structured for quick understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the existence of an output schema, the description adequately covers return behavior (full client object by default). It also provides context via siblings, making it clear when to use this tool. Minor omissions like error handling are acceptable for a single-fetch tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description explains all three parameters: agency_id as 'HawkSoft agency ID', client_id as 'HawkSoft client number', and include listing possible sections (details, people, contacts, claims, policies, invoices). This adds significant meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Fetch full details for a single client', using a specific verb and resource. It distinguishes itself from the sibling 'get_clients_bulk' by focusing on a single client.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly indicates this tool is for a single client, implicitly contrasting with 'get_clients_bulk'. It also provides guidance on using 'include' to narrow responses and save bandwidth. No explicit exclusions are given, but the context is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_clients_bulkA

Fetch multiple clients in one call (up to 200 per request).

Args: agency_id: HawkSoft agency ID. client_numbers: List of client numbers (1–200 per call).

ParametersJSON Schema

Name	Required	Description	Default
`agency_id`	Yes
`client_numbers`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description mentions the request limit but omits read-only nature, error handling, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences plus parameter list: front-loaded and concise with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists so return values need not be described; description covers key aspects but could add error handling or auth requirements.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds domain context for agency_id ('HawkSoft agency ID') and client_numbers range (1-200), despite 0% schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it fetches multiple clients in one call with a limit of 200, distinguishing it from sibling 'get_client' for single records.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly guides usage via the 'bulk' vs 'get_client' naming, but lacks explicit when-not or alternative suggestions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_agenciesA

List agency IDs that have subscribed to your HawkSoft vendor app.

Returns an array of integer agency IDs. Each represents an independent insurance agency that has opted in to data sharing with your app via the HawkSoft License Management Portal.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully carries the burden. It states the tool is read-only (returns a list) and explains the return value (array of integer agency IDs representing subscribed agencies). This is transparent enough for safe invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. The first sentence states the action, the second adds return format and meaning. Front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, no annotations, and an output schema, the description sufficiently explains what the tool does and what it returns. It covers the essential context for selecting and invoking this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so the description doesn't need to add parameter information. According to calibration, 0 params warrants a baseline of 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('agency IDs that have subscribed'), clearly distinguishing it from sibling tools like 'list_offices' (likely lists offices within an agency) and 'list_channels_tool' (likely lists channels).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool should be used to retrieve subscribed agency IDs, but does not explicitly state when to use it versus alternatives like 'list_offices' or list_changed_clients.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_changed_clientsA

List client IDs that changed since a given timestamp.

The workhorse for syncing. Pass an as_of ISO 8601 timestamp to get only clients modified after that point; omit it to get all clients. Then use get_client or get_clients_bulk on each ID.

Args: agency_id: HawkSoft agency ID. as_of: ISO 8601 timestamp (e.g. 2026-06-01T00:00:00Z). Omit for full list. office_id: Restrict to a specific office. include_deleted: Include soft-deleted clients.

ParametersJSON Schema

Name	Required	Description	Default
`as_of`	No
`agency_id`	Yes
`office_id`	No
`include_deleted`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that the tool returns client IDs (not full objects) and the effect of omitting `as_of`. However, it lacks details on potential rate limits, authentication needs, or behavior on invalid inputs. Adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise and well-structured: starts with a one-line summary, then expands on usage and parameters in a docstring format. No extraneous information; every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the existence of an output schema, the description does not need to explain return values. It covers all four parameters and the core use case. Could mention pagination or error handling, but overall complete for a list tool with sibling references.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description compensates well. It explains the purpose of each parameter: `as_of` as an ISO 8601 timestamp (optional for full list), `office_id` to restrict to an office, and `include_deleted` for soft-deleted clients. The description adds meaning beyond the schema types and defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists client IDs changed since a timestamp, using specific verb 'list' and resource 'client IDs that changed'. It distinguishes itself from siblings like `get_client` and `get_clients_bulk` by indicating the output is IDs only, and suggests using those tools for full details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly identifies it as 'The workhorse for syncing' and instructs to pass an `as_of` timestamp for incremental changes or omit for full list. It also directs to use `get_client` or `get_clients_bulk` on each ID afterward, providing clear usage context. Does not explicitly state when not to use, but the guidance is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_channels_toolA

Return all 56 HawkSoft channel codes with friendly names and categories.

Use this to discover the right channel value to pass into create_log_note, create_attachment, or create_receipts.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It accurately describes the tool as read-only (returning data) and specifies the exact count and content (codes, names, categories). It does not mention authentication or rate limits, but given the simplicity, it is sufficiently transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences. The first states what the tool returns, the second explains usage. No unnecessary words, and information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and an output schema (as indicated by context signals), the description is fully complete. It explains the purpose, the data returned, and how to use the result with sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so schema coverage is 100% by default. The description adds no additional parameter info, but none is needed. Baseline 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns all 56 HawkSoft channel codes with friendly names and categories. It uses a specific verb ('return') and resource ('channel codes'), and distinguishes from sibling tools which are write operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs to use this tool to discover the channel value for create_log_note, create_attachment, or create_receipts. This provides clear when-to-use guidance with concrete examples.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_officesB

List offices configured under an agency.

Args: agency_id: HawkSoft agency ID (from list_agencies).

ParametersJSON Schema

Name	Required	Description	Default
`agency_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and the description fails to disclose behavioral traits such as read-only nature, pagination, or error conditions. The description carries full burden but offers minimal transparency beyond the basic listing action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise with a clear structure. The description is front-loaded with the core action, followed by a parameter explanation in a single line. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema, return values are covered. The description covers the single parameter adequately but lacks behavioral and usage guidance. For a simple list tool, it is minimally complete but could be better.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description adds value by indicating agency_id comes from list_agencies. However, it does not fully compensate for the lack of parameter detail, as the schema already shows type and requirement.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List offices configured under an agency,' providing a specific verb and resource. It distinguishes from sibling tools like list_agencies or list_changed_clients, but without explicit differentiation, it is very clear but not maximally distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., list_agencies). The description does not specify prerequisites or exclusions, leaving the agent to infer usage from context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_client_by_policyA

Find a client by exact policy number match.

Useful when an agent has a policy number from a carrier but not the HawkSoft client number. Returns all clients (usually 1) holding that policy. Exact match only — no partial or fuzzy search.

Args: agency_id: HawkSoft agency ID. policy_number: Exact policy number. include: Sections to include.

ParametersJSON Schema

Name	Required	Description	Default
`include`	No
`agency_id`	Yes
`policy_number`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses key behaviors: returns all clients (usually 1) holding the policy, exact match only. Since no annotations are provided, the description carries the full burden, and it adequately covers the tool's safety (read-only search) and result characteristics. It does not mention authentication or rate limits, but those are less critical for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with a clear opening sentence and a bulleted Args section. It is front-loaded with the core purpose and constraints. Every sentence adds value, though the Args descriptions could be slightly more structured (e.g., using a list format is already good).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (3 parameters, 2 required, output schema present), the description covers the essential aspects: purpose, exact match behavior, typical result count, and parameter explanations. It lacks detail on the 'include' parameter's possible values, but otherwise is complete for an agent to use the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, so the description must compensate. The 'Args' block briefly explains agency_id and policy_number, adding context beyond schema titles (e.g., 'HawkSoft agency ID', 'Exact policy number'). However, the 'include' parameter is only described as 'Sections to include,' which is vague and adds little meaning. More detail on what values 'include' accepts would improve semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's function: 'Find a client by exact policy number match.' It specifies the exact match requirement and the use case (agent has policy number but not HawkSoft client number). This distinguishes it from sibling tools like get_client which require a client number.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear use case: 'Useful when an agent has a policy number from a carrier but not the HawkSoft client number.' It also specifies limitations ('Exact match only — no partial or fuzzy search'). However, it does not explicitly mention when not to use or suggest alternative tools, which would elevate the score to 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0

Disambiguation5/5

Each tool targets a distinct resource or action: create_attachment, create_log_note, create_receipts for different logging operations; get_client and get_clients_bulk for client retrieval (single vs. bulk); list_agencies, list_channels_tool, list_offices for different listings; search_client_by_policy for policy-based search; and list_changed_clients for sync. No two tools have overlapping purposes.

Naming Consistency4/5

All tool names follow a consistent verb_noun snake_case pattern (e.g., create_log_note, get_client, list_agencies). The only minor deviation is list_channels_tool which appends '_tool', but it is still readable and clearly indicates its purpose.

Tool Count5/5

With 10 tools, the set is well-scoped for a HawkSoft server covering client retrieval, logging activities (notes, attachments, receipts), and listing utilities (agencies, offices, channels, changed clients). Each tool earns its place without being excessive or sparse.

Completeness4/5

The core workflows are covered: retrieving clients (single, bulk, by policy), adding log notes, attachments, and receipts, and listing supporting entities. Minor gaps exist, such as no update or delete operations for logs or client data, but agents can likely accomplish typical tasks without dead ends.

Maintenance

ActivitySlowing

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

HAVN
app.havnre
Read-only AI access to HAVN properties, leads, tasks, files, media, and analytics.
Real Estate CRM
2
Cotribute MCP
com.cotribute
Connect AI agents to financial institution origination, analytics, and compliance workflows.
Finance CRM
2
kesslerio-attio-mcp-server-betaOAuth
ai.smithery
Streamline your Attio workflows using natural language to search, create, update, and organize com…
Customer Data Platforms App Automation Workplace & Productivity
268
OpenClaw Direct AOAuth
direct.openclaw
Deploy, monitor, and manage your OpenClaw AI assistants via natural language.
Agent Orchestration Autonomous Agents Monitoring
2

Related MCP Servers

HubSpot MCP Server
Customer Data Platforms Marketing
ajaystream
A
license
A
quality
D
maintenance
Enables AI clients to seamlessly take HubSpot actions and interact with HubSpot data, allowing users to create/update CRM records, manage associations, and gain insights through natural language.
Updated a year ago (2025-07-24 13:18 UTC)
22
15
MIT
QuickBooks Online MCP Server
Finance ERP Systems
hakeemrabiuDFW
A
license
A
quality
D
maintenance
Enables AI assistants to query and manage QuickBooks Online data through natural language, including customers, invoices, bills, vendors, accounts, and financial reports.
Updated 8 months ago (2026-01-11 19:24 UTC)
7
MIT
Zava Insurance MCP Server
Project Management Customer Support
rabwill
F
license
Not graded
quality
D
maintenance
Enables management of insurance claims, inspections, and contractors through interactive UI widgets and data tools. Users can view claim dashboards, update statuses, and query service provider information using natural language.
Updated 7 months ago (2026-02-13 03:39 UTC)
QuickBooks MCP
Finance ERP Systems
laf-rge
A
license
A
quality
A
maintenance
Enables financial professionals to interact with QuickBooks Online using natural language for reports, journal entries, bills, expenses, and more.
Updated 9 days ago (2026-08-24 21:53 UTC)
36
865
11
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sanjibani/hawksoft-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

hawksoft-mcp

What you can do with it

Install

Configure

Who uses this server?

Use with Claude Desktop

Use with Claude Code

Use with Cursor

Tools

Common patterns

Pre-call brief

Document a phone call after it happens

End-of-day activity digest

Channel catalog

API coverage

Development

Security & audit logging

License

Contributing

See also

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API