maintenance-schedule

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

The annotations already mark this as a non-read-only mutation and non-destructive, and the description consistently describes a create. It adds useful behavior beyond the annotations: it returns the AST-YYYY-NNNN id and discloses the 3-asset free-tier limit. It does not contradict any annotation.

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: the first states the action and payload, the second gives the return value and the quota/metering context. There is no filler and the core purpose 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 create with no output schema, the description supplies the return id and the main limitation (free tier), while the schema fully documents parameters. It leaves quota-exceeded or duplicate-tag failure behavior unstated, but duplicate refusal is already in the schema and the tool is otherwise easy to invoke 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?

Schema coverage is 100%, with every parameter already described with types, examples, and constraints, so the description has little burden. The phrase 'its name, its serial or asset tag, where it lives, and the currency' maps cleanly to name, tag, location, and currency and adds a light high-level gloss, but it does not add details 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 opens with a concrete verb and resource ('Add one piece of equipment to the maintenance register') and enumerates the key recorded fields, so an agent can tell this is the create operation rather than asset_history or maintenance_log. The title reinforces the action, and the siblings are clearly different lifecycle/logging operations.

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?

There is no explicit when-to-use or when-not-to-use statement naming a sibling alternative. The context 'Free tier: 3 assets; logging work on the assets you have is never metered' implies that adding assets is metered and that logging work is a separate, unmetered action, but the agent must infer the routing to maintenance_log rather than being told.

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 explicitly claims 'Reads only,' while the annotations set readOnlyHint: false, which contradicts the description. Per the scoring rule, a direct contradiction with annotations must receive a score of 1. Without this conflict, the detailed output listing would have been strong.

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?

A single dense sentence front-loads the core action and then efficiently lists all output components. There is no filler, and each clause contributes useful 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 tool with no output schema, the description covers the accepted inputs and the full set of returned information. Minor omissions like pagination or error behavior are acceptable 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?

The schema already fully describes the single 'asset' parameter, including accepted identifier types and the uniqueness condition. The description echoes this rather than adding new semantic meaning, so the high schema coverage 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 clearly states the verb ('Read'), the resource scope ('one asset in full'), and the accepted identifiers ('by id, tag or name'). It also enumerates the exact returned data, distinguishing it from the sibling asset_add/asset_remove and maintenance_* tools.

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 read-only use for fetching one asset's complete history and financial summary, but it never names alternatives or states when not to use this tool. There is clear context, but no explicit routing versus siblings like maintenance_log or license_status.

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 goes well beyond the annotations, which only declare destructiveHint=true. It discloses the refusal behavior when a maintenance log exists, the requirement for confirm to override that refusal, the consequence of losing the maintenance log, and the permanent side-effect that the AST number is never reissued. This is exemplary transparency for a destructive operation, with no contradiction of the annotations.

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 three concise sentences with no filler. The first sentence states the purpose and typical usage. The second explains the refusal and confirm logic. The third states the permanent non-reissuance of the AST number. Every sentence carries necessary information, and the structure is front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that this is a destructive tool with a confirm gate and a permanent side-effect, the description covers the essential aspects: when it's allowed, what triggers refusal, what confirm does, and the permanent consequence of the AST number not being reissued. It does not mention permissions or what happens to related records beyond the maintenance log, but that is not critical for invocation. With no output schema, the description doesn't need to explain return values, and the key usage nuances are addressed. It is complete enough for an agent to call 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?

Schema coverage is 100% for both parameters, so the schema already describes them. The description adds critical context for the confirm parameter: it explains that confirm must be true to remove an asset with a maintenance log, and that the log is lost. This goes beyond the schema's description of confirm as 'Pass true to remove an asset that carries a maintenance log' by emphasizing the consequence and the refusal behavior. The asset parameter is adequately covered by the schema, so the description's added value is concentrated on confirm.

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 ('Remove an asset') and the target resource, with explicit conditions for when it's appropriate ('entered by mistake or sold off'). It is clearly distinct from siblings like asset_add, asset_history, and license_* tools, which focus on addition, viewing, or licensing. The verb and resource are unambiguous, and the conditions add precision.

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 when to use the tool (mistake or sold off) and implicitly when not to (if a maintenance log exists, unless confirm is true). It does not explicitly name alternatives, but the conditions effectively distinguish it from other asset tools. It lacks explicit exclusions, but the guidance is sufficient for an agent to decide.

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 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.

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.

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

