Stuart MCP by usefulapi

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description adds real value by disclosing the cancellation-fee cost and the user-confirmation requirement, plus the underlying POST endpoint. It stops short of saying what happens to the other dropoffs in the job or any delivery-state restrictions on cancellation.

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 front-loaded sentences plus an endpoint reference, with the scope stated first and the fee warning immediately after. The API path is marginally useful grounding but not strictly needed by an agent choosing the 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 destructive, fee-bearing mutation with no output schema, the definition covers cost and confirmation but omits failure modes (invalid delivery id, non-cancellable state) and the effect on the remaining deliveries. Annotations cover the safety profile, but operational edge cases are unaddressed.

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%, including an enum for public_reason_key, so the schema carries parameter meaning. The description mentions none of the three parameters and adds no guidance on when a reason key or comment should be supplied; 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 with explicit scope: 'Cancels a single delivery (one dropoff) of a multi-drop job,' which implicitly separates it from stuart_cancel_job. It never names the sibling or the whole-job alternative, so the differentiation is inferable 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 a clear procedural precondition: 'A cancellation fee may apply; confirm with the user first,' which tells the agent to check before invoking. It offers no explicit when-not conditions (e.g., after pickup, delivery already completed) or named 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 destructiveHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds genuinely new behavior: a possible cancellation fee triggered once a courier is already en route, plus the under-the-hood POST /v2/jobs/{jobId}/cancel semantics. It doesn't say what happens to in-flight delivery state or what errors come back, keeping it below 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?

Three short sentences, each carrying a distinct payload: scope, cost/confirmation risk, reason-key purpose. The destructive scope lands first, before the caveats, so nothing important is 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, no-output-schema mutation this covers the essentials an agent needs: what is destroyed (the job and all deliveries), the financial risk, the confirmation gate, and parameter intent. What's missing is failure/reversibility detail — e.g. whether an already-started job can be refused — which matters given destructiveHint.

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 enum already enumerates the reason keys, so the baseline is 3. The description adds the *why* for public_reason_key ("for reporting"), which is intent that the schema does not convey, nudging it above baseline; job_id and comment receive no extra explanation.

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?

"Cancels a whole job and all its deliveries" gives a specific verb plus resource and states the blast radius, which implicitly separates it from the sibling stuart_cancel_delivery that targets a single delivery. An agent can pick between the two 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?

It states a concrete precondition — confirm with the user first because a fee may apply once a courier is on the way — which is real usage guidance. It stops short of naming stuart_cancel_delivery as the lighter-weight alternative for a single delivery, so the when-to-use-this-vs-sibling routing is left 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 only say openWorldHint=true and destructiveHint=false; the description adds the material behaviors an agent needs — the booking is real and charged, the courier search starts right away, and pickup_at is capped at 4 days (30 for corporate). It also flags the safe test path via sandbox, which is exactly the kind of operational consequence annotations don't 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?

One tight paragraph, front-loaded with the highest-stakes fact (real, charged delivery), then prerequisites and constraints in descending order of importance. No filler sentences.

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 multi-param nested write tool with no output schema, it covers cost, dispatch timing, scheduling limits, prerequisites and test mode. It doesn't say what comes back (job id, status) or how to undo a bad booking via stuart_cancel_job, which an agent would want given there is no 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 still adds value by tying pickup_at to a concrete scheduling window and by restating the 1-8 dropoff bound as a business constraint rather than just a maxItems. It doesn't explain assignment_code or the dropoff window fields, so it isn't 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?

Opens with a specific verb+resource (creates a job) and immediately scopes it: one pickup, 1-8 dropoffs, real charge, dispatches a courier. That is clearly separable from stuart_validate_job, stuart_estimate_price and stuart_update_job 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 an explicit ordering of prerequisites (quote via stuart_estimate_price, check via stuart_validate_job, confirm with the user), names the sandbox for tests, and explains when the job dispatches immediately versus when pickup_at defers it. Both the when-to-use and the when-to-check-first conditions are present.

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 and openWorldHint, so the safety profile is covered. The description adds a useful no-booking confirmation and the coordinate/address caveat, but says nothing about auth, rate limits, or return behavior.

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

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

Front-loads the key estimate and no-booking facts in one compact sentence. The trailing Stuart endpoint is minor implementation detail, but the overall definition remains tight.

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 estimate with a rich input schema, it conveys the return unit (seconds) and non-booking behavior. However, with up to eight dropoffs and no output schema, it does not clarify whether the ETA is per-dropoff, for the final dropoff, or aggregate.

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 nested schemas document pickup, dropoffs, contact details, coordinates, and package type. The description's coordinate note mostly restates what the schema already says rather than adding new semantics.

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

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

