QuipAssist

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

Annotations only declare mutability, idempotency, and non-destructiveness; the description adds substantive behavior beyond that — the conditional append-vs-proposal-for-review branch based on approval preference, the technician assignment restriction, and explicit scope limits. It does not detail permissions/auth beyond technician assignment or the return shape.

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

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

Front-loaded with the 'Use this when' trigger and four tight sentences with no filler. Minor redundancy between 'factual observation' and 'advisory note', but overall efficient.

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 mutating tool with no output schema, the description covers the dual-mode behavior, permissions, and scope limits well, and annotations cover the safety profile. However, the unexplained parameters (rationale, idempotencyKey, expectedApprovalRequired) leave gaps an agent must guess at.

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 0% across 6 parameters, so the description must carry the burden. It only indirectly signals targetId/targetType ('authorized repair or maintenance task') and note ('factual observation'); it says nothing about rationale, idempotencyKey, or expectedApprovalRequired, leaving half the parameters unexplained.

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 (append) and resource (advisory/factual note on a work order or maintenance task), and clarifies the draft-vs-immediate duality that the tool name alone obscures. It does not explicitly name a sibling to differentiate from (e.g., draft_work_order_update), so it stops short of 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?

Opens with an explicit 'Use this when...' condition and adds negative guidance ('Never replaces history, completes work or records safety sign-off'), which routes the agent away from misuse for completion/safety flows. It gives clear context but does not name the alternative tools to use for those excluded cases.

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 annotations already declare this is non-read-only, idempotent, non-destructive, and closed-world. The description adds useful behavioral context by disclosing the approval-preference branch and by scoping out vendor notifications, dispatch, completion, and safety sign-off. It does not describe the exact artifact produced or 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 three sentences with no wasted text. It is front-loaded with the usage condition, then gives the approval branch, then states exclusions.

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

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

The description covers the high-level purpose and usage conditions well enough for an agent to understand the tool's role. However, for an 11-parameter mutation with no parameter descriptions and no output schema, it leaves significant gaps around parameter meaning and the result of creating a plan or proposal.

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 0% across 11 parameters, so the description must carry parameter meaning, but it does not. It only implicitly references the asset, scheduling, and an approval preference, while leaving idempotencyKey, recurrence fields, assignedTo, rationale, title, description, and date semantics unexplained.

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: scheduling authorized internal preventive maintenance for an asset. It also sets boundaries by excluding vendor notifications, dispatch, completion, and safety sign-off. It does not explicitly name sibling tools such as draft_work_order, so it stops short of full sibling differentiation.

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: use this when scheduling authorized internal preventive maintenance for an asset. It also explains the approval-dependent behavior: create immediately if approval preference is off, otherwise prepare a proposal for review. It does not explicitly name alternative tools to use instead.

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?

Adds substantive context beyond the annotations: no spending approval, separate purchasing approval remains mandatory, and no supplier dispatch or stock changes. That clarifies the blast radius of a non-read-only, non-destructive write in a way the hints alone cannot. It does not address idempotency behavior or how to recover from a duplicate submission, leaving a small gap.

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?

Front-loaded with the trigger condition, then the conditional behavior, then the guardrails — a sensible order with no filler. The middle clause is dense and slightly hard to parse on first read ('using verified part price if your purchase-request approval preference is off').

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?

Covers the approval and side-effect story well for a mutation tool, and annotations plus the explicit negatives make the safety profile clear. But with no output schema and zero parameter descriptions, an agent still cannot tell what it gets back (a draft ID? a status?) or what to supply for idempotencyKey and rationale.

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 0% across 5 parameters, so the description must carry the burden — and it does not. It never explains partId, quantity, rationale, or the UUID idempotencyKey, nor what expectedApprovalRequired toggles. At best 'verified part' and 'approval preference' obliquely gesture at two of the five fields.

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 and resource ('creating a pending purchase request'), constrained to 'a verified part', and immediately negates the wrong interpretation ('this never approves spending'). Against a sibling set of draft_* tools, the resource being drafted (a purchase requisition vs. a work order or vendor message) is unmistakable.

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?

