Upper Route Planner MCP by usefulapi

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

Beyond the annotations, the description discloses that existing drivers are replaced, that every id must be an active team driver, and that an optimized route is reset to needs_optimization: true – a significant state side effect an agent must know about.

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 tight sentences, front-loaded with the write semantics and pruning constraint, then the validation rule, then the side effect and endpoint. No filler.

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

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

For a two-parameter mutation with no output schema, the description covers the key prerequisites, destructive replacement behavior, and the required re-optimization step. Nothing material is missing 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%, so the baseline is 3; the description still adds value by specifying that driver_ids come from upper_list_drivers and must be active drivers on the team, which the schema does not express.

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 ("assign one or more drivers to a route") and immediately clarifies the replacement semantics, which distinguishes it from additive siblings like upper_share_route_to_drivers. An agent can tell what this does 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?

It names the source for driver ids (upper_list_drivers) and the required follow-up (run upper_optimize_route again after assignment resets optimization). It does not explicitly contrast with upper_share_route_to_drivers, so the guidance is clear but not complete on 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 cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds real context beyond them: omitted settings inherit account defaults, the call returns a route_id, and the underlying endpoint is POST /ext-create-route. The non-idempotency warning reinforces rather than contradicts the annotation, and nothing here conflicts with destructiveHint=false.

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 paragraph with the WRITE marker front-loaded, the field inventory next, then defaults, return value, sibling handoff, and endpoint. Every clause carries distinct information and none repeats the schema verbatim.

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?

Although there is no output schema, the description states the return value (route_id), explains defaulting behavior for the six all-optional parameters, and points to the sibling needed to make the route useful. Nothing an agent needs before calling 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 100%, so baseline would be 3, but the description adds meaning the schema cannot: any omitted setting falls back to the account's defaults, which explains why all six parameters are optional. The parenthetical field list also gives a quick orientation across the six settings.

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 an explicit verb+resource ('WRITE: create a new, empty route') and enumerates the configurable settings in parentheses. It also contrasts itself with siblings by directing follow-up work to upper_create_stop, so the agent can distinguish it from upper_update_route without opening either 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?

Clear about the creation context and explicitly names the alternative path for adding stops ('add stops with upper_create_stop'), plus warns that calling it twice creates two routes. It does not spell out when to reach for upper_update_route instead, but the create/update split is self-evident from the name.

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

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

Beyond the annotations (readOnly=false, idempotent=false) it discloses real side effects: geocoding of the address, rejection if the target route is active, a re-optimization flag being set on optimized routes, and that duplicate calls create two distinct stops. The route-precondition and re-optimization consequences are not derivable from any structured field.

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 compact sentences, write-intent front-loaded, followed by the geocoding fact, the route_id branch, and the duplicate-call caveat. No filler; the endpoint path is the only arguably extraneous 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?