Names a specific verb (estimate) and resource (dropoff ETA to the destination address), and the destination/dropoff wording separates it from pickup ETA in the sibling set. It stops short of explicitly naming an alternative, so it is not quite top-tier.

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?

Says nothing is booked, which implies this is a non-committal estimate rather than create_job. But it does not state when to choose it over stuart_estimate_pickup_eta or stuart_estimate_price.

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

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

Annotations already declare readOnlyHint=true, but the description adds meaningful context: 'Nothing is booked' pre-empts confusion over the POST endpoint, and 'Stuart: POST /v2/jobs/eta' discloses the underlying call. It doesn't cover error/rate-limit behavior, but the key mutation-vs-read ambiguity is resolved.

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 and the endpoint reference, with the return value front-loaded. 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 nested, 3-parameter tool with no output schema, the description states the return unit (seconds) and clarifies the no-booking behavior. Adequate, though it could note the dropoff ETA sibling distinction more explicitly.

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, and the description earns extra credit by telling the agent the body mirrors create ('same job body as create'), which meaningfully guides parameter construction beyond the schema itself.

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

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

States a specific verb and resource ('Estimated seconds until a courier could arrive at the pickup address') and implicitly distinguishes itself from the sibling stuart_estimate_dropoff_eta by anchoring to the pickup. The 'same job body as create' clause ties it to a known sibling's shape.

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?

'Nothing is booked' clearly signals this is a non-committal quote, and 'same job body as create' tells the agent what to supply. It stops short of explicitly contrasting with stuart_estimate_price or stuart_estimate_dropoff_eta, but the conditions for use are clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true; the description reinforces this with 'Nothing is booked', resolving the natural worry about POST /v2/jobs/pricing looking like a write. It omits quote validity/expiry behavior and any rate-limit context, which is the remaining gap for a pricing call.

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

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

Front-loads the payoff (what the price returns) in the first clause, then the side-effect guarantee, then the inputs, then the upstream endpoint. Four short clauses, no filler, nothing that could be cut.

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 100% schema coverage and no output schema, the description does the one thing needed—it summarizes the shape of the response (tax-exclusive and tax-inclusive amounts plus currency). It does not cover multi-dropoff pricing behavior or quote expiry, which an agent pricing a job might care about.

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 nested pickup/dropoffs structure, contact rules, coordinates and E.164 phone format are all already documented. The description only restates the required trio (pickup address, dropoff address, package type) and actually understates it—schema requires a single pickup plus 1–8 dropoffs with richer contact obligations—so it adds little 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+resource (price of a job) and enumerates the returned values (amount excl./incl. tax, currency), which separates it from stuart_create_job and stuart_validate_job without opening any schema. The 'before you create it' framing makes the lifecycle position 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?

Gives clear context—call it before creating the job—and explicitly states 'Nothing is booked', which is the key decision input for a pre-flight quote. It stops short of naming the sibling to call next (stuart_create_job) or of distinguishing it from stuart_validate_address, so not a full when/when-not/alternatives treatment.

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

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

The description adds useful context beyond the annotations: the number is anonymized, requires an assigned courier, and expires at delivery end. With readOnlyHint and openWorldHint already present, this gives solid behavioral guidance, though it omits auth/rate-limit details.

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

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

The description is front-loaded with the return value, followed by lifecycle constraints and the underlying Stuart endpoint. It is appropriately sized with no wasted sentences.

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

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

For a simple read-only lookup with fully described schema parameters, no output schema, and annotations covering safety, the description provides everything an agent needs: what it returns, when it works, and when it expires.

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 delivery_id parameter is already fully documented in the schema. The description reinforces the delivery context but does not add syntax or format details 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?

The description states a specific resource—the courier's anonymized phone number—and ties it to a delivery. It is clear what is returned, though it does not explicitly differentiate itself from siblings, which are mostly job/delivery management tools.

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

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

It clearly states the operating condition: only works once a courier is assigned and expires when the delivery ends. It does not name alternatives, but there is no obvious sibling alternative for this specific lookup.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real value by enumerating what the response contains (status, tracking URL, addresses, contacts, ETA, cancellation, POD, driver, distance, pricing), which substitutes for the absent output schema. It does not cover error cases such as an unknown job 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?

A single dense sentence that front-loads the return payload, followed by the underlying endpoint for traceability. No filler and nothing 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?

