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

Description claims it supports Idempotency-Key and replays original responses, implying idempotent behavior, but annotation idempotentHint=false contradicts this. Flagged as Annotation Contradiction.

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

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

Front-loaded with purpose, but includes extensive detail on errors and next steps. Somewhat lengthy but necessary for clarity; well-structured.

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?

Comprehensive given no output schema: explains atomicity, locking, version fencing, error codes, and references design doc. All parameters fully described in 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 coverage is 100%, description adds extra context for expected_move_ids (recommended usage) and idempotency_key (header transmission). Adds value beyond 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?

Clearly states it applies the cascade previewed by /emergency/preview, assigning the emergency job and displacing others. Differentiates from sibling previewEmergencyReschedule by being the commit step.

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?

Explicitly ties to preview step, provides error handling for 409 codes, and recommends using expected_move_ids to avoid plan drift. Gives clear next steps on failure.

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 reveals atomic behavior, advisory lock, status_version fencing, and drift detection (409). It also explains idempotency key behavior. Annotations are minimal, so description adds substantial 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 well-structured and front-loaded. While a bit long, each sentence adds value. Could be slightly more concise but is effective.

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 main use case, error handling, and references a design document. Lacks output schema details but tool complexity is high and description is sufficient 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 100%, but description adds essential context: mode must match preview, start_at must be future, expected_version from preview, expected_move_ids are displaced job IDs. Adds value beyond 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 clearly states 'Commit a schedule-board job move' and explains it applies a previewed move. It uses a specific verb+resource and distinguishes from sibling tools like previewJobRequestMove.

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 explains the tool is to be used after a preview and provides guidance on parameters like expected_version and expected_move_ids. It also gives next steps for 409 errors, but lacks explicit alternative suggestions.

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

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

The description discloses important behavioral details beyond annotations: it fires the 'confirm_booking' action, is audited as business_on_behalf, and explains that failed attempts bump status_version. It also describes the optimistic locking mechanism (status_version) and the idempotency key behavior. However, the idempotentHint=false annotation seems to contradict the description's claim that the key makes retries safe, creating a minor inconsistency.

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 with the main purpose and structured with clear sections for use cases and a decision table. While it is somewhat lengthy, every part contributes information, and the table format is efficient for error handling. Minor redundancy exists, but overall it is well-organized for its complexity.

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 no output schema, the description adequately covers the tool's behavior, error codes, and next steps. It lacks explicit mention of the success response structure, but the decision table compensates by guiding post-call actions. The two use cases are fully explained, making the tool's role clear in the workflow.

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 100% schema coverage, the description still adds value by clarifying parameter semantics: scheduled_at is business-local naive datetime, technician_id forces assignment despite bypassing ranking, idempotency_key is sent as a header, and arrival_window_minutes provides derivation context. This enriches the schema definitions meaningfully.

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 tool confirms a booking on behalf of the customer and outlines two specific use cases (LIVE and SANDBOX). While it does not explicitly differentiate from sibling tools like 'commitEmergencyReschedule', the decision table provides context for when to use this tool vs other actions. The purpose is specific and actionable, but lacks explicit sibling 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 description explicitly says when to use the tool (LIVE staff confirmation, SANDBOX testing) and provides a detailed decision table mapping error codes to next steps. It does not, however, directly compare to alternative tools like 'quoteJobRequest' or 'commitJobRequestMove', leaving some ambiguity about when to choose this over others. Overall, it gives clear context and recovery actions.

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 a write operation (readOnlyHint=false), so the description does not need to restate mutation. It adds useful business context (customer records are tied to job requests) and flags the service_area_id ownership constraint, but it stops short of describing response behavior or idempotency semantics, which are not covered 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 compact and front-loaded, with no wasted sentences. The opening 'Create a customer' is redundant with the title, but the rest of the description earns its place by explaining the purpose and key constraints.

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 create tool with no output schema, the description gives enough context about what the customer record is, when to use it, and where key parameters live. It doesn't mention the response shape, but the rich schema and clear purpose make the tool callable without that detail.

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

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

Schema description coverage is 100%, so the schema already documents all parameters fully. The description highlights the nested address object and the service_area_id ownership rule, but these details are also present in the schema, so it adds only marginal value beyond structured definitions.

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 the specific action (creates a customer record) and the resource's role: the client/account profile a job request is booked against. This clearly distinguishes it from other create_* siblings and from read/update/delete 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?

It gives a clear use context: import or sync customers from a CRM, website lead form, or intake flow. It doesn't explicitly state when to use updateCustomer or getCustomer instead, but the intended context is specific enough for an agent to choose correctly.

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 signal this is a mutable, non-destructive operation. The description adds meaningful behavioral context: the created work order enters the dispatch & scheduling pipeline, and quoting/assignment/completion follow. This goes beyond the bare mutation hint and helps the agent understand side effects and lifecycle.

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 substantive description is compact and front-loaded with the core action. The only minor waste is the opening line 'Create a job request', which simply repeats the title. Otherwise 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?

Given the 9-parameter schema with full descriptions, the tool description adds the most valuable missing context: the scheduling-pipeline placement and the workflow stages that follow. It does not describe the response shape, but with no output schema that is a minor gap for a creation operation whose schema is already thorough.

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 carries the full parameter documentation. The description adds useful selection guidance beyond the schema, particularly the recommendation to source job_dates from GET /job-requests/booking-windows and the note that skill_ids represent required technician qualifications.

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

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

The description opens with a specific verb and resource: 'Books a field-operations job — the work order that enters the dispatch & scheduling pipeline.' This clearly differentiates createJobRequest from sibling read/update/confirm/quote tools and states exactly what object is being created.

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 concrete guidance on what to send and even points to the booking-windows endpoint as the ideal source for job_dates. It does not explicitly name alternatives or say 'use quoteJobRequest instead when...', but it implies quoting is a downstream step, which helps an agent route correctly.

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 provide the side-effect profile (readOnlyHint false, destructiveHint false, idempotentHint false), and the description's 'Adds' is consistent with those annotations. It adds the 'business catalog' context but does not disclose additional behaviors such as auth requirements or response shape.

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

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

The meaningful content is compact and clear. However, the opening sentence 'Create a job type' merely restates the title, giving the description a small redundant start while remaining appropriately short overall.

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 3-parameter create operation with full schema coverage and annotations covering the safety profile, the description is mostly sufficient for correct invocation. The main gap is the lack of any stated return value, though no output schema is present.

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%, and the schema already documents the name requirement, status enum/default, and idempotency-key behavior in detail. The tool description itself adds no parameter-specific meaning, so the baseline 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 states a specific verb, 'Adds', a specific resource, 'a new job type', and a target, 'the business catalog'. Sibling tools such as deleteJobType, getJobType, and listJobTypes make clear this is the create variant, so there is no ambiguity about what it does.

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

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

