Job cards for trades and field service: hours and materials per job, open to invoiced.
Scored across 11 tools
Every tool targets a distinct operation: lifecycle management, logging labor/materials, printing, summarizing, and license functions. Even similar tools like get, list, and print have clearly different purposes and outputs.
Most tools follow a clear job_card_<action> pattern, making the set predictable. Minor deviations like job_card_summary and license_status break the strict verb pattern but remain understandable.
Eleven tools is well-scoped for a job card management system: nine core card/entry operations plus two license tools. Each tool has a real purpose and none feel redundant.
The core job card lifecycle is covered: create, read, list, delete, update status, log labor/materials, print, and summarize. Missing edit/update of card details or correction of individual logged entries is a minor gap, but the workflow is largely complete.
Open a job card for a job your crew is taking on and return its JC-YYYY-NNNN number: the client, the site, what the job is, the currency and when it is scheduled. Free tier: 10 active cards; archiving a finished job frees its slot.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| site | Yes | Where the job is, e.g. 14 Nowa Street, flat 3 | |
| client | Yes | Who the job is for, e.g. Kowalski bathroom refit, or Acme Ltd | |
| currency | Yes | ISO code the rates and prices are in | |
| description | Yes | What the job is, e.g. Replace the consumer unit and certify | |
| scheduled_date | No | The date the crew is due on site, YYYY-MM-DD. May be in the future; it is a plan, not a log |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say the operation is not read-only, not idempotent, and not destructive. The description adds real behavioral context: it returns a JC-YYYY-NNNN number, and it discloses the 10-active-card free-tier limit with the fact that archiving frees a slot. It does not cover auth or error-on-limit behavior, but the quota context is genuinely useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The first clearly states purpose, inputs, and return value; the second adds the practical quota constraint. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-parameter create operation with no output schema, the description covers the required fields, the ID return format, the scheduling intent, and the active-card limit. It does not specify behavior when the limit is reached or the full response shape, but the core calling context is 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 83%, so the schema already explains most parameters. The description mirrors client, site, description, currency, and scheduled_date in plain language but adds no deeper meaning, defaults, or edge-case details, and it omits the optional note 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 uses a concrete verb ('Open') on a specific resource ('job card'), states the returned JC-YYYY-NNNN identifier, and lists the key fields. Among siblings like job_card_get and job_card_list, it is unmistakably the creation 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?
It gives clear context: use this when your crew is taking on a job and needs an active job card. It does not explicitly name alternatives or state when not to use it, but the free-tier active-card limit implies lifecycle management around archiving.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a job card entered by mistake. One with labor or materials logged is refused, naming what it holds, because deleting it would lose the record of work done: archive it instead. The JC number is never reissued.
| Name | Required | Description | Default |
|---|---|---|---|
| card | Yes | The job card id, e.g. JC-2026-0003, or the client name when only one card has it |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already flags mutating behavior, but the description adds crucial context beyond that: non-empty cards are refused and the refusal names what the card holds, deletion would lose work records, and the JC number is never reissued. This is exactly the kind of behavioral nuance annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: purpose first, then the critical refusal and archival guidance, then the irreversible consequence. There is no filler or repetition of schema details, and the most decision-relevant information is 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?
For a simple one-parameter destructive tool with no output schema and no nested objects, the description covers the operation, the boundary condition, the alternative action, and the long-term consequence. An agent has everything needed to invoke it correctly and to avoid destructive misuse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the single 'card' parameter is fully documented in the schema. The description adds no new parameter-level meaning beyond reinforcing that JC numbers are involved and that deletion is permanent, which does not materially improve on the existing schema documentation.
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 specific action: deleting a job card entered by mistake, with the scope constraint implied by the title ('empty'). It also distinguishes the refusal case (labor/materials logged) from the intended use, making the tool's purpose unambiguous relative to siblings like job_card_update_status or job_card_log_labor.
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 explicitly tells the agent when to use this tool: for a job card entered by mistake and therefore empty. It also gives a clear exclusion rule—cards with logged labor or materials are refused—and directs the agent to archive instead, providing actionable guidance for the alternative path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one job card in full by JC number or client: every labor entry and every material used, the hours per worker, and the running totals -- labor, materials and grand total -- as integer cents with formatted amounts. Reads only.
| Name | Required | Description | Default |
|---|---|---|---|
| card | Yes | The job card id, e.g. JC-2026-0003, or the client name when only one card has it |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'Reads only' while the annotation readOnlyHint is false. This is a direct contradiction: the description claims the tool has no side effects, but the annotation indicates it might not be read-only. An agent would be misled about the tool's mutating behavior. This is a serious inconsistency and must be flagged as an annotation contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core purpose ('Read one job card in full') and then lists the specific data returned. It is concise, with no filler or redundancy, and every element earns its place. The structure is clear and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and no output schema, the description adequately covers what is returned (labor entries, materials, hours, totals, formatting). It does not mention error conditions or behavior when the card is not found, but for a read tool this is a minor gap. The main incompleteness stems from the annotation contradiction, which is already penalized under behavioral transparency.
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 single parameter 'card' is fully documented in the schema, including the two acceptable forms (JC number or client name). The description repeats this information ('by JC number or client') but adds no new semantics. With 100% schema description coverage, the baseline is 3, and the description does not elevate it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read') and resource ('one job card') and details exactly what is returned: every labor entry, material used, hours per worker, and running totals. It clearly differentiates from siblings like job_card_list (multiple cards) and job_card_summary (summary-only) by emphasizing 'in full'. The 'Reads only' phrasing also signals a non-mutating action, which is a distinct 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 implies this is the tool for retrieving a single job card in full, but it does not explicitly mention when to use it versus job_card_list or job_card_summary. No alternatives are named, and no exclusions are provided. The usage context is inferred from the description's focus on full detail rather than stated outright.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List job cards newest first: client, site, status, hours logged, and the labor, materials and grand totals in cents. Filter by status and by client. Totals are kept per currency, never mixed.
| Name | Required | Description | Default |
|---|---|---|---|
| client | No | Only cards whose client contains this text, case-insensitive | |
| status | No | Only cards at this status: open, in_progress, done, invoiced, archived |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
All four annotation hints are false/default, so the description carries the behavioral disclosure burden. It does disclose real behavior: descending time ordering, totals in cents, and a per-currency guarantee that totals are never mixed. However, it is silent on pagination/limits, whether archived cards appear when no status filter is given, and the response shape.
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: list content/order/units, the filters, and the currency invariant. The core behavior is front-loaded in the first sentence with zero filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does specify the returned fields and denominations, which covers the main return contract. Still, for a tool that lists potentially many records, the absence of any pagination or size-limit information and the unspecified default inclusion of archived cards are material gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; both parameters are already documented (client = case-insensitive contains match; status = closed set of five values). The description only mirrors that filtering by status and client is possible, adding no meaning beyond the schema, so the baseline 3 applies.
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 opens with a specific verb-resource pair ('List job cards') and adds ordering ('newest first') plus the exact fields returned, so an agent can tell what the tool does. It is implicitly distinguishable from siblings like job_card_get (single card) and job_card_summary (aggregate), but it never names or contrasts them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool — when an agent needs an ordered, filterable set of job cards with detailed totals — but it gives no explicit when-to-use or when-not-to-use guidance and points to no alternative for other needs. No exclusions or preconditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log hours worked on a job card: who did the work, the day, the hours and the hourly rate in whole cents, with a note on what was done. The line value is hours times rate, rounded half-up to the cent, fixed the moment it is logged.
| Name | Required | Description | Default |
|---|---|---|---|
| card | Yes | The job card id, e.g. JC-2026-0003, or the client name when only one card has it | |
| date | Yes | The day the work was done, YYYY-MM-DD. A future date is refused | |
| note | No | What was done, e.g. First fix, kitchen ring main | |
| hours | Yes | Hours worked, to the hundredth, e.g. 7.5 or 3.25. One entry is one worker's day at most | |
| worker | Yes | Who did the work, e.g. Anna | |
| rate_cents | Yes | The hourly rate in whole cents. 4500 is 45.00 an hour |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the server-side line value calculation ('hours times rate, rounded half-up to the cent, fixed the moment it is logged'), which goes beyond the annotations. However, it does not mention potential side effects, whether records are appended, or any permission or reversal details, leaving some behavioral gaps.
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 purposeful sentences: the first states what the tool does and what inputs it takes; the second clarifies the calculation and persistence behavior. No filler or redundant wording.
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 6-parameter write operation with no output schema, the description covers the main behavior, input scope, and calculation semantics. The schema fills parameter constraints. Missing explicit guidance on return values or side-effect confirmation is a minor gap given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter. The description adds a useful formula relating hours and rate_cents, but does not significantly deepen per-parameter semantics beyond what the schema provides.
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 opens with a specific verb and resource: 'Log hours worked on a job card', and enumerates exactly what is logged (worker, day, hours, rate, note). It is clearly distinguishable from siblings like job_card_log_material and job_card_update_status.
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 makes the use case clear—logging labor hours—but does not explicitly contrast with job_card_log_material or mention when not to use the tool. While the purpose is implied by naming and content, there are no explicit alternative routes or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log materials used on a job card: the item, the day it went in, the quantity and the unit cost in whole cents. The line value is quantity times unit cost, rounded half-up to the cent, fixed the moment it is logged.
| Name | Required | Description | Default |
|---|---|---|---|
| qty | Yes | How many, to the thousandth, e.g. 2 or 0.5 | |
| card | Yes | The job card id, e.g. JC-2026-0003, or the client name when only one card has it | |
| date | Yes | The day it went in, YYYY-MM-DD. A future date is refused | |
| item | Yes | What went into the job, e.g. Copper pipe 15mm, or Consumer unit 10-way | |
| note | No | ||
| unit_cost_cents | Yes | What one costs in whole cents. 1299 is 12.99 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=false and destructiveHint=false, which are minimally informative. The description adds meaningful behavioral detail: line value is quantity times unit cost, rounded half-up, and fixed at the moment of logging. This goes beyond the structured hints, though it does not describe response or duplicate handling.
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 filler. The first states the action and operands, the second defines the key calculation. The information is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the inputs and the core value formula, which is enough for a basic call. However, there is no output schema and no mention of side effects, response, or whether repeated logging creates duplicates. It leaves some operational questions unanswered.
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 83%, so the schema already documents most parameters. The description adds the qty × unit_cost relationship and the rounding rule, which helps, but it does not clarify the undocumented 'note' parameter. Baseline 3 is appropriate given high schema coverage.
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 names a specific verb and resource: 'Log materials used on a job card', and enumerates the captured fields. It is clearly distinct from the sibling job_card_log_labor tool, so an agent can tell them apart without inspecting schemas.
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 states what the tool does but gives no when-to-use guidance, exclusions, or alternatives. Since job_card_log_labor exists as a sibling, the description should have mentioned that labor logging belongs to that tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a job card ready to print and hand to the client: the labor, the materials, the totals and a signature line for client sign-off. Markdown, or self-contained HTML that needs nothing from the network. Writes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| card | Yes | The job card id, e.g. JC-2026-0003, or the client name when only one card has it | |
| format | No | markdown (default) or html. The HTML carries its own styling and references nothing external |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no useful annotations (all hints false), the description carries the burden of side-effect disclosure, and it delivers with 'Writes nothing.' It also adds a meaningful behavioral detail: the HTML output is self-contained and needs nothing from the network, which is beyond what the schema states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. It front-loads the core purpose, then lists contents, output formats, and the critical side-effect guarantee, with every sentence earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter rendering tool, the description covers purpose, accepted formats, and side effects, and the schema covers parameter details. It does not specify lookup/error behavior or the exact return representation, but the Markdown/HTML wording sufficiently implies the returned content, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well documented. The description adds only a minor reinforcement about self-contained HTML and the card-to-sign purpose, but it does not materially extend the semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: render a job card for printing and client signature, including labor, materials, totals, and signature line. It clearly distinguishes itself from siblings like job_card_get, job_card_list, or job_card_create by emphasizing the print/sign-off purpose and the read-only output formats.
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 gives a clear context for use: render a job card ready to print and hand to the client for sign-off. It does not explicitly contrast with alternatives such as job_card_get, and it lacks 'when not to use' guidance, but the intended use case is evident enough for an agent to select it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hours and value for a day or a week: the job cards touched, the hours per worker, and the labor, materials and total value, kept per currency. A week runs Monday to Sunday. Touched means a labor or material entry dated inside the window.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | A date inside the window, YYYY-MM-DD. Default today | |
| span | No | day (default) is the date itself; week is the Monday to Sunday containing it |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With all annotation hints set to false, the description carries the burden of explaining behavior. It meaningfully adds the 'Touched means a labor or material entry dated inside the window' rule and the Monday-to-Sunday week definition, which go beyond the schema. It does not explicitly claim read-only behavior, but the summary intent makes mutation unlikely.
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 with no filler. The core summary output is front-loaded, and the additional sentences define the only genuinely ambiguous terms: the week boundary and the word 'touched'. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description listing the return categories (job cards touched, hours per worker, labor/materials/total value per currency) is important and largely sufficient. It stops short of specifying exact response structure or edge cases like empty windows, but an agent can select and call the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds extra semantics beyond the schema by explaining that a week runs Monday to Sunday and by defining what counts as a touched job card. This helps an agent correctly interpret the date and span parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: summarize job cards for a day or weekcars, and clearly lists the output dimensions: touched job cards, hours per worker, and labor/materials/total value by currency. This differentiates it from sibling lookup tools like job_card_get and job_card_list by its aggregate nature.
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 intended use is implied: use this when you need hourly or monetary totals for a day or week. It also clarifies the date-window semantics, including that a week is Monday-to-Sunday. However, it never explicitly states when not to use it or points to alternatives such as job_card_list for raw itemized data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move one job card exactly one step: open, in_progress, done, invoiced, archived, stamping the date and an optional note into its history. A skipped or backwards step is refused and nothing is written. Archiving a finished job frees a free-tier slot.
| Name | Required | Description | Default |
|---|---|---|---|
| card | Yes | The job card id, e.g. JC-2026-0003, or the client name when only one card has it | |
| date | No | The date to stamp the step with, YYYY-MM-DD. Default today | |
| note | No | ||
| status | Yes | The next step for this card: open, in_progress, done, invoiced, archived. in-progress is accepted too |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals important behavior beyond the bare annotations: the transition is atomic ('nothing is written'), history is stamped with date/note, and archiving a finished job frees a free-tier slot. These are non-obvious side effects and constraints that the annotations do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences carry the core action, the transition rule, and the side effect with no filler. The most identifying constraint ('exactly one step') is front-loaded before the status list.
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 mutation tool with no annotations and no output schema, the description covers the state machine, failure behavior, history side effect, and plan impact. It still leaves minor ambiguity about what a 'finished job' is and what the response looks like, but nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, and the description adds meaning to the parameters it mentions: note is 'stamped into history', date is the stamp date, and status is constrained by the one-step rule. It does not fully elaborate every parameter, but it goes beyond the schema's bare property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the specific verb ('Move'), the resource ('one job card'), and the exact allowed status sequence, making it immediately clear what the tool does. It is also easy to distinguish from sibling tools like job_card_create, job_card_delete, and job_card_log_labor because it is scoped to a single status transition.
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 use case is clearly conveyed: advance a job card by exactly one step in a defined order. The refusal of skipped/backwards steps tells the agent what not to attempt, though it does not explicitly name alternatives such as job_card_create or job_card_log_* as the right tools for other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn Pro on for this connection with key, an MCPL1.. issued at checkout for this server or the bundle. Data under your token stays; a wrong or expired key changes nothing. license_status confirms it.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | License key from checkout, MCPL1.<payload>.<signature> |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only and not destructive, and the description adds useful behavioral detail: existing data under the token stays, and a wrong or expired key changes nothing. This goes beyond the annotation hints by explaining failure semantics and safety of the 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 two sentences with no filler. It front-loads the core action, then gives the key format and safety guarantees, and closes with the verification tool. Every sentence contributes essential 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?
For a single-parameter activation tool with annotations covering the safety profile, the description is complete: it states what the tool does, what input is needed, what happens on failure, and how to confirm success. There is no missing critical information for an agent to call it correctly.
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 schema already documents the key parameter and its format with 100% coverage. The description adds meaning by specifying that the key must be issued at checkout for this server or the bundle, which clarifies validity requirements not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: it 'turns Pro on' for the connection using a license key. It also distinguishes itself from the sibling license_status tool by saying license_status confirms the activation. This leaves no ambiguity about what the tool accomplishes.
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 clear context for use: the key must be an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. It does not explicitly list exclusions or alternative tools, but it does reference license_status as the confirmation path, giving the agent a sense of the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report this endpoint's licence state for your token as JSON: the product, the tier free or pro, why it is not Pro, and the checkout URL. Call it to explain a free-tier refusal. No arguments, nothing changes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context beyond annotations by specifying the JSON response contents and stating 'nothing changes,' reinforcing the read-only nature of the call.
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 dense sentences cover output, purpose, usage context, and side-effect guarantee. Every sentence earns its place and the most important information is 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?
With no output schema, the description sufficiently describes the return value. With no parameters, annotations covering safety, and a clear use case, nothing essential is missing for an agent to invoke this tool correctly.
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 and the schema already fully documents that fact. The description explicitly says 'No arguments,' which is accurate and reinforces the schema without needing further elaboration.
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 begins with a specific verb ('Report') and a precise resource ('this endpoint's licence state for your token'), and enumerates the exact output fields: product, tier, reason, and checkout URL. This clearly distinguishes it from sibling tools like license_activate.
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 explicitly states when to call it: 'Call it to explain a free-tier refusal.' This is clear contextual guidance, though it does not name alternatives or explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
job_card_createjob_card_deletejob_card_getjob_card_listjob_card_log_laborjob_card_log_materialjob_card_printjob_card_summaryjob_card_update_statuslicense_activatelicense_statusJob orders for trades and field work: parts, labour, status, completion report, invoice payload.
Field service management for trades: clients, jobs, estimates, invoices, schedule and reports.
Manage jobs, customers, scheduling, estimates and invoices for a field service business.
Field service reports: hours, materials, sign-off, and the invoice the visit turns into.
Add one secure layer between your agents and this server.