Gives an explicit conditional: use this when the approval preference is off, otherwise prepare a proposal for review. That is real when-to-use guidance rather than implied. It stops short of naming or excluding siblings (e.g., draft_vendor_communication for supplier contact), so it is not a full 5.

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?

Beyond the annotations (readOnlyHint=false, idempotent, non-destructive), the description discloses the critical downstream boundary: nothing is sent or emailed, sending remains manual, no contractor dispatch, no purchasing-approval change. It also explains the two-mode outcome (durable text vs. proposal for manager/admin review), which is genuinely decision-relevant 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?

Front-loaded with the usage trigger and compact overall, but the non-sending point is restated three times ("never sends the message", "Sending remains manual", "Never emails a supplier"), while parameter meaning is omitted — space is spent on emphasis rather than on information the agent lacks.

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 write-shaped draft tool with no schema descriptions and no output schema, behavior is well covered but input semantics are not. An agent could still supply garbage for rationale or mismatched expectedApprovalRequired, so the definition is only partially 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 coverage is 0% across 7 parameters, so the description carries the full burden, yet it only indirectly implies vendorId (active vendor), workOrderId (authorized work order), and subject/body. It says nothing about the required `rationale`, the `idempotencyKey`, or `expectedApprovalRequired` — the last being especially important since it interacts with the approval-preference logic the description does describe.

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 (prepare/draft) and resource (vendor message text) with clear scope: a vendor linked to an authorized work order. It doesn't explicitly contrast itself with the numerous sibling draft_* tools, but the vendor-communication focus makes the resource unambiguous.

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?

"Use this when preparing a message for a vendor linked to a job" gives an explicit trigger, and the description explains conditional behavior (prepare immediately if the vendor-message approval preference is off, otherwise produce a proposal for review). It stops short of naming alternatives or stating when not to use it, e.g. versus draft_maintenance_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?

Adds real behavioral context beyond annotations: creation branches on the acting user's approval preference (immediate work order vs proposal for review), and it notes 'ordinary cost approval remains'. Idempotency is reinforced with the required-UUID constraint. It doesn't describe the response or failure behavior, so not a 5.

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?

Front-loads the usage trigger, then states the branching behavior and scope exclusions. Dense but efficient; the closing exclusions sentence is slightly compressed but earns its place by preventing misuse.

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

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

The workflow/approval branching is well covered and annotations handle the safety profile, but with 11 parameters at 0% documentation and no output schema, key inputs like expectedApprovalRequired and expectedCostCents are left opaque. Adequate on behavior, deficient on 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 0% across 11 parameters. The description only illuminates idempotencyKey (required UUID) and implicitly equipmentId; it says nothing about title, rationale, priority, category, assignedTo, appointmentDate, expectedCostCents, or expectedApprovalRequired. It fails to compensate for the coverage gap.

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+resource: 'recording a new equipment issue' and creating an 'authorized work order' vs a 'proposal for review'. This clearly distinguishes it from the update sibling by emphasizing a NEW work order. It does not explicitly name sibling alternatives, keeping it just below 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?

'Use this when recording a new equipment issue' gives a clear triggering condition, and the description scopes out unrelated actions ('no closure, dispatch or equipment control'). It stops short of naming explicit alternatives such as draft_work_order_update for modifications.

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?

Goes well beyond the annotations by disclosing the two-mode behavior (immediate change when edit-approval is off, otherwise a proposal for review), the failure mode ('stale proposals conflict'), and the explicit scope ceiling on what is never altered. This is substantive operational context the annotations do not carry.

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 dense sentences with no filler and the trigger front-loaded. It is slightly packed in the middle sentence (approval branch), but every clause carries 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 mutation tool with no output schema, it covers purpose, branching behavior, and scope limits well. The remaining gap is parameter-level guidance for the three unexplained fields, but overall an agent has enough to invoke 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?