The description offers no explicit when-to-use guidance or alternatives, so an agent must infer usage from the verb 'Adds'. It is not misleading, but it does not specify conditions or exclusions relative to other 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 cover read-only, idempotency, and destructive traits, so the description is not required to restate those. It adds the domain context that the service area belongs to 'the business' and that boundaries are optional, but it does not disclose side effects such as duplicate-name handling or response 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, but the first sentence repeats the title almost verbatim. The second sentence adds the only substantive detail, optional polygon boundary, so the structure is acceptable but not maximally 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?

With 10 parameters and a nested boundary object, the schema provides enough detail for calling the tool, and the description names the key optional boundary concept. It omits expectations about return values and gives no explicit duplicate-handling context, but these are not essential for basic 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?

The input schema provides 100% coverage with descriptions and examples for all parameters, so the schema carries the parameter documentation burden. The description only reinforces that the boundary parameter is optional and adds no meaning 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 uses the explicit verb 'creates' with the resource 'service area', clearly identifying the operation type. It also mentions the optional polygon boundary, which distinguishes it from sibling get/list/delete service-area 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 usage is implied: an agent would use this tool when a new service area needs to be created, and sibling names make the resource category clear. However, the description does not explicitly state when not to use it or contrast it with alternatives like update or delete.

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, the description discloses non-obvious behavior: skills are active by default and names must be unique within a category. It does not cover response shape or failure handling, but the annotations already establish the mutating nature 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 short and front-loaded with the primary action, followed by two valuable behavioral notes. The main redundancy is the opening 'Create a skill,' which repeats the title and tool name, but this is minor.

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 four-parameter create tool with full schema coverage and annotation support, the description adds the missing behavioral constraints needed for correct invocation. The absence of output/response information is a small gap, but it does not block correct use.

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 of 3 applies. The description reinforces that the skill belongs to a category and that names are unique, but it does not add significant parameter-level meaning beyond the already detailed 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 clearly states a specific action and object: 'Creates a skill under the given category.' It also adds scope ('under the given category') and domain constraints (active by default, unique names), which distinguishes it from category-level tools like createSkillCategory.

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

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

The description implies when the tool should be used but never names alternatives or exclusion conditions. It provides useful context such as category scoping and name uniqueness, but an agent is left to infer the difference from the overall tool family 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?

Annotations already provide the readOnly, idempotent, and destructive safety profile. The description adds useful behavioral context: the operation is scoped to the current business and category names must be unique within that business. It does not contradict any annotation, though it does not describe duplicate-name failure 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 mostly tight and front-loaded, with the real definition in the first sentence and useful examples and constraints afterward. It loses one point because the opening line 'Create a skill category' simply repeats the title before the substantive description begins.

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 operation with three fully documented parameters and annotations covering the safety profile, the description is complete enough to select and invoke correctly. The schema covers the required name and the optional icon and idempotency_key, while the description supplies business scope and uniqueness context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying that name is a business-scoped unique category label and by explaining the category-skill grouping relationship. It does not discuss icon or idempotency_key, but those are already fully described 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 clearly states a specific action and resource: 'Creates a skill category for the current business.' It also distinguishes this from the sibling createSkill by explaining that categories group skills, and it gives concrete trade examples. The uniqueness constraint further clarifies the tool's exact domain.

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

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

The intended use is implied rather than explicit: an agent can infer to use this when creating a category, not a skill, because 'Categories group skills.' However, the description does not name alternatives like createSkill, say when not to use it, or advise checking existing categories before using it despite the uniqueness requirement.

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 provide basic flags, so the description carries the full burden and does so richly: best-effort notifications, no activation step, reactivation vs new-membership semantics, group restrictions, and start-location precedence with the 400 BusinessLocationMissing condition. This is far more transparent than the annotations alone.

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 long but organized by lifecycle behavior, relation parameters, and start-location rules. Each section earns its place and adds non-obvious detail; there is no filler, repetition of the schema, or vague prose.

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 invocation-side guidance is exceptionally complete: lifecycle, identity linking, notifications, group restrictions, relations, and location edge cases are all covered. The only notable gap is that the return/payload semantics are not described, and with no output schema present the description could have stated what the successful response contains.

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?

Even with 100% schema coverage, the description adds crucial meaning: it explains that buddy_ids and lead_ids form the same relation from opposite sides, that phone/email act as identity-resolution keys, and that address/lat/long are ignored when start_location_type=office. This materially helps an agent choose correct parameter combinations.

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 'Creates a technician membership under the current business,' giving a specific verb, resource, and scope. It also distinguishes membership creation from the related update/delete and customer-creation tools, so an agent can tell exactly what this operation 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 gives strong contextual guidance: it explains identity linking, reactivation of suspended memberships, fresh membership creation after deleteTechnician, and actions that are not reachable via this API. It names deleteTechnician and points to lookup endpoints for group/service-area IDs, though it does not explicitly name updateTechnician as the alternative for modifying an existing technician.

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 signal a non-read-only, non-idempotent, non-destructive operation, and the description only restates that it creates a vehicle. It adds no behavioral detail beyond the annotation surface, such as owner-tier validation, idempotency-key behavior, or what a successful creation returns.

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 but redundant: Create a new vehicle repeats the title and name, and Creates a vehicle for the business fleet restates the same idea with only a small amount of added context. Both sentences do not earn their place.

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

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

The input schema and annotations carry most of the contextual load, making the tool callable with minimal risk. However, the prose leaves out return-value behavior and high-level side-effect or ownership guidance, so the definition is adequate but not 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 89% and the individual parameter descriptions are rich, with examples, constraints, requiredness, and domain notes. The tool description itself adds no parameter-level meaning, so it lands at the schema-heavy baseline without exceeding it.

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

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

The description states a specific action, create, and a specific resource, vehicle, and adds the business fleet scope, so an agent can distinguish it from delete/get/list vehicle tools. The first sentence repeats the title, but the body still communicates the intended operation clearly.

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 when-to-use guidance and no mention of alternatives. The description implies adding a vehicle to the fleet, but it does not explain when createVehicle is appropriate versus related operations such as replaceTechnicianVehicles or updateTechnician, even though some of those distinctions exist in parameter notes.

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 tool as destructive and idempotent. The description adds value by specifying it's a soft-delete and explaining the impact on existing bookings, which is beyond the annotation hints and helps the agent understand 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 short, with two sentences. The first sentence is repetitive of the title, which could be omitted, but overall it is efficiently structured without unnecessary detail.

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 core behavior (soft-delete) but does not explain return values, error cases, or requirements like permissions. With no output schema, more detail on expected outcomes would improve completeness.

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

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

Schema coverage is 100%, so the schema already describes the parameter (id). The description does not add any meaning beyond what the schema provides for the parameter itself, achieving only the baseline for high coverage.

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

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

The description clearly states the action (delete) and resource (customer), and explicitly mentions it's a soft-delete, which distinguishes it from a hard delete. It also contrasts with sibling tools like createCustomer and updateCustomer.

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

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

