Spoke Dispatch MCP by usefulapi

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

The annotations already declare write access, non-idempotency, and non-destructiveness. The description adds meaningful behavioral context beyond that: nothing is sent to drivers, drivers must be active and share the plan's depot, a depot defaults to the team's main depot, and the tool does not optimize or distribute. It does not cover error conditions or rate limits, but it is strong for an annotated write tool.

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

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

The description is a single, front-loaded sentence that begins with the operation type ('WRITE') and packs all constraints into clear parentheticals. Every clause adds useful information with no filler, making it easy to scan and act on.

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 tool has no output schema, so the description is the only source for behavioral context, and it covers creation semantics, side effects, driver/depot constraints, and exclusions well. It does not describe what the tool returns (e.g., a plan ID or object), which would be helpful for chaining calls, but the core invocation context 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?

Schema description coverage is 75%, so the schema documents most parameters. The description still adds valuable semantics not in the schema: driver_ids must be active drivers sharing the plan's depot and are capped at 50, and depot_id defaults to the team's main depot. These constraints materially affect correct invocation.

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 (create) and resource (route plan for a date) and immediately distinguishes the tool from siblings by noting that it creates no stops and sends nothing to drivers. It also explicitly rules out optimizing and distributing, which are separate sibling tools. An agent can identify this tool's exact role 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?

The description gives clear context for when to use it: to create a plan before stops exist, and it explicitly excludes optimization and distribution. However, it does not name the alternative tools (e.g., spoke_optimize_plan, spoke_distribute_plan) that should be used for those excluded actions, leaving that inference to the 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?

With annotations already covering write/non-idempotent/non-destructive, the description still adds material behavioral context: the plan must be in an undistributed state, recipient contact data is persisted on the stop, and Spoke may contact the recipient later even though 'nothing is sent now'. The deferred-side-effect timing is exactly the kind of thing annotations cannot express.

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 'WRITE:' and the precondition, then usage guidance, then the raw endpoint last. Three tight sentences, every one carrying information an agent needs.

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

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

For a mutation tool with no output schema and annotation coverage of the safety profile, the description covers prerequisites, side effects, and the bulk alternative. The one gap is that it never says what comes back (e.g. whether a stop id is returned for later use), which matters for a create-then-reference 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?

Top-level schema coverage is 0% (only the nested 'stop' object carries per-field descriptions), so the description does compensate by explaining the address requirement and the text-vs-lat/lng alternative. However it says nothing about plan_id semantics or the optional nested fields it doesn't repeat, so it only partially fills the gap.

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

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

States a specific verb ('add one stop') plus resource ('to a writable plan') and the critical precondition that the plan is not yet distributed. It is immediately distinguishable from spoke_import_stops (bulk) and from the getter siblings, so no schema opening is needed to disambiguate.

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 names the alternative and the condition that selects it: 'For many stops use spoke_import_stops.' It also states the when-not condition inline ('writable (not yet distributed) plan'), leaving nothing to inference.

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

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

Goes well beyond the annotations: it discloses that real people receive push messages, that the plan is locked for edits, that the action cannot be undone, and that a 1-10 driver limit applies. The annotations flag destructive/not-idempotent, but the description supplies the concrete operational consequences an agent needs.

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

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

Front-loads the critical warning 'WRITE (SENDS TO REAL PEOPLE)', then packs effect, irreversibility, constraints, and the confirmation requirement into a tight block of sentences with zero 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 destructive mutation tool with no output schema, the description covers the essentials: what gets sent, who receives it, side effects (lock), reversibility, scope limits, and the required confirmation. Nothing material is missing.

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

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

Schema coverage is 50% (only confirm_send_to_drivers is documented). The description compensates by explaining why that flag must be true (user explicitly asked to send routes), reinforcing its const:true constraint; plan_id is left implicit but its meaning is self-evident from the name and endpoint.

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 (distribute) and resource (optimized plan), plus the exact effect: sends each driver their route and locks the plan. It is clearly distinguishable from siblings like spoke_optimize_plan or spoke_update_plan, which do not send anything to real people.

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

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

