Job cards for trades and field service: hours and materials per job, open to invoiced.
Scored across 11 tools
Each tool targets a distinct action on job cards or licensing: create, delete, get, list, log labor, log material, print, summary, status update, license activate, license status. There is no overlap in purpose, and the descriptions clarify boundaries clearly.
All tools follow a consistent verb_noun snake_case pattern (job_card_create, job_card_get, license_activate). Even license tools align with the same verb_noun style, and no mixed conventions or vague verbs appear.
11 tools is well within the ideal 3-15 range for a domain-specific server. Each tool serves a clear purpose, covering job card lifecycle, logging, reporting, and licensing without redundancy.
The surface covers creation, reading, listing, logging labor/materials, printing, summary, status transitions, and licensing. A minor gap is the lack of an edit tool for core job card fields (client, site, etc.) after creation, but the lifecycle is otherwise 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?
With no annotations provided, the description carries the behavioral disclosure burden. It clearly states the create side effect, the exact return format, and a meaningful constraint (10 active cards, archiving frees a slot). It stops short of describing what happens at the limit or permission requirements, but the key behavioral traits are honestly and usefully exposed.
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, zero fluff: the first front-loads the action, return value, and required data; the second adds a genuinely useful constraint. Every phrase 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 no-annotation, no-output-schema create tool with 6 params, the description covers the essential contract: what it creates, what it returns, and the card-limit context. It does not explain error behavior at the cap or the meaning of 'note', but the high schema coverage and clear return format make it largely complete for correct invocation.
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% (5 of 6 parameters documented), so the baseline is 3. The description lightly reflects the schema fields by listing 'the client, the site, what the job is, the currency and when it is scheduled', but it adds no new syntax, format detail, or edge-case meaning beyond what the schema already provides. The optional 'note' parameter remains undocumented in both.
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 action ('Open a job card'), the resource, and the return value ('JC-YYYY-NNNN number'), and lists the data it takes: client, site, description, currency, scheduled date. This clearly distinguishes it from siblings like job_card_update_status and job_card_delete, which are different operations on the same resource.
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?
Usage is implied: create a card when your crew takes on a job. The free-tier note ('10 active cards; archiving a finished job frees its slot') hints at capacity constraints, but no alternatives are named and there is no explicit 'use X instead when...' guidance. An agent would infer when to call it, but not formally.
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?
With no annotations provided, the description carries the burden of behavioral disclosure. It clearly states that deletion is refused for cards with labor or materials, that the refusal names what it holds, and that the JC number is never reissued. This covers the key safety and side-effect behaviors. It does not mention whether deletion is permanent or if any confirmation is needed, but given the explicit refusal logic, it is close to complete.
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 efficient: three sentences, with the primary purpose in the first sentence, and key constraints and consequences in the following ones. It is slightly verbose in the second sentence but each clause adds important information. 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?
Given a single parameter, no output schema, and no annotations, the description covers the essential context: when to use, what happens on refusal, and the permanent consequence of the JC number. It is missing the return format on success, but for a simple delete operation this is not critical. It is complete enough for an agent to correctly decide and call.
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 provides a clear description of the 'card' parameter, including an example format and an alternative (client name). The description adds no additional parameter-specific details, but with 100% schema coverage, a score of 3 is the baseline. It is adequate.
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 (delete), the resource (job card), and the specific condition (empty) that must be met for the delete to succeed. It distinguishes from siblings like job_card_update_status or job_card_create by focusing on deletion and by mentioning what it is not for (cards with logged work).
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 use this tool: to delete a job card entered by mistake and only if it has no logged labor or materials. It also provides an explicit alternative: archive the card instead if it has content, and warns that the JC number is never reissued, which prevents misuse.
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?
There are no annotations, so the description carries the full burden; it explicitly states 'Reads only,' disclosing that this is a non-mutating operation. It also reveals return characteristics — each entry, hours per worker, and running totals 'as integer cents with formatted amounts' — which is useful behavioral context beyond the schema.
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, front-loaded sentence that immediately names the action and resource, then enumerates the returned content without wasted words. The final 'Reads only' is compact and earns its place as a safety-relevant clarification.
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 and no annotations, the description covers the essentials: what is read, how the card is identified, and exactly what the return includes. It does not cover error behavior or ambiguous-client handling beyond the schema note, but for a simple read operation the definition is substantially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the only parameter 'card' already explains the JC number or client name format and the single-card disambiguation rule. The description's phrase 'by JC number or client' echoes the schema rather than adding new semantic content, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource — 'Read one job card in full' — with a clear scope: by JC number or client, returning labor entries, materials, hours per worker, and running totals. It also says 'Reads only,' distinguishing it from mutating siblings like job_card_create, job_card_log_labor, and job_card_update_status, and from job_card_list which reads multiple cards.
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 its use case: you need the full detail of a single job card, not a summary or list. However, it never names alternatives or says when not to use it — e.g., job_card_summary for totals or job_card_list for browsing — leaving the choice partly to inference.
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?
With no annotations provided, the description carries the full burden. It does disclose sorting ('newest first') and a currency-mixing rule ('Totals are kept per currency, never mixed'), which are useful behavioral traits. However, it does not mention pagination, result limits, error behavior, or explicitly confirm read-only status (though implied). The added context is moderate but not comprehensive for a list tool.
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, information-dense sentence that front-loads the core action ('List job cards newest first') and then lists fields and filters. Every clause contributes value: sorting, field list, filter capabilities, and the currency rule. It is slightly long but efficient and well-organized, with no 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?
Since there is no output schema, the description appropriately lists the returned fields (client, site, status, hours logged, totals) and specifies ordering and currency handling. It omits potential details like pagination or response limits, but for a simple list tool with two optional filters, the provided information is largely sufficient for correct invocation. The only gap is a lack of mention of any default limits or paging behavior.
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%, with both parameters (client and status) fully described in the schema. The description only restates that filtering is possible without adding extra meaning (e.g., case-insensitivity is already in the schema, and the status enum is also in the schema). Thus the description adds no value beyond what the schema already provides, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('List job cards') and resource, and enumerates the exact fields returned (client, site, status, hours, totals in cents). It distinguishes itself from sibling tools like job_card_get (single retrieval) and job_card_create by its list nature and filter options. The verb and resource are precise, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (use when you need a list of job cards) and mentions filters by status and client, but it does not explicitly contrast with alternatives like job_card_summary or job_card_get, nor does it state when NOT to use it. The context is clear but lacks exclusions or direct sibling comparisons, leaving the agent to infer routing.
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?
With no annotations, the description carries the full burden and does disclose a key behavior: the line value is hours times rate, rounded half-up to the cent and fixed at log time. However, it does not disclose side effects on the job card, whether the operation is append-only, permission requirements, or failure behavior, which are significant for a write 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?
Two sentences contain all essential information with no filler. The core operation and fields are front-loaded, and the important value-calculation rule is stated clearly at the end.
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 that all parameters are fully described in the schema and the description clarifies the value calculation, an agent has enough to construct a valid call. Missing details like response format, confirmation of what was logged, and side effects on the job card are gaps, but they do not prevent correct invocation for the primary use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents each parameter. The description only loosely restates the fields ('who did the work, the day, the hours and the hourly rate') and adds no new per-parameter meaning beyond what the schema provides; the rounding detail is about output/value behavior rather than parameter interpretation.
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?
States a specific verb ('Log'), a specific resource ('hours worked on a job card'), and the relevant payload fields. It is naturally distinguishable from the sibling job_card_log_material by the labor vs. material framing.
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 it—for hourly labor entries rather than material entries—but it does not explicitly state when to use job_card_log_labor versus job_card_log_material or other siblings. There is no when-not-to-use guidance, so the agent must infer the intended selection from the title and sibling names.
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?
The description discloses the rounding rule (half-up to cent) and that the line value is fixed at log time, which is valuable behavioral context beyond the schema. With no annotations, it carries the burden well, though it doesn't discuss side effects or permissions.
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, front-loaded with the action, and no unnecessary detail. Every phrase contributes to understanding the tool's function and calculation.
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 logging operation with no output schema, the description covers the essential behavior: what is logged and how the line value is computed. It doesn't mention success/error responses, but that's not critical given the schema covers parameters.
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 high (83%), so the baseline is 3. The description adds the line value formula (quantity times unit cost) and clarifies that unit_cost_cents is in whole cents, providing meaning beyond the schema's parameter 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 clearly states the action (log materials) and the key fields (item, date, quantity, unit cost). It's unambiguous about the resource and purpose, but it doesn't explicitly mention the sibling tool for labor, so it doesn't fully distinguish from 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 implies usage for materials logging, but provides no explicit guidance on when to use it vs. job_card_log_labor. There's no mention of alternatives or exclusions, relying on the tool name to convey the distinction.
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 annotations provided, the description carries the full burden and does so well. 'Writes nothing' explicitly rules out side effects, and 'self-contained HTML that needs nothing from the network' discloses output characteristics. It also enumerates what the rendered card contains.
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 purpose, then efficiently conveys output contents, formats, network independence, and side-effect absence.
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 low-complexity tool with two parameters and no output schema, the description fully covers what the agent needs: the rendered output types, the content included, and the fact that no state changes occur. No critical invocation or outcome information 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 schema already documents the card identifier and format parameter. The description's mention of Markdown/HTML mirrors the format enum's documentation and adds no parameter-level meaning beyond it, so the baseline of 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 uses the specific verb 'Render' with the resource 'job card' and immediately scopes it to the client-facing print/sign-off use case, listing labor, materials, totals, and a signature line. This clearly distinguishes it from sibling tools like get, summary, or update.
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 clear: 'ready to print and hand to the client' tells an agent when this tool is appropriate. It does not explicitly name alternatives or exclusions, but the context is unambiguous enough for selection among the card tools.
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 no annotations, the description carries the full burden of behavioral disclosure. It adds beneficial context: the definition of 'touched', the Monday-to-Sunday week boundary, and per-currency breakdown. However, it does not explicitly state that the operation is read-only, idempotent, or side-effect free, and it gives no indication of how missing data or multiple currencies are handled. These traits are largely inferable from the word 'summary', but the description itself does not disclose them.
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 first gives the high-level output, the second defines the week, and the third defines inclusion. Each sentence earns its place, and the most important concept ('touched') is defined clearly. Structure is 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?
For a tool with only two optional parameters and no output schema, the description explains what the summary contains (hours, value, per worker, per currency) and how the window is determined. The absence of an output schema is partially mitigated by the enumeration of output categories. Minor gaps remain (e.g., behavior with no entries, multi-currency presentation), but given its low complexity, the definition is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description enriches the parameters by explaining how 'date' selects the window and how 'span' maps to a calendar week. Crucially, it introduces the 'touched' rule, which defines which job cards are included based on dated entries. This adds meaning beyond the schema's plain descriptions of date and span.
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–resource relationship: summarizing hours and value for a day or week, covering job cards touched, hours per worker, and labor/material/total value per currency. This clearly distinguishes it from siblings like job_card_list (raw entries) or job_card_log_labor (recording entries). The title 'Summarize a day or a week' reinforces the exact scope without ambiguity.
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 on the time window ('A week runs Monday to Sunday') and the inclusion rule ('Touched means a labor or material entry dated inside the window'), which helps an agent decide between day and week spans. However, it offers no explicit guidance on when to choose this tool over siblings like job_card_get or job_card_list, nor does it mention exclusions or alternatives. The usage context is useful but not prescriptive.
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?
With no annotations, the description carries the burden of behavioral disclosure. It does disclose that skipped/backwards steps are refused and nothing is written, and that archiving frees a slot. However, it does not mention whether the operation is idempotent, what happens if the card is already in the target status, or any permission requirements. This is moderate coverage for a mutation tool.
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 and front-loaded, with the key action and statuses in the first sentence. The additional constraints are stated in one sentence each, and there is no filler. Every sentence adds important 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 the schema already documents parameters and there is no output schema, the description covers the critical aspects: the exact statuses, the one-step rule, the refusal behavior, and the archiving side effect. It could be slightly more complete with mention of what the response contains or error handling, but for this simple mutation tool it is 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?
Schema description coverage is 75%, so most parameters have descriptions. The description adds the concept of 'one exactly one step' which clarifies the status parameter's roleable. However, it does not explain the 'date' and 'note' parameters beyond what the schema says (default today, optional). The description adds some value but no significant new semantics, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'move' and the resource 'job card', and specifies the exact set of statuses. It distinguishes itself from siblings by focusing on status transitions, while other tools like job_card_log_labor handle different actions.
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 use this tool (to advance a job card by one step) and what is not allowed (skipped or backwards steps are refused). It also mentions that archiving frees a slot, which is a key context for deciding when to use this tool. It does not explicitly name alternatives, but the set of statuses and the refusal rule make the usage context clear.
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?
With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states that data under the token stays and that a wrong or expired key changes nothing, which is valuable non-destructive and failure-mode context for an activation mutation.
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 tight sentences front-load the action and key requirement, then add side-effect guarantees and a pointer to verification. No wasted words or repetition beyond the schema format.
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 one-parameter activation tool with no output schema and no annotations, the description covers the action, key eligibility, non-destructive behavior, failure mode, and how to confirm success. It could add explicit return-value expectations, but license_status confirms it largely covers that gap.
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 fully documents the key parameter, so the baseline is 3. The description adds meaningful semantics by explaining the key must be issued at checkout for this server or bundle and that invalid keys are no-ops, going beyond the schema's simple format description.
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 action, 'Turn Pro on for this connection,' with a clear resource (license/Pro status) and key format. It also distinguishes itself from the sibling license_status by focusing on activation rather than checking 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?
It clearly conveys when to use the tool: when activating Pro with a checkout-issued key for this server or bundle. It also references license_status as the follow-up confirmation step, though it stops short of explicitly saying 'use license_status instead to check current status.'
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?
With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states 'No arguments, nothing changes,' indicating a read-only, side-effect-free operation. It does not detail error handling or authentication requirements, which are minor omissions for a simple status check, but the core behavioral trait (no mutation) is clearly communicated.
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, tightly packed with all essential information. It is front-loaded with the primary action and output, then adds the use case and side-effect note. Every sentence earns its place with no redundancy or 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 tool with no input parameters and no output schema, the description fully covers what an agent needs: the return format (JSON with product, tier, reason, checkout URL), the trigger condition, and the lack of side effects. 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?
The tool has zero parameters, and the description confirms 'No arguments.' Per the scoring rules, 0 parameters earns a baseline of 4. The description adds no parameter-specific meaning because none exist, and it correctly reiterates the absence of arguments, aligning with the empty 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: 'Report this endpoint's licence state for your token as JSON'. It explicitly enumerates the returned fields (product, tier, reason, checkout URL), making the tool's purpose unambiguous. It also distinguishes itself from sibling tools like license_activate by focusing on status reporting rather than activation.
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 trigger for use: 'Call it to explain a free-tier refusal.' This tells the agent when to invoke this tool. It does not explicitly discuss alternatives or exclusions, but the purpose is distinct enough from siblings that the guidance is adequate; it could be improved by noting it is the only read-only license info tool, though that is implied.
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.
Manage jobs, customers, scheduling, estimates and invoices for a field service business.
Search customers, manage quotes, work orders, action items, and calendar events for your business
Drilling jobs, customers, invoices, crews, schedules, and well logs for well contractors.
Add one secure layer between your agents and this server.