The description implies usage for removing a customer, and the soft-delete behavior provides context. However, it does not explicitly state when not to use it or when to prefer alternatives, such as updateCustomer.

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 indicate destructive and idempotent behavior, so the bar is lower. The description adds meaningful context beyond the annotations: the deletion is soft, and system rows are protected from deletion. No contradiction with 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 brief sentences, front-loaded with the core purpose and followed by a key behavioral constraint. Every sentence earns its place with no unnecessary text.

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

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

For a simple one-parameter delete operation with strong annotations, the description is mostly complete. It covers the essential soft-delete behavior and the system-row restriction, though it does not mention what happens if a system-row ID is passed or describe the response.

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 the single 'id' parameter already documented as 'Job Type ID'. The description adds no new parameter-level details, but it does contextualize the parameter by noting that system rows cannot be deleted, which is useful but not required for the parameter itself.

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 the specific operation (delete) and resource (job type), and adds the important distinction that it is a soft delete. The resource is clearly named, so an agent can distinguish it from the many other delete* sibling 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 usage: call this when you need to delete a non-system job type. It also provides one exclusion, stating that system rows cannot be deleted, but it does not explicitly contrast with alternatives or describe when a different tool should be used.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered by structured data. The description adds the 'soft deletes' nuance, which is useful, but does not explain what soft deletion means for downstream references or whether it is reversible.

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 very short and front-loaded. The second sentence adds a meaningful distinction ('soft deletes'), though it is partially redundant with the title.

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

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

For a simple one-parameter delete tool with strong annotations, the description is mostly adequate. However, it leaves out effects of soft deletion on existing assignments or related resources, and with no output schema a brief note on return behavior would have improved completeness.

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 covers the single required id parameter fully with the description 'Service Area ID', so the description need not add much. It adds no extra meaning beyond the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb ('delete') and resource ('service area'), making the tool's function immediately clear. It is distinguishable from sibling delete tools by naming the service area resource, though it does not go far beyond the title's level of specificity.

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?

No guidance is provided on when to use this tool versus alternatives such as deleteCustomer, deleteTechnician, or deleteVehicle. The description gives no context about prerequisites, when soft deletion is appropriate, or when a different delete tool should be chosen.

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 the tool as destructive and idempotent, so the description adds value by specifying that deletion is permanent, identifying the exact error code SKILL_HAS_MEMBERS (409), and explaining the blocking condition. This goes beyond the structured hints without contradicting them.

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

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

The substantive description is only two sentences, front-loads the permanent-deletion behavior, and includes the key constraint. The first line 'Delete a skill' duplicates the title and adds no real information, which keeps the score from being a 5.

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

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

For a simple one-parameter destructive operation with no output schema, the description covers the core behavior, the failure mode, and the required prerequisite. An agent has enough context to call the tool correctly and interpret the primary error response.

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 input schema has 100% coverage for the single 'id' parameter and already describes it as a Skill ID (UUID). The description adds no additional parameter-level detail, so the schema carries the full burden and the baseline score 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 states a specific verb and resource: 'Permanently deletes a skill.' This clearly distinguishes the operation from sibling tools like deleteSkillCategory and deleteTechnician, and adds a concrete error condition that defines the operation's scope.

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 operational guidance: it warns that the deletion will fail with SKILL_HAS_MEMBERS if active technicians are assigned and instructs the caller to unassign all technicians first. It does not explicitly contrast alternatives or state when not to use the tool, but the precondition is clear.

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

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

Annotations already mark the tool as destructive and non-read-only. The description adds the meaningful behavioral detail that calling it returns SKILL_CATEGORY_NOT_EMPTY (409) if skills remain, which helps the agent anticipate failure modes. 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 core guidance is compact and valuable, with the permanent-deletion fact and error condition in one clear sentence. The opening line 'Delete a skill category' merely repeats the title, but the overall description remains tight and readable.

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 destructive tool with no output schema, the description covers the essential behavior and the main failure case. It could mention the success response shape, but this is not critical 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?

The schema already documents the single id parameter with 100% coverage, so the baseline is 3. The description references the category context but does not add further parameter-level meaning beyond the schema.

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

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

The description states a specific verb and resource: 'Permanently deletes a skill category.' It clearly distinguishes from sibling tools like deleteSkill by referring to the category concept and the skills-belonging dependency.

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 by stating the prerequisite: remove or move all skills before deleting the category. It does not explicitly name alternatives, but the condition for successful use is concrete and actionable.

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 destructiveHint=true and readOnlyHint=false. Description adds the 'soft-remove' detail (sets status to deactive), which is beyond annotations, but lacks other behavioral context like reversibility or permission requirements.

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

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

Two sentences, no filler. Could be slightly more concise but overall well-structured and 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?

No output schema provided, and description does not mention return value or confirmation. As a destructive tool, more completeness would be expected (e.g., what happens on success/failure, idempotence implications).

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 covers the 'id' parameter completely (100% coverage). Description does not add additional meaning to the parameter, so baseline score 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?

Description clearly states verb (remove) and resource (technician), and specifies it's a soft-remove by setting status to deactive. This distinguishes it from createTechnician or updateTechnician.

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?

No guidance on when to use this tool vs alternatives (e.g., updateTechnician to deactivate instead). No exclusion criteria or prerequisites mentioned.

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

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

The description discloses that the operation is a soft delete, adding nuance beyond the annotations' destructiveHint and idempotentHint. It clarifies that the vehicle is not permanently purged, though it does not explain the observable consequences such as visibility in list calls or restoration 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 extremely short and the key detail 'soft deletes' is present, but the first line 'Delete a vehicle' is redundant with the title. Apart from that minor waste, the definition is appropriately sized and easy to parse.

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 annotations covering safety and idempotency, the definition is largely sufficient to invoke it. However, 'soft deletes' is left unexplained—there is no statement about what happens to the record, whether it can be restored, or what response to expect, and there is no output schema to fill the gap.

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

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

Schema description coverage is 100% and the only parameter, id, is documented as 'Vehicle ID'. The description adds no parameter-specific meaning, but at this coverage level it does not need to; the baseline of 3 applies.

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

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

The description uses the specific verb 'soft deletes' and identifies the resource 'vehicle', clarifying both the action and the object. This distinguishes it from hard-delete operations and from sibling delete tools for other resource types, even without opening the schema.

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

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

Usage is implied by the resource name and 'soft deletes' phrasing, but the description gives no explicit when-to-use guidance, exclusions, or alternatives. Sibling delete tools exist for other resources, but the description does not explain when to choose this tool over them or mention any prerequisites.

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 readOnlyHint=true and destructiveHint=false. The description adds specific returned fields (preferred_technician, service_area, address coordinates) and notes that coordinates can be null. No contradiction.

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

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

The description is clear and front-loaded, but includes some detail that could be more concise. Still, it is well-structured and informative.

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?

Description compensates for missing output schema by listing key returned fields and noting nullability. It is fairly complete for a read tool with one parameter.

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 'id' with schema description 'Customer ID (UUID)'. The description does not add further semantics beyond the schema. Schema coverage is 100%, so baseline is 3.

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

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

