Field Service Business Platform by Doing Work

costs_job

Job costing for one job: contract, invoiced, collected and revenue against labor (approved and pending time at each entry's cost rate), materials at cost, expenses and Doing Work fees, with profit and margin. Owner or office; needs seeing costs and prices.

Input Schema

Name	Required	Description	Default
`job_id`	Yes

Output Schema

Name	Required	Description
`kind`	Yes
`job_id`	Yes
`margin`	Yes	profit / revenue, 4 decimals; null while revenue is 0.
`status`	Yes
`summary`	Yes
`currency`	Yes
`tax_minor`	Yes	Sales tax on those invoices; it is not the shop's money, so revenue leaves it out.
`cost_minor`	Yes	labor + materials + expenses + fees.
`fees_minor`	Yes	Doing Work fees taken from the job's payments.
`customer_id`	Yes
`occurred_at`	Yes
`profit_minor`	Yes	revenue - cost. Can be below 0.
`labor_minutes`	Yes	Approved and pending minutes on the job (running clocks not counted).
`revenue_minor`	Yes	invoiced - tax - refunded. What the job earned so far.
`contract_minor`	Yes	Signed quote totals (tax included) plus approved change orders.
`expenses_minor`	Yes	Expenses on the job in the shop's currency, as entered (receipt totals).
`invoiced_minor`	Yes	Sent and later invoices, tax included; drafts and voided invoices left out.
`refunded_minor`	Yes	Refunds and lost disputes on the job's payments.
`running_clocks`	Yes
`unbilled_minor`	Yes	contract - invoiced: signed work not yet invoiced (tax included both sides).
`collected_minor`	Yes	Paid through Doing Work, net of refunds, lost disputes and tips, plus invoices recorded as paid outside.
`labor_cost_minor`	Yes	Approved and pending minutes at each entry's copied cost rate, rounded half up.
`uncosted_minutes`	Yes	Minutes with no labor cost rate set; they count as zero cost. Set rates with timesheets.setRate.
`uncosted_materials`	Yes	Material lines with no unit cost; they count as zero cost.
`draft_invoices_minor`	Yes	Amount in minor units of the currency (cents).
`expenses_by_category`	Yes	category -> minor units.
`materials_cost_minor`	Yes	Materials used, quantity x unit cost, rounded half up per line.
`labor_pending_minutes`	Yes
`materials_price_minor`	Yes	The same materials at their recorded prices (what they would bill at).
`labor_pending_cost_minor`	Yes	Amount in minor units of the currency (cents).

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 1, 2026

TDQS

A3.8/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does real work: it discloses the permission prerequisite ('needs seeing costs and prices', 'Owner or office') and precisely how the numbers are derived (approved and pending time at each entry's cost rate, materials at cost, Doing Work fees). It stops short of stating that this is a non-mutating read or how it behaves for jobs with incomplete data.

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?

It is compact and front-loaded: the first phrase names the operation and scope, then the cost components, then the permission note. The middle enumeration is dense and clause-heavy, but every element is substantive rather than filler.

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?

An output schema exists, so return structure needn't be described, and the description covers the computation inputs, the permission gate, and the resulting metrics (profit and margin). For a single-parameter read-style reporting tool this is sufficient to call it correctly.

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 coverage is 0% for the single job_id parameter, so the schema contributes nothing and the description must compensate. 'For one job' does imply the id identifies a single job, but it adds no detail on format (UUID), lookup behavior, or what an invalid/foreign job identifier does.

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 gives a specific verb-plus-resource ('Job costing for one job') and enumerates exactly which financial components are rolled up, so an agent knows this is a per-job cost/profit breakdown rather than a list. It only implicitly differentiates from the sibling costs_jobs via 'for one job' — it never names the plural tool outright.

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?

Usage is implied by the content (per-job profit and margin reporting) and the closing clause 'Owner or office; needs seeing costs and prices' signals the audience and permission prerequisite. There is no explicit when-to-use vs costs_jobs, no exclusions, and no statement of what happens if the job has no costs.

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

All Field Service Business Platform by Doing Work tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?