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.

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.

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.

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.

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.

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.

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.

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.

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.

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

With no annotations provided, the description carries the full behavioral burden. It discloses that verification happens offline against a built-in public key, that the key is persisted to the config file, and that invalid keys are refused and left unsaved. This is substantial transparency for an activation tool, though it could mention overwriting an existing key or the exact return behavior.

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. The first sentence front-loads the main action, source, verification method, and persistence. The second sentence efficiently covers error handling and points to the related read-back tool. Every clause adds value.

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 tool with no output schema and no annotations, the description covers activation behavior, verification mechanism, persistence, error outcomes, and how to read the result later. The only minor gap is an explicit statement of what the function returns upon success or failure, but the phrase 'refused, unsaved' implies a feedback mechanism. Overall, it is sufficiently complete 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 at 100% coverage, so the baseline is 3. The description adds meaningful semantics by giving the concrete key format ('MCPL1.xxx.yyy'), confirming the key comes from the checkout page, and explaining that malformed or expired keys will be rejected. This goes beyond the schema's one-line 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 states a specific action ('Activate a Pro key'), the exact key format ('MCPL1.xxx.yyy'), the source ('from checkout'), and the core mechanism ('verified offline against a built-in public key'). It also differentiates itself from the sibling license_status by noting that license_status reads the activation back, so there is no ambiguity about which tool does what.

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 clear context: use this when you have a Pro key from checkout that needs to be activated. It also points to license_status as the read-back tool, which implies when to use a related sibling. It does not explicitly spell out 'do not use for checking status' or list other alternatives, but the context is strong enough to avoid misuse.

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

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

Annotations are absent, so the description carries the full burden of behavioral disclosure. It discloses that the call is local ('no network') and argument-free, and it mentions a specific explanatory behavior. The word 'Report' implies read-only, though it does not explicitly state non-destructive or permission requirements; this is adequate for a status command.

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 with no filler. The first sentence lists the output fields; the second adds constraints and the sibling pointer. Every clause contributes meaningful 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 zero-parameter status tool with no output schema, the description lists the expected output fields, behavioral constraints, and the relevant alternative tool. Nothing an agent needs to call 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?

The schema has zero parameters and the description reinforces this with 'No arguments'. It adds value by listing the reported fields, helping an agent understand what the empty input will yield. The baseline for zero-parameter tools is high, and the description meets 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 ('Report'), a clear resource ('this server's licence state'), and enumerates the exact fields returned. It also names the sibling 'license_activate' as the tool that does something different, so an agent can distinguish them immediately.

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 explicit usage constraints: no arguments, no network, and explains a free-tier refusal. It also directs the agent to license_activate when the task is to install a key, serving as an explicit pointer to the relevant alternative.

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