With 0% schema coverage the description must compensate, and it does name five editable fields (title, description, priority, assignedTo, appointmentDate). However, it leaves rationale, idempotencyKey, and especially expectedApprovalRequired unexplained, so coverage of the 9 params is only partial.

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 (correct/change) and resource (an open job / work order) and enumerates the editable fields, so it is clearly distinguishable from draft_work_order (create) and view_work_order (read) siblings.

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?

Gives an explicit trigger ('use this when correcting an open job's details') and clear exclusions ('Never changes closure, spending approval, costs or safety sign-off'), plus the approval-preference branch that decides immediate edit vs proposal. It does not name specific sibling alternatives, keeping it just below a 5.

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 establish read-only, idempotent, and non-destructive behavior. The description adds useful context about access filtering by acting user, sites, record visibility, and read scopes, plus the explicit non-mutation boundary.

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 front-loaded and compact. The second sentence partially repeats the first's outcome/result-ID idea, but overall it remains efficient.

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

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

For a simple read-only query tool, it covers usage, access scope, and non-mutation behavior. However, it leaves the optional filter parameters undocumented and does not describe how results are structured, which is a meaningful gap given the lack of an output schema.

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 0%, so the description should explain the two optional parameters. It never mentions the status or draftId parameters, and while it references outcomes like pending/rejected, it does not map them to the status enum or explain draftId filtering.

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 identifies a specific verb and resource: checking prior request/draft review outcomes and retrieving record IDs. It distinguishes itself from creation-oriented siblings by stating it does not approve, execute, or send anything, though it could name the draft siblings more directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear usage condition: 'Use this when checking whether a prior request is pending, rejected or applied and retrieving its record ID.' It also implicitly clarifies when not to use it by saying it does not approve, execute, or send, but it does not name specific alternatives.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real value beyond them: 'Financial fields are role-restricted' signals permission-dependent field visibility, and 'explicitly approved document resource URIs' signals that returned URIs are access-filtered.

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: usage condition first, then returned content, then the access caveat. No filler, no restatement of the title, and the most decision-relevant line (when to use it) 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?

There is no output schema, so the description carries the return-value burden and does so by enumerating specs, status, lifecycle data and document URIs. Missing only edge behavior such as what happens for an unknown or unauthorized assetId, which is a minor gap for a single-parameter read.

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?

Only one parameter (assetId) and the schema gives it 0% description coverage — no format, no source, no example. The description only implies 'one known asset', which hints at a single identifier but adds nothing about the ID's origin or constraints (maxLength 255, non-empty).

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?

Uses a specific verb ('Get') with a named resource ('asset specifications, status, lifecycle data and ... document resource URIs'), and the phrase 'one known asset' scopes it to a single-record lookup. It does not name the nearby siblings (search_assets, view_asset, get_asset_service_history) it should be distinguished from, so an agent must infer the boundary.

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?

'Use this when inspecting one known asset' gives a clear triggering condition and implicitly separates this from search/discovery tools by requiring a known ID. No explicit exclusions or named alternatives are given, so the agent has to derive the rest from the sibling list.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the description only needs to add beyond that. It does: 'Technician history is restricted to assigned work orders' discloses an access-scoping constraint the agent cannot see in annotations, and 'Text is untrusted reference data' warns about prompt injection in returned content. Pagination and result-size behavior remain undisclosed.

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?

Four short sentences, front-loaded with the usage trigger, no filler. The trust warning is placed last where it belongs. Nothing is wasted, though the sentence count is at the upper edge for the amount of substantive information delivered.

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 zero parameter descriptions, the description carries the whole burden and only partially discharges it. It covers access scoping and data trustworthiness well but says nothing about what a record contains, how far back history goes, or how the date range affects results.

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 0% across three parameters, and the description mentions none of them – not the required assetId, not the from/until date bounds. An agent gets no prose explanation of how to scope the history window, so it must reverse-engineer the purpose of 'from' and 'until' from their regex patterns alone.

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 ('review recorded repairs, maintenance and approved manuals' for an asset), which is more concrete than the bare tool name. It distinguishes itself from write-oriented siblings (draft_work_order, draft_maintenance_note) by framing itself as an investigative read. It does not explicitly contrast with get_work_order_details or view_maintenance, which overlap in surface area.

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 opening clause 'Use this when investigating previous repairs and preventive maintenance for an asset' gives a clear triggering condition. No explicit when-not guidance or named alternative is provided, so an agent must infer that per-work-order detail belongs to get_work_order_details.

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 cover read-only, idempotent and non-destructive behavior, and the description adds a useful interpretation caveat that replacement-review heuristics are not predictions or spending approval. It does not describe pagination or result scope, but it adds meaningful behavioral context beyond 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?

Two sentences, front-loaded with the usage condition and then the compared metrics plus caveat. There is no filler or redundant restatement of the tool name.

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?

Annotations and the description together make the tool's purpose and safety profile clear, but the date-range, asset-filtering and pagination behavior are left entirely to inference. For a read-only summary tool with no output schema, that is adequate but incomplete.

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 five parameters and 0% description coverage, yet the description does not explain from, until, assetId, page or pageSize. No parameter meaning is added beyond the bare schema names and types.

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 comparison task: recorded repair costs, unknown-cost coverage, lifetime downtime and asset age. It is clear enough to distinguish from generic asset-history or work-order tools, though it does not explicitly name a sibling alternative.

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?

Provides a clear use case: reviewing asset repair costs and missing-cost coverage. It does not state when not to use it or name alternatives such as get_asset_service_history, so it falls short of full routing guidance.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context: results are site-scoped, and unknown reserved quantities come back as null rather than fabricated — an important data-trust detail.

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

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

Three sentences, each earning its place: the first routes usage, the second defines the returned data, the third states a null-handling guarantee. Front-loaded with the decision context and free of 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?

There is no output schema, and the description does describe the returned fields (stock, thresholds, usage, incoming orders, reserved quantities) reasonably well. However, for a six-parameter tool with zero schema coverage, the omission of parameter and pagination semantics leaves the definition only partially complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across six parameters, so the description must compensate and largely does not. It hints at site scoping (locationId) and part lookup (partId/query) but says nothing about pagination (page, pageSize) or assetId, leaving several filters ambiguous.

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

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

The description names a specific resource and scope: 'Read site-scoped stock and reorder thresholds with recorded usage and incoming orders', reinforced by the title about stock and incoming orders. It is clearly distinguishable from sibling tools such as get_asset_details or list_due_maintenance, though it never names a sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use this when identifying stock shortages or checking a part before requesting replenishment' gives a concrete triggering situation and a downstream workflow. It stops short of stating exclusions or naming the replenishment tool (e.g., draft_purchase_requisition) by name.

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 cover read-only, idempotent, non-destructive and closed-world semantics, so the bar is lower. The description still adds real value by disclosing what the response contains — freshness, missing-data, plausibility and threshold observations — which is important with no output schema. It stops short of noting pagination behavior or limits.

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 compact sentences, front-loaded with the selection condition. The second sentence partly restates the first ("Read telemetry only" vs. "Use this when checking telemetry"), but the added detail about observation types keeps it earning its place.

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

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

For a zero-required-parameter read tool this covers purpose and output content adequately, but five undocumented parameters and no output schema leave real gaps: time-range semantics, asset/sensor scoping, and pagination defaults are all unstated.

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?

All five parameters (from, until, assetId, sensorId, pageSize) have 0% schema description coverage, so the description carries the full burden — and it says nothing about any of them. There is no mention of time-window semantics, defaults, single-asset vs. fleet scope, or the pageSize cap of 100.

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 resource (telemetry / sensor readings) and the aspect being checked (freshness), which is more precise than the title alone. It implicitly separates itself from the drafting and work-order siblings by being a read-only observation tool, though it never names a sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-to-use ("when checking telemetry and its freshness") and clear exclusions ("not for controlling equipment or certifying safety"). The exclusions are stated by category rather than by naming an alternative tool, so the agent still has to infer which sibling covers control/safety-adjacent asks.

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 annotations already establish that this is a safe read-only, idempotent operation. The description adds useful data-integrity context by limiting comparison to authorized jobs and completed scorecards and stating that unknown contract state is not fabricated.

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 short and front-loads the usage condition. The second sentence partly repeats the first, but it also adds the important constraint about not fabricating unknown contract state.

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 comparison tool with one optional parameter and no output schema, the definition covers scope and data-source constraints adequately. However, it leaves out what performance dimensions are compared and how the optional vendorId changes the result.

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 0% description coverage for the single optional vendorId parameter, and the description never explains how vendorId is used or what happens when it is omitted. The plural 'vendors' hints at comparing all vendors, but this is not made explicit.

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 clear verb and resource: compare vendors using completed scorecards and authorized jobs. It is understandable without opening the schema, though it does not explicitly distinguish itself from any sibling tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear usage condition: 'Use this when comparing authorized vendor jobs and completed scorecards.' It also states a scope restriction, but does not name alternatives or 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description's additions ('Read an authorized job', 'No closure or sign-off operation') gesture at permission scoping and scope boundaries but never state what authorization means or what happens on an unauthorized ID.

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 very short sentences, front-loaded with the use case. There is mild redundancy — 'examining one job' and 'Read an authorized job' restate each other, and 'approval history' appears twice — but nothing is bloated.

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, read-only tool with full annotations and no output schema, the description adequately signals scope by listing the content returned (parts, notes, approval history). Its main omission is disambiguating itself from view_work_order and search_work_orders, which matters given six near-neighbor siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single workOrderId parameter has 0% schema description coverage, so the description would need to compensate — but it says nothing about the ID's source or format. The schema still provides type, min/max length and required-ness, and the parameter name is largely self-explanatory, so this is not a severe gap, but no meaning is added 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?

Names a specific verb and resource ('examining one job'), and enumerates what the read covers: recorded parts, notes, approval history. It does not, however, differentiate itself from close siblings such as view_work_order, view_work_orders, and search_work_orders, so an agent cannot tell which of these to pick from the description alone.

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?

'Use this when examining one job' gives an implied use case, and 'No closure or sign-off operation' sets a boundary on what it will not do. But it never names the alternative tool an agent should use for writes or for broad listing, and gives no prerequisites beyond a vague 'authorized'.

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?

Beyond the read-only/idempotent annotations, the description adds meaningful behavior: only active authorized technicians are returned, results are scoped to one asset’s site, and technician callers see only themselves. The dispatch-permission caveat is also important behavioral context not captured by 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 short sentences, front-loads the usage condition, and has no filler. Each sentence contributes either decision guidance, scope, or a behavioral constraint.

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 list tool with one parameter and no output schema, the description adequately covers when to use it, what is returned conceptually ('active authorized technicians'), visibility limits, and how IDs may be used. It could be slightly more complete by clarifying equipmentId semantics or the result shape.

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?

With one required parameter and 0% schema description coverage, the description partially compensates by indicating that the asset’s site drives the technician list. However, it does not explain the equipmentId format or confirm that the parameter is the asset identifier, leaving some semantic gap.

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: 'Find active authorized technicians for one asset’s site.' It also clarifies the intended decision context ('when choosing an authorized technician for a proposed or permitted assignment'), which distinguishes it from sibling tools that draft documents or retrieve work orders.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear usage context: 'Use this when choosing an authorized technician for a proposed or permitted assignment.' It also explains a usage boundary: IDs may be used in assignment proposals but 'never as permission to dispatch.' It does not name explicit alternatives, but no obvious sibling competes for the same task.

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 read-only, idempotent, non-destructive behavior, and the description adds value beyond them: results carry evidence-based risk indicators, and it warns that criticalOnly only matches assets explicitly tagged Critical, with untagged criticality treated as unknown. It does not describe pagination or default result ordering despite page/pageSize parameters.

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

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

Three short sentences with no filler; the usage trigger and scope come first and the criticalOnly caveat is placed last as a targeted warning. Tight 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 an 8-parameter, entirely undocumented schema with no output schema, the description is too thin: an agent cannot tell the default date window, whether from/until are required, how overdueOnly interacts with criticalOnly, or what a page of results contains. The one caveat it does provide is good but insufficient for this schema.

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 0% across 8 parameters, so the description must carry parameter meaning, but it only explains criticalOnly. It says nothing about from/until, overdueOnly, assetId, locationId, or page/pageSize defaults, leaving most filter semantics to be guessed from property names.

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+resource: finds upcoming or overdue maintenance schedules with risk indicators, which an agent can distinguish from drafting or viewing tools. It never explicitly contrasts itself with view_maintenance or view_operations_dashboard, so sibling differentiation is left implicit.

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?

Opens with an explicit trigger ('Use this when identifying maintenance that needs attention or planning upcoming work'), giving clear context for invocation. It names no alternatives and gives no when-not conditions (e.g. use view_maintenance for a single record), so it stops short of full routing guidance.

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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral context: it creates no record or approval and returns review/direct requirements plus reasons, though it does not discuss permissions, audit logging, or rate limits.

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 short and front-loads the main usage condition, but it repeats the point that the tool creates no record or approval and restates the checking action in the second sentence, adding some redundancy.

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?

It tells the agent what the tool returns, which matters because there is no output schema, but with two required parameters and 0% schema description coverage it does not fully explain the kind enum or the payload object structure.

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 0%, so the description must carry parameter meaning. It partially explains that payload represents the "exact proposed fields" and that kind is the record-change type, but it does not explain the allowed kind values or the expected payload properties, leaving substantial ambiguity for a nested object parameter.

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

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

The description states a specific verb and resource: checking exact proposed fields against current security rules before confirming a record change. It also clarifies the outcome (review/direct requirements and reasons) and distinguishes the tool from record creation by saying it creates no record or approval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear use condition: "Use this when checking whether exact proposed fields require review or may be applied directly." The "creates no record or approval" line implies this is not a drafting or creation tool, but it does not explicitly name sibling alternatives such as the draft_* 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds one genuinely useful trait, that results are limited to 'authorized' assets, but says nothing about pagination behavior or result caps despite page/pageSize parameters.

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 short sentences with no bloat, but the second largely restates the first with a slightly longer field list. Its one new contribution, 'authorized', is buried mid-sentence instead of 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 7-parameter, zero-coverage search tool with no output schema, the description covers the filter vocabulary but omits pagination and expected result shape. Annotations handle the safety profile, so the remaining gap is moderate rather than critical.

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 0%, so the description must carry the load. It maps concepts to filters (name/serial → query, type → type, site → locationId, status → status, ID → assetId), but page and pageSize are never mentioned and the query/assetId split is left ambiguous.

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 ('Find') and resource ('authorized assets'/'equipment'), and enumerates the lookup keys. It does not distinguish itself from close siblings like view_assets, view_asset, or get_asset_details, so an agent cannot tell search-vs-retrieve apart from the description alone.

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?

'Use this when identifying equipment by name, serial number, type or site' gives a clear triggering condition. It stops short of naming alternatives or stating when not to use it (e.g., when the asset ID is already known, use view_asset).

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 annotations already establish readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the description does not need to restate safety. It adds useful behavioral context by saying the search returns blockers and approvals and that technician access is assigned-only, though it does not cover pagination or result-shape details.

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, front-loaded with when-to-use guidance, and contains no wasted wording. It stays compact while covering purpose, filters, return context, and access constraint.

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

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

The annotations cover the safety profile and the description covers high-level purpose and some filters, but for an 11-parameter tool with 0% schema description coverage and no output schema, more parameter semantics and pagination/result context would be needed. It is adequate but leaves clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning. It maps several filters conceptually (status, open-only, priority, site, technician, text, date), but it does not explain all 11 parameters, such as page, pageSize, or assetId, and does not give value formats or examples.

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: it searches authorized jobs/work orders by filters and returns blockers and approvals. This is clearly distinguishable from draft or detail-oriented siblings, but it does not explicitly contrast itself with similarly named siblings such as view_work_orders.

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 opening sentence gives clear when-to-use guidance: locating jobs by status, priority, site or technician. It also notes that technician access is assigned-only. It does not explicitly state when not to use the tool or name alternatives for single-record or list-oriented views.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds useful context about authorization ('governed by the caller's existing scopes, role and approval preferences') and freshness ('Loads a fresh ... asset'), but never explains what the 'optional actions' are or whether they write anything.

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 compact sentences, front-loaded with the trigger condition. Phrasing like 'approved document references' and 'approval preferences' is a little abstract but nothing is wasted.

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 read tool with rich annotations and no output schema, the description covers the when and the authorization model, but leaves the required assetId undocumented and the 'optional actions' undefined. An agent could call it, but with avoidable guesswork about the identifier.

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 is one parameter (assetId) with 0% schema description coverage, so the description carries the full burden — and it never mentions assetId, its format, its length limit, or how to obtain a valid value (e.g. via search_assets). This is a real gap for a required identifier.

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?

It states a verb and resource ('inspect one known asset', 'Loads a fresh, authorized asset and approved document references'), but the addition of 'initiate an authorized work order or maintenance plan' muddies what the tool actually does. Siblings like get_asset_details and view_assets are never mentioned, so an agent cannot tell why it should pick this over those.

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?

'Use this when the user wants to inspect one known asset' gives a usable trigger condition, implying the asset is already identified. But there is no guidance on when NOT to use it versus get_asset_details, view_assets, get_asset_service_history, or the draft_* tools for creating work orders.

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 read-only, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds meaningful context beyond them: results are server-side filtered and paginated, scoped to "current authorized equipment," and client-supplied records are not trusted. It omits pagination defaults and result shape, but the added behavioral context is substantive.

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

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

Three short sentences, with the usage trigger front-loaded and no filler. The closing line about untrusted client records is slightly cryptic and could be phrased more directly, but nothing is wasted.

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, zero-required tool with no output schema and no schema descriptions, the description leaves the entire parameter surface undocumented and never explains what a call returns or how pages are bounded. Annotations cover safety, but an agent cannot call this with confidence about filter semantics.

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 0% across 7 parameters with no enums, so the description carries the full burden. It only gestures at categories ("search, filters and pagination") without mapping them to `query`, `type`, `status`, `locationId`, `assetId`, `page`, or `pageSize`, or explaining how the id filters interact with the search fields.

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 set (browse, search, filter, inspect) and resource (equipment), and the title clarifies it opens an interactive explorer. It does not, however, distinguish this from the sibling `search_assets` or `view_asset`, which sound like near-equivalents.

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?

"Use this when the user wants to browse, search, filter or inspect equipment interactively" gives a real trigger condition. But the trigger verbatim overlaps with sibling `search_assets` (search) and `view_asset` (inspect), and the description names no alternative or exclusion, so an agent still has to guess between them.

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 annotations declare readOnlyHint=true and destructiveHint=false, but the description says the user can 'record authorized observations interactively,' which implies a write operation. This contradicts the read-only annotation, so the description fails to accurately disclose 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 short and front-loads the use case, then states what loads and adds a risk disclaimer. The contradictory 'record observations' clause is the main flaw, but the overall size is appropriate.

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 an 8-parameter tool with no output schema, the description is incomplete: it does not map filters to parameters and contradicts the read-only annotation. An agent would lack enough detail to invoke it correctly without inspecting the schema.

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 8 parameters with 0% description coverage, so the description must compensate. It only says 'with filters and pagination,' which hints that filters exist but does not explain any specific parameter (e.g., overdueOnly, criticalOnly, assetId, from/until).

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: 'Loads upcoming/overdue authorized schedules with filters and pagination.' This clearly conveys that the tool retrieves schedules, but it does not explicitly differentiate from the sibling list_due_maintenance.

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 provides a clear when-to-use context: 'Use this when the user wants to browse due schedules, focus on overdue work or record authorized observations interactively.' However, it does not state when not to use it or name alternatives.

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?

Goes well beyond the readOnly/idempotent annotations: it discloses that counts are exact only for authorized records, that ungranted sections report as unavailable rather than zero (a critical interpretation trap), that lists are paginated/capped independently, and that it never executes operational actions. This is exactly the kind of behavioral context annotations cannot carry.

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?

Four short sentences, each front-loaded with a distinct fact: when to use, count semantics, pagination behavior, safety profile. 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?

Covers usage, counting semantics, unavailable-section behavior, pagination and safety, which is strong for a dashboard tool with no output schema. The only omission is the undocumented locationId parameter, which leaves scope behavior ambiguous.

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 0% for the single optional locationId parameter, and the description never mentions it, so an agent gets no guidance on what scoping by location does or whether omitting it widens scope. With only one optional parameter and no output schema, the gap is real but modest.

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

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

The description names specific content: authorized equipment, open work, overdue maintenance, low stock. This is clearly distinguishable from siblings like get_maintenance_cost_summary or list_due_maintenance, which return single-domain data rather than a combined overview.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Use this when the user wants an interactive overview' framing gives a clear selection condition, and the contrast with drill-down siblings is implied by 'overview'. It does not explicitly name which sibling to use for detail on a specific asset or work order, but the context is clear enough.

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, destructiveHint=false and closed-world, so the safety profile is covered; the description still adds real value by naming the payload returned (parts, notes, approval history), the 'authorized' scoping, and explicit negative boundaries — viewing never closes, dispatches or approves. The 'initiate permitted edits' phrasing sits slightly awkwardly against readOnlyHint, but the final sentence resolves it rather than contradicting it.

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

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

Three short sentences, trigger first, payload second, boundaries last — nothing is repeated from the annotations or schema. Every sentence carries distinct 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?

With one parameter, no output schema and strong annotations, the description does the right extra work by enumerating what is returned (parts, notes, approval history). What remains missing is the identifier format and any disambiguation from get_work_order_details, which matters given the sibling set.

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 is only one parameter and the schema gives it no description at all (0% coverage), so the description must compensate. It only says 'one job' / 'authorized job' and never indicates the expected ID form (e.g., a work-order identifier string) or that a full/partial ID is acceptable, leaving the agent to infer the value from the property name.

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 and resource — inspect one job — plus what it loads (parts, notes, approval history), so the operation is concrete. However, it never distinguishes itself from the near-identical sibling get_work_order_details, nor from view_work_orders, so an agent cannot tell these apart from the description alone.

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?

'Use this when the user wants to inspect one job' gives a usable trigger condition, but there are no exclusions and no mention of alternatives, which is a notable gap given three sibling tools that appear to read work orders. The phrase 'initiate permitted edits, notes or prepared vendor text' hints at follow-on draft tools without naming them.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: it discloses authorization scoping ('Technicians see assigned work only') and that blockers are included in the payload. It stops short of return shape or pagination defaults, which keeps it out of the top band.

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, trigger condition front-loaded, zero filler. The second sentence is a tight capability summary rather than repetition of the title. Slightly more could have been said about filtering semantics within the same budget.

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 an 11-parameter tool with no parameter descriptions and no output schema, the description covers intent and authorization scoping but leaves the agent guessing about defaults (page size, sort order), what a 'blocker' contains in the response, and how unsupplied filters behave. Adequate to invoke, not complete enough to invoke confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 11 parameters at 0% schema description coverage, the schema provides almost nothing, so the description has to compensate. It does partially: 'search' maps to query, 'filters' implies status/priority/date/assignee/asset/location, and 'pagination' implies page/pageSize. But no individual parameter is explained, and semantics like date-range meaning, defaults, or valid status/priority values are absent.

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 gives a specific verb+resource: it 'loads current authorized jobs with blockers, search, filters and pagination' as an interactive browse view. An agent can tell this is the interactive list view rather than a single-record fetch, though it never names its closest siblings (search_work_orders, view_work_order) to sharpen the distinction.

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 opening clause 'Use this when the user wants to browse, search or filter jobs ... interactively' is a genuine use-condition, not just a restatement. But with siblings search_work_orders, view_work_order and view_operations_dashboard in scope, no alternative is named and no exclusion is given — the word 'interactively' is the only routing signal.

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