Given 22 optional parameters, a 100% documented schema, and no output schema, the description covers the crucial creation semantics and route preconditions. It does not say what the response contains (e.g., the new stop's id), which an agent would need for follow-up calls, but that is a small 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%, so the schema already documents all 22 parameters, including that address is geocoded and that route_id may be omitted. The description mostly restates this; the added value (route must not be active) is behavioral rather than 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?

Opens with 'WRITE: create a stop', a specific verb+resource that separates it from read siblings like upper_list_stops and from the mutating counterpart upper_update_stop. It is clear what is produced, though it never names the alternative (update_stop) explicitly.

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

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

Gives concrete conditional guidance: pass route_id to schedule, omit it for an unscheduled stop, and the route must not be active/in progress. It does not contrast with upper_update_stop or upper_create_route, so an agent must infer when to create versus update, but the route_id branch is well specified.

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 the fixed five-slot return shape and endpoint, but does not discuss auth, pagination, rate limits, or other behavioral details; with annotations, this is adequate but not rich.

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 one sentence plus the endpoint, front-loaded with the resource. Every element conveys scope or returned fields, and there is no redundant 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?

For a zero-parameter read-only getter, the description gives enough return shape (five slots with label, unit, enabled) to use it without an output schema. It could be slightly more explicit about the response container, but it is largely complete.

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

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

There are zero parameters, so the schema has nothing for the description to compensate for. The baseline of 4 applies because no parameter semantics are needed.

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

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

The description names the specific resource (the workspace's five capacity-field slots capacity1-capacity5) and the fields returned, and the GET endpoint makes the operation clear. It does not explicitly contrast with upper_get_custom_fields, but the resource distinction is largely inherent in 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?

No when-to-use or when-not-to-use guidance is provided. The phrase 'used for load planning' explains what the fields are for, not when an agent should call this tool versus upper_get_custom_fields or other 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 establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds useful behavioral context: the Upper plan feature dependency and the underlying GET endpoint, while also clarifying the shape of the returned custom-field slots.

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 tight sentences that front-load the resource and then add the plan prerequisite and endpoint. Every part contributes useful information without repetition.

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 zero-parameter read tool with no output schema, the description sufficiently explains what is returned: five custom-field slots with type, label, enabled, and required attributes, plus their enabled status. It also notes the plan-level prerequisite.

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?

This tool has zero parameters, so the baseline is 4. The description does not need to explain parameter meaning, and the empty schema is fully consistent with a workspace-level getter.

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 specifically identifies the resource as the workspace's five stop custom-field slots (custom1-custom5) and names the attributes returned. This clearly distinguishes it from sibling tools like upper_get_capacity_fields and upper_get_optimization_status.

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 description, and the description adds the important prerequisite that the Custom fields feature must be enabled in the Upper plan. However, it does not explicitly state when to call this instead of related getter tools or what workflow it supports.

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 non-obvious context by naming the three possible status outcomes and the queue_id field of the last job. It also discloses the underlying endpoint (GET /ext-optimization-status). Auth requirements and rate limits are not mentioned, which keeps it from 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 short sentences with no filler; the outcome enumeration comes first and the operational instruction (poll after optimize) follows. Nothing is repeated from the schema or annotations.

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 return-value disclosure and does so by listing status values and queue_id, which is the key information for a polling tool. It does not indicate what happens for an invalid or never-optimized route, nor any recommended polling interval, leaving a small gap for an async-status 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?

There is a single parameter, route_id, and schema description coverage is 100%, so the schema already fully documents it. The description adds nothing about route_id semantics (e.g. where to obtain it), 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 ('check whether a route is optimized') and enumerates the exact status values returned plus queue_id, so the agent knows the response shape from the description alone. It is clearly distinguishable from the sibling upper_optimize_route, which starts the job rather than reporting on 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?

'Poll this after upper_optimize_route' gives an explicit sequencing rule tied to the relevant sibling tool, which is exactly the guidance needed for an async job. It stops short of stating when-not to use it (e.g. before any optimization job exists) or a polling cadence, so it falls just below the top tier.

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 useful context by disclosing that only *active* drivers are returned and that results are scoped to the team owning the API token. It does not discuss result size or ordering, but with zero parameters there is little else at stake.

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, front-loaded sentences: what is returned, how to use the ids, and the underlying endpoint. Every sentence earns its place and nothing is repeated from the schema or annotations.

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 parameters and no output schema, the description carries the return-value burden itself and does so by naming the four fields and the 'active' filter. An agent has everything needed to decide whether to call it and how to use 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?

The input schema has no parameters, which is the baseline-4 case. The description correctly adds no parameter guidance, since there are none to explain, and instead uses the space to describe outputs.

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 active drivers) plus the scoping qualifier 'on the Upper team that owns the API token,' and enumerates the returned fields (id, name, email, phone). It also names the sibling tools the ids feed into, so it is clearly distinguishable from upper_assign_drivers and upper_share_route_to_drivers.

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 tells the agent where the results go next — 'Use the ids with upper_assign_drivers and upper_share_route_to_drivers' — which implies a discovery-then-act workflow. It does not state any when-not condition, but there is no competing list-drivers tool among the siblings, so no exclusion 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 annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. Beyond that, the description adds important behavior: Upper itself has no paging, this tool pages locally, limit defaults to 100 and maxes at 500, and replies indicate truncation via next_offset.

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 well front-loaded: returned fields come first, then filter modes, then pagination behavior, then endpoint. Every sentence carries operational information, with no redundant restatement of the name.

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

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

With no output schema, the description still tells the agent what fields are returned and how to detect more results via truncated/next_offset. It also covers all five parameters and the main filtering modes, making the definition complete enough 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 description coverage is already 100%, so the baseline is 3. The description adds value by clarifying parameter interactions that matter when constructing calls: scheduled is only meaningful with route_id, unscheduled is used without route_id, and offset should follow next_offset from the prior reply.

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 ('List the team's stops') and enumerates the returned fields, including optimized order and route/custom ids. It is clearly distinguishable from sibling tools such as upper_create_stop, upper_update_stop, and upper_optimize_route.

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 explicitly explains the three filtering modes: route_id for one route, scheduled true/false only with route_id, and unscheduled=true without route_id. It also states that with no filter all active stops are returned, leaving little ambiguity about how to call the tool.

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 non-idempotent, and the description adds real context beyond them: async execution, the returned status/queue_id, and the dedupe behavior for in-flight jobs. It stops short of saying what the reordering actually changes on the route or whether it can be undone, which is the main thing an agent weighing a destructive write would want.

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

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

Four short sentences, front-loaded with the WRITE marker and the core action, then prerequisites, then async contract. No filler and nothing buried.

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 async mutation with no output schema, the description supplies the missing pieces: prerequisites, that the call returns immediately with pending/queue_id, how to poll, and the duplicate-job behavior. An agent can invoke and follow up correctly from this alone.

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 route_id and timezone are already documented in the schema. The description adds no parameter-level detail, not even a note about when timezone matters, 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?

Opens with a specific verb and resource ("start optimizing a route's stop order") and prefixes WRITE to flag the mutation class. The async/polling follow-up immediately separates it from upper_get_optimization_status and upper_assign_drivers.

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?

States the explicit preconditions (at least one stop and one assigned driver, pointing to upper_assign_drivers) and the next step (poll upper_get_optimization_status). It also covers the edge case where a job is already running, so an agent knows the expected response instead of double-submitting.

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

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

Adds real context beyond annotations: it discloses the notification side effect, warns that 'sending twice notifies twice' (reinforcing non-idempotency the annotations only hint at), and states a validation rule ('every id must be an active driver on the team'). This is exactly the behavioral disclosure a write tool 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?

Every sentence carries unique information – operation class, side effect, default, validation, idempotency warning, confirmation gate – with no repetition or filler. Front-loaded with the most decision-relevant facts.

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 what an agent needs to call it safely: side effects, defaults, validation, and a confirmation requirement. Return values are not described, though with no output schema this is a minor omission for a simple action endpoint.

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 more by explaining driver_ids' default behavior and its constraint that ids must be active drivers. The timezone parameter is left to the schema alone, so it is not a full 5.

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 ('push a route to the drivers' mobile app') with the immediate side effect (notification per driver), which clearly separates it from upper_assign_drivers or upper_create_route. The 'WRITE:' prefix front-loads the operation class.

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 clear context for use (push to drivers' app now), a default path (no driver_ids → route's assigned drivers), and an explicit gate ('Confirm with the user before calling'). It does not name a sibling alternative such as upper_assign_drivers and when to prefer it, so it falls short of a 5.

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

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

Annotations already cover the safety profile (destructive, idempotent, open-world, non-read-only), and 'WRITE:' is consistent with that. The description adds one genuinely useful behavioral fact — 'Only the fields you pass change' (partial update semantics) — but says nothing about what a settings change does to an existing optimization, nor about required auth or failure modes.

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 operation class and resource, then the field list, then the partial-update rule — three short clauses, no padding. The trailing 'POST /ext-update-route' is endpoint trivia that an agent invoking the MCP tool doesn't need.

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 annotations carrying the destructive/idempotent profile and a fully documented schema, the description supplies the one missing behavioral fact (partial update). The only residual gap is not saying whether changing settings invalidates an already-optimized route.

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 every parameter is already documented including enums and formats. The description's parenthetical field list adds mild value by grouping the mutable fields and using friendly labels (name, date) that map to route_name/route_date, but nothing 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?

States a specific verb and resource ('change settings of an existing route') and enumerates the mutable fields, making it clearly separable from upper_create_route and upper_update_stop. The 'WRITE:' prefix signals the operation class against read siblings, 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?

'change settings of an existing route' implies the precondition that a route must already exist, which is the main usage constraint. There is no explicit guidance on when to use this versus upper_optimize_route or upper_create_route, and no stated 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?

Goes well beyond the annotations: partial-update semantics, silent re-geocoding that ignores accompanying city/state/zipcode, the side effect of route_id moving the stop, re-optimization flagging, the hard block on active routes, and the underlying POST endpoint. These are exactly the hidden behaviors an agent needs for a destructive mutation.

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 then a dense sequence of clauses, each carrying distinct operational information with no filler. Every sentence earns its place for a 23-parameter mutation 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?

Covers eligibility, partial-update behavior, geocoding precedence, and side effects for a complex nested-object schema. The one remaining gap is the response: there is no output schema, and the description never says what a successful update returns (e.g., the updated stop object) or how failures on active routes surface.

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 adds cross-parameter precedence rules (address wins over city/state/zipcode and those are ignored) and the side effect of route_id, which the schema alone states only tersely. It does not add meaning for the remaining ~20 fields, but those are self-documented.

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 ('WRITE: change an existing stop') plus the key semantic 'only the fields you pass change', which immediately separates it from upper_create_stop and upper_update_route. An agent can identify the operation and its patch semantics 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?

Gives concrete preconditions and exclusions: 'stops on an active route cannot be edited' and the re-optimization consequence when editing on an optimized route. It also encodes when address vs city/state/zipcode apply. It stops short of naming sibling alternatives (e.g., create_stop for new stops), so it is clear context rather than full when/when-not routing.

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