For a read-only getter with one parameter and no output schema, the description covers the return shape and scoping well enough to call correctly. The only gap is what happens on a missing or invalid job id.

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

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

Only one parameter and schema description coverage is 100%, so the schema fully documents job_id. The description adds nothing about the id format or accepted integer-vs-string variants beyond what the schema already states; 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 (get) and resource (a single job) and the phrase 'One job in full' implicitly contrasts with the list operation. It is easy to distinguish from stuart_list_jobs or stuart_create_job, 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?

Usage is only implied: fetch a job by id when you need its details. There is no explicit statement of when to prefer this over stuart_list_jobs, stuart_validate_job, or the cancel/update siblings, and no prerequisites such as a known job id or auth context.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower. The description nonetheless adds two useful behavioral facts: the response is GeoJSON, and the zone must be open — a precondition that hints at a failure mode. It still says nothing about what happens if the zone is closed or about error shape.

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

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

Two short sentences with the return format and subject front-loaded. The trailing 'Stuart: GET /v2/areas/{zone}' reference is mildly redundant but cheap and occasionally useful for tracing.

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 two-parameter lookup with full schema coverage and no output schema, stating the GeoJSON return type and the open-zone requirement covers what an agent needs. The only real gap is behavior on a closed or unknown zone.

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

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

Schema coverage is 100% with both parameters described, and one carries an enum, so the schema does the heavy lifting. The description only reinforces the zone-name convention and the picking/delivering split already present in the schema, adding 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?