Gives explicit preconditions: plan must have 1-10 drivers and the user must have explicitly authorized the send (confirm_send_to_drivers=true). It doesn't name an alternative tool by name, but the 'only after optimizing / explicit confirmation' framing makes the when-to-use boundary clear enough.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the endpoint mapping and says nothing about lookup failure behavior or return shape, so it clears the lowered bar but adds little.

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 very short clauses, front-loading the resource before the endpoint. Minimal waste, though the REST path restates information an agent rarely needs to act on.

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

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

For a one-parameter read tool with annotations covering the safety profile, the definition is nearly sufficient. The absence of an output schema means it could say more about the returned depot object, but nothing critical for invocation is missing.

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

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

Schema description coverage is 100% and the single depot_id parameter is documented with format examples ('abc' or 'depots/abc'). The description adds no format or constraint detail beyond the schema, so baseline 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?

States a specific verb and resource ('One depot by id') plus the underlying REST endpoint, so an agent knows exactly what entity is returned. It implicitly contrasts with spoke_list_depots by emphasizing single-id retrieval, though it never names the sibling explicitly.

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

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

There is no guidance on when to prefer this over spoke_list_depots, no prerequisites, and no mention of what to do if the id is unknown. The agent must infer usage purely from the tool name and schema.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral note, 'Contains personal data', plus the underlying REST path, but says nothing about error behavior (e.g. unknown id) or sensitivity-handling expectations. Useful addition, minimal depth.

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

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

Three short fragments with zero filler, and the purpose is front-loaded before the PII warning and route. Slightly telegraphic rather than sentence-formed, but nothing wasted.

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

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

For a single-parameter read-only lookup with full schema coverage and annotations carrying the safety profile, the description is adequate. The only residual gap is the return shape, and no output schema exists, though 'One driver' makes the return plausible enough not to block a correct call.

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

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

Schema description coverage is 100%, so the single driver_id parameter is already fully documented in the schema, including the 'abc' vs 'drivers/abc' format. The description adds no additional parameter semantics, 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?

States a specific verb and resource with a scope qualifier ('One driver by id'), which contrasts with the singular/plural distinction against the sibling spoke_list_drivers. It does not name the sibling outright, but the retrieval target is unambiguous.

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

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

Usage is only implied: 'by id' signals you should call this when you already hold a driver id rather than when browsing. There is no explicit statement of when to prefer this over spoke_list_drivers, and no preconditions or exclusions are given.

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, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds real behavioral context beyond them: this is a polling endpoint, the terminal condition is 'done is true', and the typical operation source is spoke_optimize_plan.

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

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

Two tight sentences: purpose, polling behavior, and endpoint. The critical polling instruction ('poll until done is true') is front-loaded and nothing is wasted.

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

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

For a one-parameter read tool with no output schema, it adequately conveys what the agent gets back (an operation with a done flag) and how to use it for polling. It stops short of naming other operation fields (progress, errors) that an agent polling a long-running job might need.

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 accepted id forms ('abc' or 'operations/abc'). The description's 'GET /operations/{operationId}' merely echoes that format, adding little beyond the structured field.

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

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

States a specific verb and resource ('One operation', 'GET /operations/{operationId}'), making it clearly the singular fetch counterpart to spoke_list_operations. It does not explicitly name that sibling, so differentiation is implied rather than stated.

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

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

Gives concrete context: it is used to poll an operation started by spoke_optimize_plan until 'done is true'. Names the originating tool and the polling pattern, though it does not state when not to use it (e.g. vs. spoke_list_operations for enumeration).

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully discloses the shape of the returned plan (distribution/writable flags, optimization state, route overrides), which matters because there is no output schema, but it says nothing about failure behavior such as an unknown plan id.

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

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

Two terse fragments, front-loaded with the returned field list and closed by the endpoint. Nothing is wasted, though the comma-run field enumeration is dense rather than elegant.

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 fully documented parameter and no output schema, the enumerated return fields are the key missing piece and they are present. Only error/permission behavior is left unstated, which 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?

Schema description coverage is 100% and the single plan_id parameter is documented in the schema with accepted id formats, so the schema carries the burden. The description adds no format or id-handling detail beyond that.

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 resource (a single plan) and enumerates the fields it returns, with the endpoint GET /plans/{planId} pinning the operation. The word 'One' implicitly separates it from spoke_list_plans, though no sibling is named explicitly.

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

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