The description clearly states 'Get a customer' and elaborates that it returns the full customer record including profile, contact details, tier, and spending summary. It distinguishes from siblings like listCustomers (list) and updateCustomer (modify).

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 mentions use cases: 'for support, upsell or CRM enrichment', providing context on when to use. However, it does not explicitly state when not to use or list alternative 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about the response contents, but it does not disclose error behavior, authorization requirements, or any other non-obvious traits beyond what annotations provide.

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

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

The description is concise and well-structured: a short identifying opener followed by a compact enumeration of returned fields and the intended use case. No filler or redundant content is present.

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 get-by-id tool with one parameter, the description adequately covers the return value and use case. There is no output schema, so the explicit list of fields helps compensate. It stops short of noting potential error conditions, but given the low complexity this is a minor gap.

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

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

The schema has 100% description coverage for the single 'id' parameter, including that it accepts a UUID or short_code. The description does not need to add parameter detail and does not go beyond the schema, so the baseline of 3 applies.

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

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

The description uses the specific verb 'Get' with the resource 'job request' and then details the contents of the returned work order (status, duration, schedule, customer contact, technician/crew). This makes the tool's purpose clear and helps distinguish it from listJobRequests or getJobRequestTimeline, though it does not explicitly name those 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?

The phrase 'everything a dispatcher or an external field-operations system needs to track one job' implies this is the go-to tool for retrieving a single job request's full details. However, it does not explicitly state when to prefer this over getJobRequestTimeline or listJobRequests, nor does it mention any exclusions.

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 declare readOnlyHint=true, aligning with timeline retrieval. The description adds key behavioral context, such as that entered_at may be null for upcoming steps and older jobs, which goes beyond 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 front-loaded with the core purpose and is within 5 sentences. However, it redundantly repeats the title 'Job timeline' as the first line and could be slightly more economical.

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?

Despite no output schema, the description fully explains the return format: each status includes state, entered_at, and actions. This provides sufficient context for the agent to handle the output 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 the parameter 'id' fully described in the schema. The tool description does not add extra semantic meaning beyond what the schema 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 tool is explicitly described as providing a per-status progress of a job's lifecycle, with a specific sequence and detailed state information. This clearly distinguishes it from sibling tools, none of which are timeline-oriented.

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

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

The description states 'render it as a job-tracking timeline,' implying its use for displaying job progress. However, it neither explicitly states when to use this tool over alternatives nor provides exclusions or when-not-to-use 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 indicate readOnlyHint=true. The description adds value by explaining the return includes a localized display name and provides concrete examples. No contradictions.

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

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

Two sentences with no extra words. Front-loaded with the tool's purpose. Efficient and clear.

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, single-parameter, read-only tool without output schema, the description is complete. It explains the return value (one entry with localized name) and gives examples. No missing information.

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 a single parameter 'id' described as 'Job Type ID'. The description does not add additional parameter meaning beyond the schema, so baseline score 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 clearly states 'Get a job type' and explains it returns one entry of the service catalog with a localized display name. Examples (HVAC tune-up, drain cleaning) add clarity. It distinguishes from sibling listJobTypes by specifying single entry retrieval.

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 use for retrieving a single job type by ID, but does not explicitly state when to use this tool versus listJobTypes or other siblings. No when-not or alternative guidance is provided.

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 readOnlyHint=true, so safety is clear. Description adds that it returns geometry metadata but does not detail other behavioral aspects. With annotations covering safety, a score of 3 is appropriate.

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

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

Two sentences, no redundancy. First sentence states purpose, second adds detail about return value and usage. Efficient and well-structured.

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, no-output-schema tool, the description adequately explains return fields (name, geometry metadata) and use case (territory-aware dispatch). Sufficient for an agent 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 description 'Service Area ID'. Description mentions 'UUID' and 'reference its UUID', adding slight context beyond schema. However, this is minimal enhancement over baseline 3.

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

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

The description clearly specifies the verb 'Get' and resource 'service area', explaining it returns a geographic coverage zone with name and geometry metadata. It distinguishes from 'listServiceAreas' by targeting a single record via ID.

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 context for use: referencing the UUID as `service_area_id` on customer records for territory-aware dispatch. While not explicitly stating when not to use, the sibling 'listServiceAreas' implies alternative for listing.

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 and destructiveHint=false, so the safety profile is clear. The description adds value by detailing the returned data ('full profile', 'dispatch-ready view'), which is beyond what annotations provide. No contradictions.

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 to the point, with a clear title and a list of returned fields. It front-loads the purpose. One could argue the title repeats the name, but overall it is 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?

Given the simple one-parameter input and no output schema, the description sufficiently explains what is returned. It lists the key fields, which helps the agent understand the tool's output. However, it could mention potential error conditions like 'invalid ID'.

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 one parameter 'id' described as 'Technician ID'. The description does not add additional meaning to the parameter beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states 'Get a technician' and lists the specific fields returned ('contact info, employment status, assignment tier, skills/qualifications, buddy relations, assigned vehicles'). The verb is 'Get', resource is 'technician', and it distinguishes from siblings like listTechnicians (list) and updateTechnician (update).

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

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

No explicit when-to-use or when-not-to-use guidance. The description implies usage for fetching a single technician's full profile, but does not mention alternatives or context where other tools would be more appropriate.

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 readOnlyHint=true. Description adds details about date range behavior (defaults, inclusive, 31-day max), which are not in annotations. No contradictions.

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 the core purpose. The second sentence is dense but packed with necessary details. Could be slightly more concise but not overly verbose.

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?

No output schema, so description should explain return format. It mentions 'job session on their lane (solo/lead and crew) plus approved time-off blocks' but lacks structure details (e.g., list of objects). Could be more complete.

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

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

Schema coverage is 100%, but description adds meaning beyond schema: explains 'business-local' dates, defaults, and inclusive ranges. This helps clarify usage beyond the schema descriptions.

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

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

The description clearly states it shows a technician's actual occupancy including job sessions and time-off blocks. It uses specific verbs like 'real schedule' and distinguishes it from the 'get crew availability' endpoint.

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?

Explicitly explains when to use (to see actual occupancy over a date range) and suggests combining with technician-availability endpoints for full availability. Also specifies default date ranges and maximum range.

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 and destructiveHint=false. The description adds value by specifying the returned fields (identity, plate, status, technicians) and the fleet-management context, without contradicting 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 core purpose. The second sentence adds relevant detail. Could be slightly more concise but not wasteful.

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 no output schema, the description reasonably covers the return structure (key fields). A simple getter with one parameter, this is adequate for an AI agent.

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 has 100% coverage with parameter 'id' described as 'Vehicle ID'. The description does not add additional meaning or constraints 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 title 'Get a vehicle' and description clearly state it returns a single fleet vehicle with specific details (identity, plate, status, technicians). It distinguishes from siblings like listVehicles (which lists all).

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

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