The description names a specific resource (a zone's picking or delivering coverage area) and the exact return type (GeoJSON), with concrete zone examples. It is clearly distinguishable from the nearest sibling, stuart_get_zone_schedule_slots, though it never states that contrast 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 phrase 'open Stuart zone' implies a precondition (the zone must be open) but does not spell out when to choose this over the schedule-slots or ETA tools. No explicit exclusions or alternatives 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 and openWorldHint=true, so safety is covered; the description adds genuinely new behavior — 15-minute slot granularity, results truncated to the current moment, and the future-date requirement. Timezone handling and failure behavior for past/invalid dates remain unstated.

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

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

Two compact sentences with the return shape front-loaded and constraints immediately after. The trailing API route reference (GET /v2/jobs/schedules/...) is mild noise for an agent but still maps the tool to the underlying endpoint.

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 does the work of explaining what comes back (start/end pairs at 15-minute steps), which is what an agent needs. It is nearly complete for a simple read tool; timezone semantics for the returned slots is the main omission.

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

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

Schema coverage is 100%, so baseline is 3, but the description contributes extra meaning for `date` beyond the schema's 'YYYY-MM-DD' pattern: the date must be in the future and results are clipped to now. The `type` and `zone` parameters are left to the schema's 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 — available scheduling slots in a zone for a date — plus the granularity (15-minute steps) and the response fields (start and end). No sibling tool covers schedule slots, so an agent can select it unambiguously.

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 only usage guidance is the constraint 'Use a future date' and the note that slots run from the time of the request onward. There is no explicit when-to-use versus when-not framing or reference to any alternative, though the sibling list contains no direct competitor.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds real behavioral facts — the 90-day lookback cap, newest-pickup-first ordering, and the full-page-means-more-pages inference rule. It doesn't state rate limits or whether a total count is returned, but the read-only safety profile is already covered by annotations.

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

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

Three tight sentences, front-loaded with scope and ordering, then filters, then pagination. The trailing 'Stuart: GET /v2/jobs' endpoint mapping adds little for an agent that never constructs URLs, but everything else 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?

With five optional params, no output schema, and read-only annotations, the description covers the remaining gaps itself: timeframe, sort order, return contents (tracking URLs, courier proof, driver, pricing) and how to page through results. Nothing needed to call it correctly 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 the baseline is 3. The description goes beyond it by explaining the pagination contract between page and per_page, which the schema only lists as integers, and by framing active/status/client_reference as the intended filtering axes.

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 delivery jobs') plus the exact scope (last 90 days, newest pickup first) and what each row carries. The list-vs-single distinction is clear against stuart_get_job, and no agent could confuse it with stuart_create_job or stuart_cancel_job.

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 selection guidance: filter by status, active, or client_reference, and the pagination rule ('when a page returns per_page rows, ask for the next page'). It never explicitly says when to prefer stuart_get_job for a single job, so it stops short of full alternative 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 idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the underlying HTTP endpoints and the 'only when really ready' correctness caveat, but says nothing about what happens on a repeated or invalid call, or what the response confirms.

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 ordered well: action, selection constraint, precondition. The trailing HTTP endpoint listing is marginal for an agent caller but does not bloat the description meaningfully.

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, idempotent, non-destructive signal tool with no output schema and full schema coverage, the description supplies the decision rule and precondition an agent needs. Failure modes and confirmation behavior are the only notable omissions.

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 each parameter's meaning is already documented. The description's real contribution is the mutual-exclusivity rule ('exactly one of'), which the schema does not encode (no required fields, no oneOf), but it adds nothing about order_ready_at semantics 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 action (mark an order ready for courier collection) and precisely scopes it to the Stuart job/delivery domain. The second sentence distinguishes the two granularities (whole job vs. single delivery), which lets an agent pick the right variant without consulting 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?

Explicitly says to pass exactly one of job_id or delivery_id and warns to send it only when the order is genuinely ready. It does not name a sibling or an exclusion (e.g., versus stuart_cancel_delivery or re-sending after a prior call), so the alternative-routing guidance is implicit rather than complete.

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, idempotentHint and openWorldHint, and the description adds genuinely new behavioral context: the status-gated editability rule. It still doesn't say whether omitted fields are preserved (PATCH semantics), what errors a rejected edit returns, or whether the mutation re-prices or re-validates the job.

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

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

Two compact sentences plus the endpoint tag; the status constraint is placed immediately after the field list where it is most useful. Nothing is repeated from the schema or annotations, and no sentence is 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 nested-object mutation with no output schema and thin schema coverage, the description supplies the essential editability model. It leaves open how partial updates behave for unspecified fields and what a successful response contains, which matters given the nested pickup/dropoff contact objects.

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 only 33%, so the description must compensate, and it does: it names client_reference, package_description, and the pickup/dropoff comment and contact as the editable set, effectively documenting the low-coverage optional parameters. It adds no format or length semantics beyond what the schema already encodes for those fields.

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

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

States a specific verb ('Change allowed details') plus the exact resource (a delivery inside a job) and enumerates the editable fields, which cleanly separates it from stuart_get_job, stuart_create_job and stuart_cancel_delivery. The PATCH endpoint reference pins down the operation further.

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 concrete usage condition: what is editable depends on delivery status, and after delivery only client_reference can be changed. It does not name an alternative tool or state what to do when a field is not editable, so it falls short of explicit when/when-not/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 openWorldHint=true, so the safe-read nature is known. The description adds useful behavioral context by explaining that validation checks both geocoding and zone membership, and that a phone number is needed when the address is approximate.

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 core validation check and the pickup/dropoff distinction. The trailing API endpoint reference is minor but not wasteful, and no sentence is bloated.

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

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

For a read-only validation tool with full parameter documentation and no output schema, the description covers what is being validated and the key phone condition. It does not explain the return shape or failure behavior, which leaves a small gap given there is no output schema.

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

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

Schema description coverage is 100%, so all parameters are already documented, including the type enum, phone requirement, and coordinates object. The description restates the pickup/dropoff distinction and phone condition but does not add meaningful syntax or format guidance beyond the schema.

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

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

The description states a specific verb ('Check') and resource ('address'), and clarifies that validation covers both geocoding and Stuart zone inclusion for pickup or dropoff. It is clear what the tool does, but it does not explicitly differentiate itself from the related zone-coverage sibling tool.

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

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

It implies usage before job creation by framing validation around pickup and dropoff addresses, and notes the phone requirement for approximate addresses. However, it gives no explicit guidance on when to use this versus stuart_get_zone_coverage or other siblings, and no when-not-to-use cases.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds useful behavioral context beyond that: it confirms no job is created, specifies what is validated, and states the return shape as {valid}. It does not cover auth or rate limits, but the safety profile is already provided by annotations.

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

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

The description is two compact sentences with no filler. The purpose and no-side-effect guarantee are front-loaded, and the return shape and endpoint are included without unnecessary elaboration.

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 validation tool with a rich input schema and annotations covering the safety profile, the description is complete enough: it explains what is validated, that no job is created, and what is returned. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the input schema already documents all parameters in detail. The description adds no parameter-specific meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description gives a specific verb and resource: it checks whether a job would be accepted without creating it. The phrase 'without creating it' cleanly distinguishes it from stuart_create_job, so an agent can identify the tool's role without opening its 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 clearly implies the use case: pre-validating a job before creation, including the checks performed (geocoding/covered zone and field validity). It does not explicitly name alternative tools like stuart_validate_address or stuart_estimate_price, but the context is clear.

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