The Peil MCP server connects Peil (a freelance invoicing/time-tracking app) to MCP clients like Claude, letting you manage clients, log hours, and handle invoices via natural language prompts.
Client Management
List clients, view details (including default rate)
Create, update, or delete clients (delete blocked if client has projects or sent invoices)
Time Tracking
Log hours for a client/project/description (with optional rate and date)
Edit or delete timesheet entries (delete blocked if linked to sent/paid invoices)
Invoicing
List unbilled hours per client for a given period
Draft invoices from unbilled hours, grouped by summary, project, or day
List invoices, filterable by status and/or client
Change invoice status (draft, sent, paid, overdue, archived)
Update safe fields: due date, payment date, notes
Delete invoices (paid invoices must be archived instead)
Financial Overview
Get an orientation snapshot: outstanding, overdue, draft invoices, and year-to-date position
Client-Facing Emails (require invoices:send permission)
Send an invoice by email immediately
Schedule a draft invoice to be emailed at a future date/time
Cancel a scheduled send
Send a payment reminder for sent/overdue invoices
Reminder Copy
View your custom reminder email text and schedule
Set custom reminder copy for specific tones (pre_due, overdue, formal) and languages (nl/en)
mcp-name: app.peil/peil-mcp
Connect Peil to Claude (or any MCP client): log hours, draft invoices from unbilled hours, and check where you stand — from a prompt.
Website: https://peil.app
The server is a pure client of Peil's public API. It authenticates with a scoped API key you create in Peil under Settings → Developer (Pro).
draft_invoice only ever creates a draft — nothing is sent to your
clients. Sending is a separate tool (send_invoice) that also requires the
separate invoices:send permission on your key. A key without that
permission can never email anything on your behalf.
Related MCP server: Time Tracking MCP
Reads (read)
Tool | What it does |
| List your clients |
| One client's details, incl. whether a default rate is set |
| Unbilled hours per client for a period |
| List invoices, filterable by status / client |
| Outstanding / overdue / drafts / YTD position |
| Your custom reminder email copy + schedule |
Hours (timesheet:write)
Tool | What it does |
| Add a timesheet entry (client default rate unless given) |
| Edit an entry (only the fields you pass change) |
| Delete an entry (blocked if on a sent/paid invoice) |
Clients (clients:write)
Tool | What it does |
| Client CRUD (delete blocked if it has projects/sent invoices) |
Invoices (invoices:write)
Tool | What it does |
| Draft an invoice from unbilled hours (summary / by_project / per_day) |
| Change status (e.g. mark paid) — does not email anyone |
| Edit safe fields (due date, payment date, notes) |
| Delete (paid ones blocked) / archive |
| Write custom reminder email copy for one tone/language |
Client-facing email (invoices:send — irreversible, always confirm first)
Tool | What it does |
| Email an invoice to the client now |
| Schedule a draft to be emailed at a future time |
| Cancel a scheduled send |
| Email a payment reminder for a sent/overdue invoice |
In Peil: Settings → Developer → create a key with the permissions you want.
Start with read + Log hours + Draft invoices; leave Send invoices off
unless you truly want an assistant emailing clients. You'll paste this key into
your assistant's config as PEIL_API_KEY below.
The easy way — no clone, no install (once peil-mcp is published to PyPI):
uvx peil-mcp # runs the latest release on demand
# or, with pipx:
pipx run peil-mcp→ Your launch command is uvx peil-mcp (or pipx run peil-mcp). Skip to
step 3. Everything below is only needed if you're
running from source (e.g. before the first release, or to hack on it).
You need Python 3.11 or newer and a local copy of this mcp-server/ folder.
Check your Python with python3 --version.
Which method? Run
which uv pipxfirst. If you already haveuv, use A — it's the least work. If not,pipx(B) gives you a clean global command. If you have neither and don't want to install tooling, the plain-venvpath (C) works with nothing but the Python that's already on your machine.
Everywhere below, replace /ABS/PATH/TO/mcp-server with the real absolute path
to this folder (run pwd inside it to get it).
uv (no install step)uv builds and runs on demand — nothing to install first:
uv run --directory /ABS/PATH/TO/mcp-server peil-mcp→ Your launch command is: uv run --directory /ABS/PATH/TO/mcp-server peil-mcp
Don't have uv? curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux)
or pip install uv.
pipx (isolated global command)pipx installs the server into its own isolated environment and puts a
peil-mcp command on your PATH:
pipx install /ABS/PATH/TO/mcp-server→ Your launch command is simply: peil-mcp
Don't have pipx? python3 -m pip install --user pipx && python3 -m pipx ensurepath.
venv + pip (works with only stock Python)No extra tooling — just the python3 you already have:
cd /ABS/PATH/TO/mcp-server
python3 -m venv .venv
.venv/bin/pip install .→ Your launch command is: /ABS/PATH/TO/mcp-server/.venv/bin/peil-mcp
(equivalently /ABS/PATH/TO/mcp-server/.venv/bin/python -m peil_mcp).
Use a plain
pip install .(not-e/editable) for running. An editable install relies on a.pthpath hook that can silently fail to load on some setups, givingModuleNotFoundError: No module named 'peil_mcp'. Editable is only needed if you're modifying the server itself — see Local development.
The only thing that changes between assistants is where the config lives. Every MCP client needs the same three things:
command — your launch command from step 2
env — PEIL_API_KEY set to the key from step 1
(optional) PEIL_API_URL — only if you're pointing at a non-production
Peil (see Local development); defaults to
https://api.peil.app/api/v1.
The canonical config block (used by Claude Desktop, Cursor, Windsurf, Cline, and
most others) looks like this — command + args are just your launch command
split on spaces:
{
"mcpServers": {
"peil": {
"command": "peil-mcp", // or "uv", or the venv's python path
"args": [], // e.g. ["run","--directory","/ABS/PATH/TO/mcp-server","peil-mcp"] for uv
"env": { "PEIL_API_KEY": "your-key" }
}
}
}Edit claude_desktop_config.json
(macOS: ~/Library/Application Support/Claude/,
Windows: %APPDATA%\Claude\), add the block above, and restart Claude Desktop.
# pipx / venv (single-command launcher):
claude mcp add peil -e PEIL_API_KEY=your-key -- peil-mcp
# uv:
claude mcp add peil -e PEIL_API_KEY=your-key -- uv run --directory /ABS/PATH/TO/mcp-server peil-mcpAnything after -- is the launch command. Verify with claude mcp get peil
(look for Status: ✔ Connected) and use /mcp in a session to reconnect.
Add the canonical block to .cursor/mcp.json (this project) or
~/.cursor/mcp.json (all projects), then enable peil in
Settings → MCP.
Add the canonical block to ~/.codeium/windsurf/mcp_config.json, then hit
Refresh in the Cascade MCP panel.
Open the extension's MCP Servers → Configure panel and add the canonical
block to cline_mcp_settings.json.
VS Code uses a slightly different shape — servers (not mcpServers) and an
explicit type — in .vscode/mcp.json:
{
"servers": {
"peil": {
"type": "stdio",
"command": "peil-mcp",
"args": [],
"env": { "PEIL_API_KEY": "your-key" }
}
}
}Give it the same command + args + PEIL_API_KEY env. The server speaks MCP
over stdio; if a client can launch a stdio command, it can run Peil.
Once connected, try:
"Where do I stand?" → orientation_snapshot
"Log 6 hours to De Correspondent today for editing work." → log_hours
"Draft an invoice from my unbilled hours for De Correspondent." → draft_invoice
With Send invoices left off your key, an assistant can prepare everything but physically cannot email a client — you send from Peil yourself.
Point the server at a local backend with PEIL_API_URL:
PEIL_API_URL=http://localhost:8000/api/v1 PEIL_API_KEY=your-local-key peil-mcpIf you're modifying the server, an editable install picks up your changes without reinstalling:
.venv/bin/pip install -e ".[dev]"Tests (mocked HTTP, no backend needed — pythonpath = ["src"] in
pyproject.toml makes them independent of the install mechanism):
.venv/bin/pytestCancel a previously scheduled send. Requires invoices:send.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 the required permission but does not explain what happens after cancellation, whether it is reversible, or any other behavioral traits like rate limits or side effects. The output is not described despite an output schema existing.
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 very concise with one sentence and a permission note. No unnecessary words, but it sacrifices completeness. It is front-loaded with the core action.
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 is simple with one parameter and an output schema exists, the description is incomplete. It fails to explain the return value, how to identify the scheduled send, or any post-cancellation effects. For a tool with no annotations, this is inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning to the parameter 'invoice'. However, the description does not mention the parameter at all, leaving the agent without any guidance on what the invoice refers to or how to obtain its value.
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 ('Cancel') and the resource ('a previously scheduled send'), and it distinguishes from sibling tools like schedule_send and send_invoice through the context of cancelling a scheduled operation.
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 a permission requirement ('Requires invoices:send'), which is a usage guideline, but does not explicitly state when to use this tool versus alternatives or when not to use it. The context of cancelling a scheduled send is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a client. Destructive — confirm first.
Blocked (409) if the client has projects or sent/paid invoices. Requires clients:write.
| Name | Required | Description | Default |
|---|---|---|---|
| client | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses destructive behavior and conditions for failure. No annotations exist, so description carries full burden. Could mention if deletion is irreversible or affects related data, but the blocking conditions mitigate risk.
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?
Extremely concise: three short sentences, front-loaded with purpose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simplicity (1 param, no nested objects) and presence of output schema, the description adequately covers purpose, constraints, and authorization. Lacks detail on parameter but overall sufficient.
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 only parameter 'client' is not described beyond the schema's title. With 0% schema description coverage, the description should compensate but does not add any meaning about the parameter (e.g., what value to provide).
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 clearly 'Delete a client.' with a specific verb and resource. It distinguishes from siblings like 'update_client' by implying destruction.
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 warns about destructive nature ('confirm first'), conditions that block deletion (409 if has projects/invoices), and required permission ('clients:write'). This provides clear when-to-use and when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit an existing time entry. Only the fields you pass are changed.
Confirm with the user before editing an entry that's already on a sent/paid invoice (the server blocks it with INVOICE_LOCK). Requires timesheet:write.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | ||
| rate | No | ||
| hours | No | ||
| client | No | ||
| project | No | ||
| entry_id | Yes | ||
| description | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It discloses partial update behavior ('Only the fields you pass are changed') and the invoice lock condition. It does not cover rate limits or other side effects, but the provided info is sufficient for safe operation.
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 with three focused sentences: first states purpose, second adds behavioral nuance, third lists requirement. No extraneous information.
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 7 parameters (1 required) and an existing output schema, the description covers main behaviors and constraints but lacks detailed parameter explanations. It adequately informs about the partial update and invoice lock, but more details on editable fields would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only mentions that only passed fields are changed, without explaining individual parameters like date, rate, hours, etc. The description fails to add meaning beyond the schema for each parameter.
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 'Edit an existing time entry', specifying the verb (edit) and resource (existing time entry). It distinguishes from sibling tools like 'log_hours' which creates new entries.
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 advises confirming with the user before editing entries on sent/paid invoices due to a server block, providing clear contextual guidance. It also lists the required permission 'timesheet:write', but does not explicitly state when not to use the tool or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the user's custom reminder email copy and schedule.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'Show'. It does not disclose that the tool is read-only, whether authentication is needed, or what happens if no copy exists. The description carries the full burden but is insufficient.
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 fluff. It could be slightly expanded to add context without losing conciseness.
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 zero parameters, existence of an output schema, and sibling tools, the description is minimally adequate. However, it could better explain the purpose (e.g., preview vs. sending).
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 zero parameters, so the description cannot add meaning beyond the schema. Baseline 4 applies per guidelines.
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 shows the user's custom reminder email copy and schedule, using a specific verb and resource. It distinguishes itself from siblings like 'send_reminder' which actually sends the reminder.
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 versus alternatives like 'send_reminder' or 'schedule_send'. Agents must infer from the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log worked hours for a client in Peil's timesheet.
Omit rate to use the client's default rate. date is ISO YYYY-MM-DD.
Requires the timesheet:write key permission.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | ||
| rate | No | ||
| hours | Yes | ||
| client | Yes | ||
| project | No | ||
| description | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must fully convey behavior. It mentions required permission ('timesheet:write key'), which is important. But does not disclose idempotency, whether it overwrites existing entries, or any side effects beyond basic creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: first states purpose, second explains key parameter details, third states permission requirement. No redundancy or 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 6 parameters and 4 required, description covers basic usage. However, lacks details on output (though output schema exists), error conditions, or concurrency behavior. Slightly incomplete for a tool with this complexity, but acceptable with output schema present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description adds value by detailing 'rate' behavior and 'date' format. However, it does not explain 'client', 'hours', 'description', or 'project' beyond their names, leaving some parameters semantically underdocumented.
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?
Clearly states the action (log), the resource (worked hours for a client), and the system (Peil's timesheet). Distinguishes from sibling 'edit_hours' by using 'log' instead of 'edit', implying creation of new entry.
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?
Provides explicit guidance on optional 'rate' parameter (omit to use default) and date format (ISO YYYY-MM-DD). However, does not explicitly contrast with sibling 'edit_hours' or specify when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Schedule a DRAFT invoice to be emailed at a future time. Client-facing.
scheduled_at is an ISO datetime (e.g. 2026-07-20T09:00:00). Only call this
when the user has explicitly confirmed sending this invoice at this time.
Requires invoices:send.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice | Yes | ||
| scheduled_at | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. Mentions 'Client-facing' and permission requirement. However, lacks details on side effects (e.g., what happens to draft state, whether scheduling can be modified) and does not address edge cases like past scheduled_at. Provides basic but not comprehensive transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences covering purpose, param format, usage condition, and permission. Front-loaded and efficient. Minor improvement could be grouping permissions with usage condition for better structure.
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 output schema exists (so return values not needed) and sibling tools provide context, the description adequately covers prerequisites (draft invoice, explicit confirmation) and distinguishes from related actions. Still, could explicitly mention that invoice must be in draft state and not already scheduled.
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 has 0% coverage; description partially compensates by explaining `scheduled_at` format with an example. However, `invoice` parameter is not described (likely an ID or reference). Baseline 3 is appropriate, but could be improved by clarifying `invoice`.
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?
Clearly states the verb 'Schedule' and resource 'DRAFT invoice to be emailed at a future time'. Distinguishes from siblings like 'send_invoice' (immediate) and 'cancel_scheduled_send' (cancellation), making the purpose unambiguous.
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 states when to call ('only when user has explicitly confirmed') and includes a permission requirement ('Requires invoices:send'). Could further clarify when not to use (e.g., if invoice is already sent), but overall guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send an invoice to the client BY EMAIL. Irreversible and client-facing.
invoice is a numeric id or invoice number. Only call this when the user has
explicitly confirmed sending this specific invoice. Requires invoices:send.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. States irreversible and client-facing nature, plus permission requirement. Provides sufficient behavioral context.
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?
Extremely concise, front-loaded with key info, every sentence adds value. No fluff.
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 send tool with output schema, description covers purpose, usage, parameter, and behavior. Missing details on email validation or confirmation flow, but adequate.
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?
Parameter 'invoice' has 0% schema coverage, but description adds meaning: numeric id or invoice number. Clarifies input beyond schema type.
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 'Send', resource 'invoice', and medium 'BY EMAIL'. Distinguishes from sibling tools like send_reminder and schedule_send.
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 states when to call (only after explicit user confirmation) and permission requirement. Could mention alternatives but not needed given clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Email a payment reminder for a sent/overdue invoice. Irreversible, client-facing.
Only call this when the user has explicitly confirmed reminding about this specific invoice. Requires invoices:send.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses irreversibility and client-facing nature, which are critical behavioral traits. It also mentions permission requirement. No annotations provided, so description carries full burden and does so adequately.
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, highly concise. The first sentence captures the action and key traits; the second adds usage guidance. No extraneous 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?
The tool is simple with one parameter and an output schema. The description covers purpose, usage condition, and consequences. It does not mention output format, but that is likely in the output schema. Slightly lacking in parameter details, but overall adequate.
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?
Only one parameter (invoice) with 0% schema description coverage. The description adds no specific guidance on the parameter's format, source, or validation. The context implies it's an invoice identifier, but the description should compensate for the schema gap.
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 the exact action: email a payment reminder for sent/overdue invoices. It clearly distinguishes from siblings like send_invoice or schedule_send by specifying the reminder context and noting irreversibility.
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 states when to use (only after user confirmation) and a prerequisite (requires invoices:send permission). Does not explicitly mention when not to use or alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a client's details. Only the fields you pass change. Requires clients:write.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| No | |||
| client | Yes | ||
| default_rate | No | ||
| payment_terms_days | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses partial update behavior and the required permission, but does not mention other behaviors such as idempotency, side effects, rate limits, or what happens when required fields are omitted. Adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no fluff. Every sentence adds value: purpose and partial update rule. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, 1 required, and no enums, the description misses contextual details like return format (though output schema exists), usage scenarios, and parameter interdependencies. Adequate for a simple update 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 description coverage is 0%, so description should compensate. However, it only states that changes are field-specific and lists no parameter semantics (e.g., default_rate meaning). The schema provides titles but no descriptions, leaving agents to guess parameter meanings.
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 'update' and resource 'client details', and distinguishes from sibling tools like delete_client. It also specifies the partial update behavior ('Only the fields you pass change'), leaving no ambiguity about the tool's purpose.
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 says when to use (update client details) and that it requires clients:write permission, but does not explicitly state when not to use or mention alternative tools. The context of sibling tools provides implicit differentiation, but explicit guidance is lacking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct action (e.g., cancel_scheduled_send vs schedule_send, delete_client vs update_client). No significant overlap.
All tool names follow a consistent verb_noun pattern with underscores, making them predictable and easy to understand.
9 tools is well-scoped for a time tracking and invoicing server, covering key operations without being bloated.
Missing essential CRUD operations like create_client and get_invoices; the focus on sending/managing invoices and timesheet entries leaves gaps in client and invoice lifecycle management.
Invoicing you drive by talking to your AI: log time, raise invoices and track what's owed via MCP.
Time tracking and invoicing for AI agents and their humans: track, log and bill work by agent.
Connect Claude AI to UluP Spaces via MCP — create projects, nodes, and tasks with OAuth 2.0.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Luminc/peil-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