The description implies usage for retrieving a single vehicle but does not explicitly state when to use versus alternatives (e.g., listVehicles). No exclusions or prerequisites mentioned.

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, and the description adds meaningful behavior beyond that: the current lead and buddies are deliberately excluded, an empty leads list is normal on small rosters, 409 errors are possible, and candidates carry a score breakdown and on-site session plan. No contradiction with annotations exists.

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 dense but every sentence adds a distinct fact: purpose, stage constraints, exclusions, alternatives, matching criteria, response content, defaults, and force_lead_id behavior. The core purpose is front-loaded and no filler is present.

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?

Despite lacking an output schema, the description effectively communicates the return payload (ranked leads, per-slot buddy pools, vehicle list, score breakdown, session plan), error semantics, and normal empty case. All four parameters are behaviorally covered, and sibling-tool routing is complete.

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

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

Although the input schema has 100% description coverage, the tool description enriches the parameters by explaining defaults ('returns the ranked feasible LEAD pool by default'), the effect of include_buddies/include_vehicle, and force_lead_id's behavior including the 409 NO_TECHNICIAN_AVAILABLE fallback. This goes well beyond the schema's basic field descriptions.

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

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

The description clearly identifies the tool as matching/listing re-staffing candidates for a confirmed scheduled job, with the specific resource being the crew candidate pool. It further distinguishes itself from sibling tools by stating it is NOT a raw roster list and names the pre-booking discovery alternatives.

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?

Explicitly states when to use: for RE-STAFFING a CONFIRMED, SCHEDULED job not yet completed/archived, and that any other stage yields 409 JOB_REQUEST_INVALID_TRANSITION. It also directs users to listJobRequestBookingWindows/listMatchingSlots for pre-booking and GET /technicians for raw roster, giving clear exclusions and 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 indicate readOnlyHint=true and destructiveHint=false. Description adds behavioral details: pagination, searchability, and cursor-based incremental sync, which are 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?

Description is two concise sentences, front-loaded with the core purpose, and no unnecessary words.

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

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

Given 8 parameters and no output schema, the description adequately frames the tool's purpose, pagination, and incremental sync capability. It lacks output details but is sufficient for most use cases.

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 individual parameter descriptions. The description provides overall context (searchable directory, cursor sync) but does not add significant meaning beyond what the schema already offers for each 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?

Title and description clearly state 'List customers' and elaborate that it returns a paginated, searchable directory. It distinguishes itself from sibling tools like getCustomer (single record), createCustomer, and deleteCustomer.

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?

Description highlights usage for CRM, booking, and work order contexts, and mentions incremental sync via cursor. However, it does not explicitly state when not to use it or provide direct 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 are consistent (not readOnly, not destructive). Description adds behavioral details: ETA from start location, no live GPS, displacement preview, crew_recommendation, and error conditions. No contradictions.

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?

Well-structured with front-loaded purpose and ranking logic. Error codes are clearly listed. Slightly long but every sentence adds value; could be more concise.

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?

No output schema, but description thoroughly explains return values (ranked technicians, crew_recommendation, displacement preview, total_moves, ETA) and error handling (409 codes). Complete for a complex tool.

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 covers all 5 parameters with descriptions (100% coverage). Description adds context for mode (cascade behavior) and start_at (business-local naive datetime), slightly exceeding schema info.

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 tool ranks technicians for a P0 emergency insert, sorted by fastest arrival. It differentiates from siblings like listCrewCandidates and listNearbyTechnicians by focusing on emergency dispatch with displacement previews.

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?

Explicitly states when to use (P0 emergency), ranking logic, and what the response includes. Provides detailed 409 error codes with next steps and alternative flows (normal confirm, reassign) for unsupported 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 description adds behavioral context beyond the readOnlyHint annotation, explaining the real-time nature of the data (based on technician capacity, working hours, service territory) and the purpose of preventing unschedulable bookings. No contradictions with 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 relatively concise (4 sentences), but the first sentence is redundant as it repeats the title. The remaining sentences provide value. Could be slightly shorter by removing the first line.

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 no output schema, the description lacks details on the return format (e.g., structure of time windows, pagination, error handling). It covers the core purpose and usage but leaves some gaps for a comprehensive understanding.

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?

Input schema already describes all 3 parameters (to, from, x_timezone) with 100% coverage. The description does not add parameter-specific details beyond that, but implies a date range context. Baseline score of 3 is appropriate as schema does the heavy lifting.

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 specifies the verb 'list' and resource 'booking windows' clearly. It explains that it returns bookable date/time windows based on technician capacity, working hours, and service territory coverage. While it doesn't explicitly differentiate from sibling 'listMatchingSlots', the context implies a distinct role in preventing unschedulable bookings.

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 advises calling this before creating a job request and offering only the returned windows to prevent unschedulable bookings. This provides clear when-to-use guidance, though it does not list when not to use or mention 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 readOnlyHint=true, but the description adds materially beyond that: the server primes the cursor at 'now' on first poll, re-scans a ~5s safety window causing duplicate deliveries, orders results by updated_at ASC, and includes soft-delete/archive changes. No contradiction with 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 long but every sentence is load-bearing: it teaches a stateful protocol that is easy to get wrong. The content is front-loaded with the core concept, then organized as a numbered how-to, with the important caveat ('never blindly append') placed inline. No fluff.

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

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

Despite having no output schema, the description fully specifies return mechanics (next_since, has_more, item ordering, duplicate re-delivery) and usage lifecycle. For a stateful sync-feed tool this is exactly the information an agent needs to call it correctly without guessing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by explaining cursor lifecycle (omit `since` to prime, use `next_since` from the response), `limit`/`has_more` interaction, and how filters narrow the feed. It doesn't enumerate each filter parameter, but the schema already documents those adequately.

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 ('Poll'), resource ('job requests'), and the distinguishing property ('new & changed', sync feed). It explicitly contrasts with paginated listing, and the title reinforces the purpose. An agent can tell it apart from listJobRequests without opening the schema.

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 numbered usage protocol: omit `since` on first poll, store `next_since`, pass it back, upsert on `id`, and re-poll when `has_more` is true. It also tells the agent when NOT to use it ('This is NOT pagination') and directs the initial bulk load to GET /job-requests.

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 declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral details: pagination, date range semantics (end-of-day, exclusive boundaries), and the distinction for completed_from/to. No contradictions.

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

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

The description is concise: two short paragraphs, no superfluous text. It front-loads the core purpose and then elaborates on the schedule use case. Every sentence is informative.

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 14 parameters, no output schema, and readOnlyHint annotation, the description covers all essential aspects: purpose, filters, pagination, scheduling use case, and date semantics. It is complete enough for an agent to use effectively.

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?

Input schema has 100% coverage with descriptions for all 14 parameters, so the baseline is 3. The description adds context on combining parameters for scheduling and explains date range behavior, providing additional value.

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 tool lists job requests (bookings) with dispatch-oriented filters, and explicitly identifies it as the schedule query for reading technician agendas. This distinguishes it from siblings like listTechnicians and getTechnicianSchedule.

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

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