No when-to-use guidance and no alternatives referenced. An agent must infer that this is the single-record lookup versus spoke_list_plans or spoke_list_plan_stops, and there is no mention of prerequisites such as a valid plan id or permissions.

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 carry readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered; the description adds real value by disclosing the response shape and the domain state vocabulary (distributed, started, completed, recipients notified). It omits auth requirements, error behavior, and pagination/absence handling, so not a 5.

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

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

Two sentences, no filler, with the return contents front-loaded before the endpoint reference. Every clause 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?

There is no output schema, so the description must sketch the return value, and it names four of the most relevant fields including the state enum. It is still not a complete picture of the returned route object (no id, dates, or nested driver/stop detail), leaving a small gap for a read 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 description coverage is 100% and the single route_id parameter already documents the accepted forms ('abc' or 'routes/abc'). The description's 'GET /routes/{routeId}' path template echoes but does not extend that meaning, so the schema carries the load.

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

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

States a specific verb+resource ('One route') and enumerates exactly what comes back: title, driver, stop count, and state with its enumerated values. The singular 'One route' distinguishes it from the sibling spoke_list_routes without needing to name it.

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 'One route' plus the 'GET /routes/{routeId}' endpoint template, which signals single-resource retrieval rather than listing. However, there is no explicit when-to-use-vs-spoke_list_routes guidance or any precondition stated.

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 covered. The description adds genuinely useful context not in annotations: that the payload contains personal data (PII handling implication) and the exact fields returned, including delivery outcome and photo/signature links.

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?

One dense sentence plus the endpoint template. The resource enumeration is long but each field listed earns its place by compensating for the absent output schema. Front-loaded with the resource identity before the field list.

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

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

With no output schema, the description carries the return-value burden and discharges it by enumerating the key returned fields. Combined with annotations covering the read-only profile and the PII warning, an agent has enough to call it correctly; only auth/permission details are missing.

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

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

Schema coverage is 50%: stop_id is documented with format examples ('xyz' or 'plans/abc/stops/xyz'), but plan_id has no schema description. The description's path template (GET /plans/{planId}/stops/{stopId}) confirms both parameters' roles but adds no new syntax or constraint detail, so this stays at baseline.

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

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

States a specific verb+resource: retrieves a single stop of a plan, and enumerates the resource contents (address, recipient, timing, ETA, route, delivery outcome). The singular 'One stop' implicitly distinguishes it from list_plan_stops/search_stops, but no sibling is named explicitly.

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

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

No when-to-use guidance and no alternatives named. The agent must infer from the endpoint template GET /plans/{planId}/stops/{stopId} that this is a single-item fetch versus the list/search siblings. No exclusions or prerequisites are given.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description does add a genuinely useful disclosure not in the annotations: the payload 'Contains personal data', which signals a privacy-sensitive read. No auth, rate-limit, or error behavior is described.

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

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

Three terse fragments that front-load the resource and scope. The trailing 'GET /unassignedStops/{id}' restates the tool name and endpoint without adding agent-relevant information, so it is mild 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 single-parameter read with no output schema, the description conveys what is fetched, that it is keyed by id, and that the result contains personal data, which is what an agent needs before calling. Return-field structure is unspecified, but with no output schema that 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?

Schema coverage is 100% and the single parameter already documents its accepted formats ('abc' or 'unassignedStops/abc'), so the schema carries the full burden. The description's 'by id' adds no meaning beyond that; baseline 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?

States a specific resource ('unassigned stop') and scope ('one ... by id'), which clearly separates it from the sibling spoke_list_unassigned_stops. It stops short of an explicit verb like 'retrieve', but the intent is unambiguous.

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

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

No when-to-use guidance and no reference to the alternative tools (spoke_list_unassigned_stops, spoke_get_stop). The agent must infer that this is the single-item lookup rather than the list endpoint.

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

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

Goes well beyond the annotations: discloses the rate limit (30 requests/minute), that recipient contact data is stored but nothing is sent at import time, that the response carries created ids and failures, and the underlying POST route. These are exactly the operational details an agent needs and that the hints alone do not 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?