The description adds useful behavioral context by stating that the report is computed from stored next-due dates against today at call time, meaning results are live and time-sensitive. It also flags that this is a Pro feature, which is an access/entitlement consideration. Since the annotations do not mark the tool as read-only, the description's implicit report-only framing is helpful but not explicit about whether invoking it has side effects.

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 compact and front-loaded: the first sentence delivers the full scope and categories, and the second provides computation semantics and the Pro-feature caveat. Every sentence earns its place with no filler.

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 one optional parameter and no output schema, the description does a solid job of explaining the output categories and the time-based nature of the report. It stops short of describing the exact output shape, sorting, or whether the result includes asset identifiers, but the core calling context is adequately covered.

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 within_days with a description and bounds, so the baseline is 3. The tool description repeats the default of 30 days but adds no additional meaning beyond what the parameter description already 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 clearly names a specific deliverable — the due report across every asset — and enumerates exactly what it covers: overdue items, days overdue, upcoming items within N days, later items, and items with no schedule. It does not explicitly contrast itself with maintenance_export or maintenance_log, so it earns a 4 rather than a 5.

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 to use when a consolidated due/overdue report is needed, and it notes the global scope across every asset. However, it gives no explicit guidance about when to use this tool instead of maintenance_export, maintenance_log, or asset_history, nor does it mention any exclusions or prerequisites beyond the Pro feature note.

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 already mark this as read-only, idempotent, and non-destructive, and the description adds 'Writes nothing' to reinforce this. More importantly, it discloses output behavior beyond any structured field: CSV produces one row per entry, while Markdown produces per-asset sections with total spend and next due date. It also surfaces the Pro feature distinction for Markdown, which is useful entitlement context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three short sentences with no filler. The core action and range filter are front-loaded, the two format variants are logically separated, and the final 'Writes nothing' reassures without bloating the text. 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?

For a read-only export tool with no output schema, the description explains exactly what the agent and user should expect from each format, including structure, aggregation, and Pro restrictions. Combined with a fully described schema and strong annotations, nothing critical is missing for correct invocation and result interpretation.

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 alone fully documents all three parameters (to, from, format). The description does not add parameter-level syntax or constraints beyond what the schema provides; it only describes format outcomes, so the baseline of 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 opens with 'Export maintenance entries dated inside a range,' naming a specific verb, resource, and date-scoping. It then distinguishes the two output formats, and the tool name/title reinforces the export function, making it clearly different from siblings like maintenance_log or maintenance_due.

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 usage context: CSV is 'ready for a spreadsheet' and Markdown is 'ready to paste into notes or a report,' so an agent knows which format fits which scenario. It does not explicitly mention when not to use the tool or point to alternative siblings like maintenance_log, but the context is sufficient for a straightforward export operation.

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 only indicate mutability and non-idempotency. The description adds concrete behavioral constraints: a future work date is refused, next_due and interval_days are mutually exclusive, and a repair with no schedule takes neither. These help the agent avoid rejected or invalid calls.

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, dense sentences lead with the action, summarize the recorded fields, and then state the critical exceptions. There is no filler, and parenthesized parameter names help the agent map concepts to schema fields.

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 7-parameter mutation tool with no output schema, the description plus schema are sufficient to determine required inputs, allowed values, and rejection rules. It does not explain return/confirmation behavior, but that is not necessary 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 100%, so the baseline is 3. The description earns credit by synthesizing the scheduling parameters into a clear either/or/neither rule that no single parameter description fully expresses, and by clarifying that cost is in whole cents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with 'Log work done on an asset'—a specific verb and resource—and lists exactly what is recorded: day, work, cost, technician, and next service. This clearly separates it from sibling read/export tools like maintenance_due and maintenance_export.

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 operation is clearly scoped to recording maintenance work, with explicit rules about when schedule parameters should or should not be supplied. It does not explicitly name alternative sibling tools for related tasks, but the use context is unambiguous.

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