The description gives explicit usage guidance, e.g., combining technician_id + scheduled_from/scheduled_to for schedule queries, and listing filters. It does not explicitly mention when not to use it or compare to alternatives, but the context is sufficient for an agent.

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, so the agent knows it's safe. The description adds value by describing the return content (service catalog with examples) and the filter parameter. It does not mention pagination or ordering, but for a simple catalog list this is acceptable.

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

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

Two sentences with no wasted words. First sentence states the action, second provides context and examples. Well-structured 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?

Given the simplicity of the tool (one optional parameter, no output schema, clear annotations), the description is fairly complete. It covers purpose, use cases, and return values. Minor omission: no mention of pagination or ordering, but not critical for this type of tool.

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% and the schema description already explains the status parameter. The description adds no additional parameter details beyond the schema, but the overall context of the tool's return values helps usage. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists job types and returns the business's service catalog. It provides examples (installation, repair, maintenance) and distinguishes from getJobType by emphasizing the list behavior and use cases like discovering job_type_id.

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 says to use it to discover job_type_id or render a services menu. While it doesn't mention when not to use it, the context is clear and the sibling tool getJobType is implied for single type lookup.

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=true), the description adds rich behavioral detail: the engine checks skills, availability, schedule, time off, travel, and provides per-technician match scores. It also explains slot width override. No contradictions.

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 with purpose and provides details in a structured paragraph. It is efficient but slightly verbose; each sentence adds value. No 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?

Despite no output schema, the description explains the output structure (technician availability and match scores) and compares it to the customer slot picker. It covers the return format and usage flow adequately.

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

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

Schema coverage is 100%, so baseline is 3. The description provides no additional meaning beyond what the schema already states for both parameters (id and step_minutes).

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 title and description clearly state the tool computes matching time slots for a quoted job using a smart-assignment engine, distinguishing it from sibling tools like listJobRequestBookingWindows. It specifies the resource (time slots) and the action (list matching).

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 says to use it after quoting the job and mentions the next step (confirm via POST endpoint). It provides context for use but does not list when not to use or alternative conditions.

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?

Description details ETA origin (no live GPS), application of real hard filters (hours, schedule, time-off, service areas, skill), and return order. Annotations read-only hint is consistent.

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

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

Two concise sentences plus usage note, front-loaded with purpose. No unnecessary words.

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

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

Adequate for a query tool but lacks output structure details. Mentions return order and filters but not fields returned (e.g., technician ID, ETA). No error handling info.

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 has 100% coverage with parameter descriptions. Description adds no extra per-parameter meaning; it explains overall behavior but not syntax or constraints beyond 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 clearly states the tool finds nearby feasible technicians for a hypothetical visit, with ranking and filtering. It distinguishes from sibling tools like listTechnicians (no location filter) and listEmergencyCandidates.

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?

Explicitly advises use before creating a booking to propose realistic arrivals. Context implies not for emergencies or listing all technicians, but no explicit when-not-to-use.

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 read-only and non-destructive. Description adds that results are paginated, but does not reveal additional behavioral traits beyond what is already covered 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?

Description is two sentences, front-loaded with title and then adds context. No unnecessary words, efficient and clear.

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 list tool with good annotations and full schema coverage, this description is complete: it explains the return value, pagination, and a key use case.

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

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

Schema coverage is 100%, and description does not add extra meaning for page/limit beyond what is in the schema. Baseline score 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?

Clearly states it lists service areas; explains it returns geographic coverage for routing and provides a specific use case (discovering service_area_id for customer create/update). Distinguishes from sibling getServiceArea.

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?

Implies usage for discovering IDs for customer operations, which guides when to use. Does not explicitly mention alternatives, but the context is clear given sibling 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 indicate readOnlyHint=true and destructiveHint=false. The description adds value by noting paginated results and alphabetical ordering, providing behavioral context beyond the structured fields.

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

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

Two sentences with no waste. The title is repeated efficiently, and the key details (paginated, alphabetical, explanation of categories) are front-loaded and concise.

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

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

Given the tool's simplicity, annotations covering safety, and schema covering parameters, the description is largely complete. The explanation of what skill categories represent adds useful context. No output schema exists, but for a paginated list tool this is acceptable.

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 well-described page and limit parameters. The description adds no additional parameter meaning beyond what the schema already provides, meeting the baseline but not exceeding it.

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

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

The description clearly states the tool lists skill categories and explains they represent technician qualification groupings by trade or specialty (e.g., HVAC, plumbing). This specific verb+resource definition distinguishes it from sibling tools like listSkills, which list individual skills, not categories.

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 tool is for browsing categories, but it does not explicitly state when to use it versus alternatives like listSkillsByCategory. Sibling names provide context, but the description lacks direct usage 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, so the tool is safe. The description adds behavioral context: returns flat list of active skills, used for dispatch matching, and purpose of UUID discovery. No contradictions.

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

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

Two sentences, no wasted words. First sentence front-loads the main action, second provides context and alternative. Highly concise.

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 zero parameters and no output schema, the description fully covers purpose, use case, and relationship to siblings. No gaps remain.

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?

No parameters exist; schema coverage is 100%. The description does not need to add parameter details. It appropriately focuses on the tool's purpose.

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 it lists all active technician skills/qualifications, using specific verb+resource. It distinguishes from sibling listSkillsByCategory by mentioning the category-grouped 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?

The description explicitly tells when to use this tool (discover skill UUIDs for creating job requests) and provides an alternative (listSkillsByCategory) for a different view.

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 and destructiveHint=false. The description adds valuable behavioral context: pagination behavior, alphabetical ordering, and meaning of the 'members' field. No contradictions.

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 efficiently convey purpose and key details. No redundant phrases. 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?

With 3 parameters, no output schema, and high schema coverage, the description adequately explains pagination, ordering, and field meaning. It lacks return structure but the explanation of 'members' field partially compensates. Slightly more detail on response format would improve completeness.

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 documentation covers all 3 parameters (id, page, limit) with clear descriptions. The description adds no new parameter-level information beyond restating the category context for id. Baseline 3 is appropriate due to high schema coverage.

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

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

The description clearly states it lists skills in a category, specifying they are technician qualifications/certifications, paginated, ordered alphabetically. This distinguishes it from sibling tools like listSkills (all skills) and listSkillCategories (categories only).

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 indicates when to use (for a given category) by mentioning 'belonging to the given trade/specialty category'. However, it does not explicitly state when not to use or contrast with listSkills for unfiltered listing, leaving some ambiguity.

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 as readOnlyHint=true and non-destructive. Description adds behavioral details: pagination, cursor support, and specific output fields (status, tier, skills, crew relations). No contradiction with 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?

Four sentences with slight redundancy (first sentence repeats title). Still efficient and front-loaded with key information. Could trim the first sentence without loss.

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?

Provides a complete picture for a list tool: explains returned fields, pagination, cursor for sync, and a practical use case (preferred_technician_id). No output schema needed; description suffices.

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 covers all 7 parameters (100% coverage). Description adds value by explaining `since` cursor usage and linking to preferred_technician_id, going beyond schema descriptions.

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

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