Front-loaded with 'WRITE:' and packed into one dense paragraph where each clause (limit, geocoding benefit, rate cap, return value, storage behavior, endpoint) carries information. Slightly over-stuffed into a single block rather than cleanly separated, but nothing is wasted.

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

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

For a write tool with no output schema, it explains the return value (created ids and failures), the side effects (contact data stored, nothing sent), rate limits, and the required plan state. An agent has everything needed to invoke it correctly.

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

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

The description adds the 100-stop cap and characterizes the payload as stops with recipient contact data, but gives no per-field guidance. This is the baseline case: nested item schemas carry their own descriptions, while top-level coverage is 0%, so the description does minimal compensating work.

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 (add/import) and resource (stops), plus scope (up to 100 per request) and a precondition (writable, not-yet-distributed plan). The phrase 'better geocoding than one at a time' implicitly contrasts it with the sibling spoke_create_stop, so an agent can pick it apart from the single-stop tool.

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

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

Clearly signals when to prefer this over per-stop creation ('better geocoding than one at a time') and the plan-state condition ('writable (not yet distributed) plan'). It stops short of explicitly naming spoke_create_stop as the alternative or stating what to do when the plan is already distributed.

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 the read-only, non-destructive safety profile, and the description adds meaningful context beyond them: the subscription prerequisite producing HTTP 403, the endpoint path, and the semantic link between returned ids and the customProperties map on stops. It omits pagination/return-shape details, but with zero parameters that is a minor gap.

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

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

Three short sentences, front-loaded with the resource and its returned fields, then the key linkage, then the operational caveat. Every sentence carries distinct information; the endpoint path is the only mildly redundant element.

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

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

With no output schema, the description compensates by naming the returned fields (ids and names) and explaining the id semantics, plus the auth/subscription failure mode. It stops short of noting ordering or size limits for a list call, but is otherwise sufficient for a zero-parameter read.

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

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

The tool takes no parameters, so the baseline of 4 applies. The description correctly implies an unparameterized, team-wide listing and adds no parameter information, which is appropriate given there is nothing to document.

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

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