The description clearly states it lists technicians (field workers) with status, tier, skills, crew relations, and explicitly links to dispatch scheduling. It distinguishes from sibling tools like getTechnician or createTechnician by focusing on roster listing.

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 usage guidance such as discovering preferred_technician_id and using `since` cursor for incremental sync. Lacks explicit when-not-to-use or alternatives among similar list tools like listNearbyTechnicians or listTechnicianSkills.

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 signal readOnly. The description adds value by clarifying pagination and the default filtering for active skills via eligible_only. No contradictions.

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

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

Two concise sentences with no fluff. The key information (purpose and filtering nuance) 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 read-only list tool with complete schema coverage, the description adequately explains pagination and filtering. No output schema exists, so return format is not expected.

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 provides full parameter descriptions. The description adds meaning for eligible_only by explaining its default and effect, enhancing the schema's description.

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

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

The description clearly states it lists skills for a specific technician, differentiating from listing all skills (e.g., listSkills). The verb 'list' and resource 'skills for a technician' are specific.

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 explains the default behavior of eligible_only but does not explicitly state when to use this tool versus alternatives like listSkillsByCategory or listSkills. Usage context is implied but not contrasted.

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. Description adds key behavioral traits: pagination, status filtering, and cursor-based incremental sync.

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?

Extremely concise: one sentence for purpose, one for key capability. No filler. 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?

Covers pagination, filtering, and incremental sync. No output schema, but description adequately explains returns (fleet with status). Minor: could mention response 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?

Schema description coverage is 100%, so description adds little beyond confirming the `since` cursor's purpose. Baseline 3 is appropriate.

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

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

The description clearly states it lists vehicles and returns the fleet with operational status. It distinguishes from siblings like getVehicle (singular) and listTechnicians, etc.

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?

Context is clear: returns fleet with pagination and incremental sync. No explicit when-not or alternatives, but the purpose is unambiguous given sibling context.

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?

Description claims 'Read-only' and 'Computes (WITHOUT writing)' but annotation readOnlyHint is false, constituting a direct contradiction. This undermines agent trust.

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?

Well-structured with front-loaded purpose, mode details, safety note, and error codes. Slightly long but every section 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?

Covers essential behavior and error handling, but no output schema exists and description does not explain the return format (e.g., the structure of the preview). Adequate for a preview tool but could be more complete.

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

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

Schema coverage is 100% (all parameters described). Description adds contextual explanation of modes and displacement but does not provide significant value beyond the schema descriptions.

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

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

Clearly states it computes a cascade preview without writing, distinguishes from commit sibling via explicit 'Read-only — safe to call repeatedly; commit is a separate endpoint.'

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 error codes and next steps, mentions isolation feature reference. Could explicitly contrast with previewJobRequestMove or state when not to use, but context is adequate.

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?

Annotation Contradiction: the description repeatedly states 'WITHOUT writing', 'Read-only — safe to call repeatedly', yet the annotations declare `readOnlyHint: false` and `idempotentHint: false`. This directly contradicts the most important behavioral trait of the tool. Per the rubric, a contradiction with annotations forces a score of 1 despite the otherwise rich behavioral 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?

The description is well-structured and front-loaded, with the core purpose in the first sentence and organized sections for warnings and errors. However, it is very long and repeats some schema-supplied details such as mode semantics and technician equality. The exhaustive 409 error catalog is valuable but could be condensed or placed in referenced documentation without losing much utility.

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 complex preview operation with no output schema, the description is remarkably complete: it covers outcome computation, cascade behavior, warning semantics, error conditions, and temporal constraints. The one significant gap is not in the text itself but in the contradictory read-only annotation, which prevents the overall definition from being fully trustworthy.

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 input schema already covers all parameters at 100%, setting the baseline at 3. The description adds meaningful interpretive value by explaining that `mode` determines how later jobs are pushed back, that `technician_id` distinguishes pure time moves from manual reassigns, and that `earliest_feasible_at` should be suggested as a drop slot for infeasible moves. This goes beyond schema definitions.

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

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

The description opens with a specific verb and resource: 'Computes (WITHOUT writing) the outcome of moving a confirmed job to a new time and/or technician.' It clearly distinguishes preview from execution by saying 'commit is a separate endpoint' and from emergency reschedule by naming the job-move context. This is unambiguous and differentiates well from sibling 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 explicitly frames the tool as a read-only preview safe for repeated calls while dragging and points to commit as a separate endpoint, giving clear situational context. It does not name the exact sibling `commitJobRequestMove`, but the intent is obvious. It also gives extensive 409 error conditions that help the agent decide whether a move is even viable.

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 reveals that the tool mutates state (sets columns, advances pending_action) and notes that status remains 'booking'. Annotations already mark it as non-read-only and non-destructive. The description adds context about the idempotency key parameter, which aligns with the idempotentHint false annotation properly.

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 to the point. The first line repeats the title unnecessarily, but the second line provides the core functionality. It is efficiently structured with minimal waste.

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 7 parameters and no output schema, the description covers the main behavioral effects and state changes. It does not explain failure scenarios or prerequisites (e.g., job request must be in 'booking' status), but given the detailed schema descriptions, it is sufficiently complete for an agent to understand the tool's purpose.

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

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

Schema coverage is 100%, so all parameters are described in the schema. The description adds minimal additional meaning beyond stating the overall effect (e.g., 'sets duration cols' relates to job_duration_minutes). It does not elaborate on parameter details or constraints beyond what's 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 clearly states the tool's action: 'Sends the quote' and specifies the exact effects (sets quoted_at + duration columns, advances pending_action to confirm_booking). This distinguishes it from sibling tools like confirmJobRequest, which handles the next step.

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 tool is used after creating a job request and before confirming a booking, but it does not explicitly state when to use it versus alternatives like confirmJobRequest or commitJobRequestMove. No exclusions or prerequisites are mentioned.

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 indicate idempotentHint=true and destructiveHint=false, which are consistent. The description adds important behavioral details: buddy IDs must be active technicians of same business and no self-buddy. No contradictions.

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

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

The description is concise with two short paragraphs. The first line repeats the title but the second adds essential details. It is well-structured 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?

With 2 parameters and no output schema, the description provides sufficient behavioral context including edge case (empty list) and constraints. It covers the essential information for correct usage.

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%, baseline 3. The description adds semantic value beyond the schema: clarifies that empty list clears buddies and imposes constraints (active technician, no self-buddy) that are not in the parameter descriptions.

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

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

The description clearly states the action 'Replace a technician's buddies' and explains it overwrites the buddy list. The purpose is specific and distinct from sibling tools like replaceTechnicianLeads or replaceTechnicianServiceAreas.

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 explains that an empty list clears all buddies, providing clear context. It does not explicitly mention when not to use it or compare with alternatives, but the sibling tools have distinct purposes making the guideline adequate.

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 annotations (idempotentHint=true, destructiveHint=false), the description explains that lead_ids is the complete new list and that [] clears all leaders, providing key behavioral context for a replace 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 concise with two sentences plus a title, each sentence providing essential information without 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?

The description covers purpose, behavior, parameter semantics, and access context (business staff), which is adequate for a replace tool with good annotations.

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 descriptions, but the description adds value by clarifying replace semantics and the clearing behavior for empty array, which is not explicit 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 clearly states the verb 'replace' and resource 'buddy's leaders', and distinguishes from sibling tools like replaceTechnicianBuddies. It explains replace semantics and the scope of the operation.

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

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

The description implies usage context through replace-semantics and mention of business staff, but does not explicitly state when to use vs alternatives or provide when-not 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?

The description adds significant behavioral details beyond annotations: overwriting semantics, clearing via empty list, atomic partial failure (404 with no writes), and that the result is returned and embedded in technician responses. Annotations confirm idempotent and non-destructive nature, no contradiction.

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

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

The description is a single paragraph that is well-structured and front-loaded with the main action. It contains necessary details without fluff, though it could be slightly more concise by merging some sentences. Still, it is efficient and clear.

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

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

Given the tool's low complexity (2 parameters, no output schema) and the presence of annotations, the description covers all essential aspects: purpose, behavior, error handling, side effects (embedded in get/list), and access control. It is fully adequate for an agent to use 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 covers both parameters with descriptions. The description adds valuable context: clearing with empty list, error handling for missing service_area_ids, and that the resolved set is returned. This goes beyond what the schema provides, enhancing understanding.

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 'Replace' and resource 'technician's service areas', and clearly states the action: overwriting assignments with provided IDs. This distinguishes it from sibling tools like replaceTechnicianBuddies or replaceTechnicianLeads, which operate on different resources.

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: it's managed by business staff (Booking Coordinator) and not for tech self-service. It also explains behavior for empty input and error handling. While it doesn't explicitly compare with alternatives, the sibling tools are distinct enough that no further guidance is needed.

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 fully discloses the behavioral traits beyond the minimal annotations. It explains the replace semantics (removing/adding), constraints that all skills must be active and belong to the business, and specific error responses (SKILL_NOT_FOUND with missing_ids, SKILL_INACTIVE with inactive_ids). No contradictions with 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 concise with only two sentences in the second paragraph, but the first line is a header-like repetition. The structure is clear with a brevity introduction followed by detailed behavioral notes. Minor verbosity is acceptable, but could be slightly tighter.

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

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

Given the tool's low complexity (2 parameters, no output schema), the description covers all essential aspects: operation semantics, parameter constraints, error conditions, and clearing behavior. It is fully self-contained and requires no additional information for correct usage.

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 100% schema description coverage, the baseline is 3, but the description adds significant value beyond the schema. It explains the replace semantics apply to both parameters, clarifies that skill_ids must be active and belong to the business, and details the error response structures. The example and maxItems in schema are complemented by practical usage guidance.

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 name and title clearly indicate the action: replacing a technician's skills. The description explicitly states 'replace semantics' and details that skills not in the list are removed and new ones added, distinguishing it from sibling tools like listSkillsByCategory or replaceTechnicianBuddies, which target different resources.

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 explains the replace semantics and mentions passing an empty list to clear all skills, providing clear context for usage. However, it does not explicitly state when not to use this tool or suggest alternatives, which is a minor gap. The context from sibling tool names partially compensates.

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

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

The description discloses that the operation is an overwrite, which is idempotent as per annotations. It adds value by noting that the vehicle list is embedded in the technician GET/list response. No contradictions with 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 concise: a short title followed by two sentences that efficiently convey the core behavior and constraints. No unnecessary words.

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

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

Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description sufficiently explains the operation: overwrite behavior, clearing via empty list, business consistency, and where to find vehicle IDs. It also mentions the response embedment.

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 description adds significant context beyond the schema: for vehicle_ids, it explains that an empty list clears all, each ID must be from the same business, and suggests discovering via GET /vehicles. For id, it simply states 'Technician ID'. With 100% schema coverage, this is excellent.

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

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

The description clearly states the action ('Replace a technician's vehicles') and resource, elaborating with 'Overwrites the technician's vehicle list with the provided set of vehicle IDs'. This distinguishes it from sibling tools like replaceTechnicianBuddies and replaceTechnicianSkills.

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 guidance on usage: 'Sending an empty list clears all' and 'Each vehicle ID must belong to the same business'. It also suggests discovering vehicle IDs via GET /vehicles. However, it does not explicitly state when to use this tool versus alternatives, which is implicit given the specific resource.

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 declare readOnly=false, idempotent=true, destructive=false. The description adds substantial behavioral detail: omitted fields are left unchanged, empty strings clear fields, enum empty values are ignored, full_name cannot be emptied, address replacement is all-or-nothing with geocoding, and clearing both contact channels is refused. This is rich, non-obvious behavior that the annotations alone cannot convey.

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

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

The description is dense but every clause earns its place. The most important caveat — partial update semantics — is front-loaded, and the subsequent rules cover clearing, enums, address replacement, and validation without repetition or 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 complex 12-parameter mutation with many edge cases, the description covers all critical update behaviors, including an explicit error condition. No output schema exists, so the absence of return-value documentation is not a significant gap given how thoroughly the operation's semantics are specified.

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?

Although schema coverage is 100%, the description adds cross-cutting parameter semantics that tie the schema together: which fields accept empty-string clearing, how enum empty values are handled, the tri-state nature of sms_opt_in, and the all-or-nothing address object. This materially improves an agent's ability to construct correct update payloads.

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: update an existing customer. It goes further by immediately characterizing the operation as a PARTIAL update, which distinguishes it from create/delete/get siblings even without naming them.

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 title and lead sentence establish clear context for modifying an existing customer, and the partial-update semantics make the intended use unambiguous. However, it does not explicitly contrast with createCustomer, getCustomer, or deleteCustomer, so it lacks an explicit when-not-to-use statement.

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 annotations (readOnlyHint=false, etc.), the description reveals behavioral traits: it modifies the job, triggers SLA auto-escalation, disarms SLA when changing away from p1, and records notes on activity trail and webhook. No contradictions.

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 well-structured with a title line and a paragraph. Every sentence provides necessary information without fluff, making it concise yet comprehensive.

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?

Despite no output schema, the description fully covers the tool's behavior, constraints, prerequisites, and side effects. It is complete for a mutation tool of this complexity.

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 100% schema coverage, the description adds context beyond the schema: clarifies that sla_deadline is only valid with p1, must be future, and is business-local naive datetime. Also explains note's audit purpose.

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 'set' and the resource 'job priority', and specifies constraints (non-archived, non-completed). It distinguishes from sibling tools, which are mainly CRUD operations for other entities.

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 explains when to use the tool (for setting P0-P3 priorities), details allowed priority values with their meanings, and specifies constraints (sla_deadline only with p1). It lacks explicit when-not-to-use or alternatives, but context is clear.

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