The description identifies a specific resource (the team's custom stop property definitions, with ids and names) and the underlying endpoint GET /team/customStopProperties. It goes beyond the title by explaining that the returned ids serve as keys in customProperties on stops. No sibling covers custom properties, so explicit differentiation is unnecessary.

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 rather than stated. The one genuine guideline is the subscription dependency ('Needs a subscription that includes custom properties (HTTP 403 otherwise)'), which tells the agent a failure condition but not when to prefer this tool over alternatives — and there are no direct alternatives among the siblings.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds meaningful extra context beyond that: the page cap ('up to 20 per page') and the returned field set. It still omits what happens at the end of pagination and whether any auth/scope is needed.

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

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

A single front-loaded sentence with the resource, returned fields, page limit, intended downstream use, and endpoint. Every clause carries information and nothing is padding.

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

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

There is no output schema, so the description carries the burden of describing results, and it does so by enumerating the returned fields plus pagination behavior. Complete enough to call correctly; a note on what an empty result or final page looks like would close the remaining 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%, so both page_token and max_page_size are fully documented in the schema, establishing a baseline of 3. The description's 'up to 20 per page' merely restates the schema's 1-20 maximum and adds no new syntax or format detail.

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

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

States a specific verb+resource ('List depots') and enumerates the fields returned (start/end addresses, working hours, vehicle type, max stops), so the agent knows exactly what it gets back. It is distinguishable from spoke_get_depot by the plural 'list' framing, but does not explicitly name that sibling.

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

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

'Use the ids when creating plans' tells the agent why the result matters and connects it to spoke_create_plan, which is genuine usage context. However, there is no explicit when-not guidance or comparison to the other list tools (drivers, operations, plans), so the routing decision is left mostly implicit.

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 the safety profile (readOnlyHint, openWorldHint, destructiveHint=false), so the description adds value by flagging 'Contains personal data' (a real PII caution) and naming the underlying endpoint 'GET /drivers' and the 50-per-page cap. It stops short of describing auth requirements or rate limits.

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

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

Three short fragments, front-loaded with the operation, then the PII warning and endpoint. Nothing is redundant and every clause carries information the agent would otherwise lack.

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

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

With no output schema, listing the returned fields is the right compensation, and the PII note plus pagination hint cover the main risks of this read. Missing are any statement of prerequisites/permissions and confirmation that the reply carries nextPageToken for paging, though the page_token schema implies it.

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 all three parameters (active, page_token, max_page_size) are already documented in the schema. The description only echoes the paging limit ('up to 50 per page') and field list, adding no syntax or format detail beyond the schema, so the baseline 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?

States a specific verb and resource ('List the team's drivers') and enumerates the fields returned plus the page cap, so the agent knows exactly what it gets. It does not explicitly differentiate itself from the singular sibling spoke_get_driver, but the list-vs-single distinction is clear enough from the wording.

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 name and the 'active' filter mention, i.e. use it to enumerate drivers with pagination. There is no explicit when-to-use guidance or pointer to alternatives such as spoke_get_driver for a single driver, so the agent must infer the routing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuine return context — it enumerates the fields surfaced (type, done flag, starter, optimized/skipped stops) and discloses the 'up to 20 per page' cap, which is meaningful behavior 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?

A single dense sentence front-loads the verb and resource, then packs the return fields and pagination limit with no wasted words, ending with the endpoint. Nothing is redundant.

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

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

With no output schema, the description usefully compensates by summarizing the returned fields, and both parameters are schema-documented. It is nearly complete for a read-only list tool; only the absence of tie-in guidance for get_operation keeps it short of a 5.

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 both page_token and max_page_size are fully documented in the schema. The description's 'up to 20 per page' merely restates what the schema's maximum already enforces, adding no syntax or format detail. 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?

States a specific verb and resource ('List long-running operations') and clarifies the domain by equating 'operations' with 'plan optimizations'. It clearly reads as a list tool, though it never distinguishes itself from the closely related sibling spoke_get_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?

Usage is only implied: the listed fields ('done flag', 'result') suggest polling to check optimization status, but there is no explicit when-to-use statement and no named alternative (e.g., get_operation for a single job). Adequate but with a clear routing gap.

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 safety is covered. The description adds behavior beyond that: result ordering (newest first), page size ceiling, and the important constraint that the page token must be passed 'with the same other arguments' for the next page, which is a real pagination-consistency rule not visible in 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 dense sentences plus the endpoint literal; the entity definition, ordering, paging, and filter examples are all front-loaded with no filler. Every clause carries operative information.

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

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

For a read-only list tool with no output schema and full schema description coverage, the description covers paging, ordering, and filtering adequately; mentioning nextPageToken implies the reply shape. Minor gap: it never says what a returned plan object contains, though that is partly excused by the entity definition and absent output schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes slightly beyond by showing how the free-form filter object is actually shaped in practice and by restating the same-arguments requirement for page_token. It does not, however, explain the semantics of the free-form nested filter fields beyond the two examples.

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

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

States a specific verb and resource ('List route plans'), then defines the domain entity ('a plan = one day's delivery job: date, depot, drivers, routes') and the ordering/paging scope. An agent can distinguish this from sibling list tools like spoke_list_plan_stops or spoke_list_depots without opening any 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?

Gives concrete usage context: newest-first ordering, pages of up to 20, and filter syntax examples ({"title":"Monday run"}, {"startsGte":"2026-10-01"}). It does not state when NOT to use this tool or point to alternatives such as spoke_get_plan for a single plan, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds value beyond that by disclosing the page cap of 10 and warning that the payload contains personal data (names, phones, e-mails, addresses), which is exactly the kind of context an agent needs for responsible pagination.

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

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

Two short sentences front-load the purpose and pagination, and the privacy warning is placed before the trailing endpoint. The bare 'GET /plans/{planId}/stops' line is mildly redundant but cheap and unambiguous.

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

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

With no output schema, the description usefully sketches the return payload (recipient names, phones, e-mails, addresses) and explains pagination, which is the main complexity here. The unmentioned recipient_external_id filter is a minor gap for a read-only list 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 75% and both optional params (page_token, max_page_size, recipient_external_id) are documented in the schema. The description's 'pages of up to 10' merely restates max_page_size and says nothing about the recipient_external_id filter, so it adds no meaning beyond structured data.

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

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

States a specific verb and resource ('List the stops of a plan'), and the plan-scoping naturally separates it from list_route_stops and list_unassigned_stops. It never names a sibling, so it stops short of an explicit 5, but an agent can still place it correctly.

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 one real usage directive ('page only as far as needed') for privacy reasons, which is genuine when-to-use context. However, it names no alternative tools and does not say when a caller should prefer route stops, unassigned stops, or search_stops instead.

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

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

Annotations already declare the safe read-only, open-world profile, so the bar is lower. The description adds real value beyond that by enumerating returned fields (stop count, driver, distributed/started/completed state) and the 20-per-page cap, which compensates for the absent output schema.

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

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

A single tightly-packed sentence that front-loads the action and resource, then adds definitional and pagination detail with no waste. The endpoint reference is a compact addition rather than 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?

With no output schema, the description usefully lists the fields returned and the page-size cap. It is largely complete for a paginated list tool, though it omits ordering/sort behavior and any filtering context beyond the date 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?

Schema description coverage is 100%, so page_token, max_page_size, and starts_on_or_after are already fully documented in the schema. The description's 'up to 20 per page' merely restates the schema's max_page_size maximum, adding no new parameter meaning; baseline 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?

States a specific verb ('List') and resource ('routes') and goes further by defining what a route is ('one driver's run of a plan: stop count, driver, distributed/started/completed state'). This definition lets an agent distinguish routes from plans and stops, which matters given the many list_* 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?

Usage is only implied by the resource name; there is no explicit when-to-use or when-not-to-use guidance. It never points to alternatives such as get_route for a single route or list_route_stops for the stops within a route, which is a notable gap in a dense sibling set.

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

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

Annotations already declare readOnly/openWorld/non-destructive, and the description adds behavior beyond that: results come back in driving order, page size is capped at 10, and the payload contains personal data that should be paged conservatively. The privacy caution is genuinely valuable context not available in 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?

Three short clauses, front-loaded with what the tool returns, followed by the privacy/paging constraint and the endpoint. No sentence is wasted.

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

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

For a read-only, paginated list tool with annotations covering safety, the description covers ordering, page limits, and the PII caution. With no output schema, it could have said more about what a stop record contains, but nothing critical for correct invocation is missing.

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

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

Schema coverage is 75% and the schema already documents page_token, max_page_size, and recipient_external_id; route_id has no schema description. The description only reinforces the route scope and the 10-item page cap, adding little syntax or format detail beyond what the schema 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?

States a specific verb (List) plus resource (stops) and constrains scope to a single route in driving order, which separates it from spoke_list_plan_stops and spoke_list_unassigned_stops. It does not name those siblings explicitly, so the differentiation is inferred rather than stated.

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?

"Page only as far as needed" gives a usage constraint tied to the personal-data warning, which is useful. However, there is no guidance on when to pick this tool over spoke_list_plan_stops or spoke_search_stops, so the alternative-selection guidance is only implied.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real context beyond that: the result 'Contains personal data' (a privacy/handling caveat) and the pagination contract 'pages of up to 20 (default 20)'. It does not describe auth requirements or return fields, but that is a minor gap given the annotation coverage.

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

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

A single front-loaded sentence that defines the resource first, then the caveat, then the paging contract. Tight and readable, with only minor duplication of the schema's page-size default.

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 exists, but the description covers the key facts an agent needs: what the list contains, that it is paginated with a bounded page size, and that results carry personal data. The only omissions are the return field shape and the alternative list/search tools.

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% — both page_token and max_page_size are fully documented in the schema, including the nextPageToken chaining instructions. The description's 'pages of up to 20 (default 20)' merely restates the schema's max_page_size bounds, adding no new semantic detail. 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?

States a specific verb (list) and resource (unassigned stops) and clarifies the concept with a gloss — 'stops that are not on any plan yet (the inbox of imported orders)'. This distinguishes it from the singular spoke_get_unassigned_stop and from spoke_list_plan_stops, though it never names those siblings explicitly.

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

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

The parenthetical 'the inbox of imported orders' implies the context in which this list is relevant, but there is no explicit when-to-use vs. when-not guidance and no routing to alternatives such as spoke_search_stops or spoke_list_plan_stops. Usage must be inferred.

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 flag destructiveHint=true and idempotentHint=false, but the description adds the crucial specifics annotations cannot: it rewrites existing routes if previously optimized (what gets destroyed), it consumes a rate-limited quota (30/min, 100/10min), and it does NOT notify drivers. This is exactly the behavioral context needed for a destructive, non-idempotent write.

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

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

Front-loaded with the 'WRITE:' marker, then a dense sequence of scope, side effects, quota, non-effects, return handling, and prerequisites. Every clause earns its place with no filler.

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

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

There is no output schema, and the description fills that gap by explaining the return (an operation handle) and the polling follow-up. Combined with prerequisites, rate limits, and destruction semantics, an agent has everything needed to invoke and sequence this 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?

With one parameter at 0% schema description coverage, the description must compensate. It only implicitly reveals the parameter through the endpoint 'POST /plans/{planId}:optimize', mapping plan_id to planId, but adds no format, source, or constraint detail beyond that.

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 — 'start the route optimization of a plan' — and clarifies the effect with the parenthetical 'orders and assigns its stops to its drivers'. It is unambiguous about what the tool does, but it never names or contrasts a sibling such as spoke_distribute_plan, so the 5-level sibling differentiation is absent.

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 concrete precondition ('needs at least one driver and one stop') and an explicit follow-up workflow ('Returns an operation: poll spoke_get_operation until done'), which is strong context for invocation. It stops short of stating when NOT to use it or which sibling to prefer for adjacent tasks (e.g. distribute_plan), so no explicit 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 and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond that: results contain personal data, the search index lags real time by a short while, and results are capped at 20 per page. It stops short of describing the response shape or ordering defaults.

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 and scope in the first clause, followed by the example filter, filterable fields, and two operational caveats. Dense but every sentence carries information; the filterable-field list is long but justified for a filter-driven tool.

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

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

For a read-only search with no output schema, the description covers scope, query construction, the personal-data caveat, index staleness lag, and pagination limits, with pagination token semantics carried by the schema. Return-value structure is unspecified but that is the only notable 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 coverage is 67%, so the schema documents most parameters, but the description adds value the schema does not: a concrete filter expression with a different field set (address.countryCode, deliveryInfo.attempted) and an enumerated list of filterable fields. That materially helps construct a valid filter beyond the schema's single example.

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 (Search) and resource (all stops of the team) and explicitly scopes it as planned, unassigned and past, which distinguishes it from siblings such as spoke_list_unassigned_stops, spoke_list_plan_stops and spoke_list_route_stops that cover only one bucket. An agent can tell this is the cross-scope keyword/filter search without opening any other 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?

It explains what can be searched and lists filterable fields, which implies when the tool is useful, but it never explicitly says when to choose this over the scoped list_* siblings or what conditions require it. Usage is inferable rather than stated.

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

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

Goes well beyond annotations: it discloses PATCH partial-update semantics, the destructive REPLACE behavior of driver_ids, the writability precondition, and — importantly for a destructiveHint=true tool — that nothing is sent to drivers, scoping the blast radius. It stops short of naming required permissions/roles or any side effects on dependent stops and routes.

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

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

Three short sentences, front-loaded with the WRITE marker and mutation scope, then the replace-semantics gotcha, then the failure condition. Zero 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 destructive, non-idempotent mutation with no output schema and sparse parameter documentation, the description covers the essentials: what changes, what gets replaced, when it fails, and the absence of driver notification. It omits what happens to existing stops/routes when depot_id changes and gives no auth/permission guidance.

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 only 20% schema description coverage, the description must carry the load, and it does map its prose fields (title, date, drivers, depot) onto title/starts_on/driver_ids/depot_id and clarifies driver_ids replaces the whole list. However, plan_id, date format expectations, and depot-change consequences are left entirely to the schema's bare type/pattern declarations.

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?

Opens with a specific verb+resource ("change a plan's ...") and enumerates exactly which fields are mutable, which cleanly separates it from spoke_create_plan, spoke_distribute_plan and spoke_get_plan. The PATCH endpoint reference removes any ambiguity about the operation type.

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

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

Gives a clear when-to-use context (editing an existing writable plan) and a when-not condition ("Fails if the plan is not writable (already distributed)"). It does not explicitly name spoke_distribute_plan or another sibling as the alternative path, so routing is implied rather than stated.

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