ValveRide Flow

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds real behavioral context: the result shape '{ data: StationPrice[] }', that stations without a price are dropped from results, default and maximum values for radius and limit, and the auth requirement of partner keys with partner_tenant_ref on every call. This is information an agent cannot get from the annotations or 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?

Four dense sentences, front-loaded with the identity and data source, then return shape, then defaults/limits, then the auth constraint. Nothing is padded and the most actionable constraint (partner keys) sits at the end where it is easy to catch.

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 correctly supplies the return wrapper and the key filtering behavior (unpriced stations omitted), plus limits and auth. It does not describe what fields a StationPrice contains, which is the remaining gap for a consumer of the response.

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

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

Schema coverage is 100%, so baseline is 3; the description goes beyond it by supplying the defaults the schema omits (radius default 10, limit default 50) and the units of radius (miles). The partner_tenant_ref requirement is also reinforced, though include_estimated is not touched on.

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 (posted retail diesel prices at truck stops), the geographic scope (near a point), the ordering (nearest first), and the data source. An agent can immediately distinguish this from diesel_price_station (single station), fuel_market_snapshot (market-level), and optimize_fuel_plan (planning).

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 'near a point' plus the radius defaults, and the partner-key prerequisite ('send partner_tenant_ref with every call') is a genuine usage constraint. However, it never states when to prefer this over a sibling like diesel_price_station, nor any exclusion such as coverage limits.

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 (readOnly, idempotent, non-destructive, closed-world), so the description adds the useful extras: the null-result case when no price exists, the meaning of is_estimated, and the partner-key auth requirement. It does not describe rate limits or the shape of StationPrice, which matters since there is no 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?

Four short sentences, front-loaded with the resource and scope, then return shape, then the estimation caveat and auth note. Dense and mostly waste-free, though the auth sentence could be compressed.

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 correctly fills in the return envelope ({ data: StationPrice } or { data: null }) and the estimation semantics, plus the auth requirement. The internal fields of StationPrice remain undefined, which is the main residual gap for a 3-parameter lookup tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description earns a bump by explaining that an is_estimated price is 'modeled from nearby observations' and by restating the pf_+16-hex id contract tied to diesel_prices_near. It adds interpretive meaning rather than merely repeating field descriptions.

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

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

States a specific verb and resource — posted retail diesel price for one truck stop — and scopes it to a single station identified by public id. The singular 'one truck stop' plus the id format implicitly separates it from the plural sibling diesel_prices_near.

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 routes the agent by naming diesel_prices_near as the source of station ids, implying a discovery-then-lookup chain. It also states the precondition 'Partner keys only; send partner_tenant_ref with every call.' It stops short of explicitly saying when to prefer this over fuel_market_snapshot or optimize_fuel_plan.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the description only needs to add context — and it does: cached data refreshed every 12 hours (implying possible staleness) and zero cost. It does not discuss any rate limits or failure modes, but for a free read-only snapshot those gaps are minor.

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

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

Three sentences, front-loaded with what it returns, then routing, then cost. Slightly dense but every clause carries information; 'free and carries no charge' is mildly redundant with the title.

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

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

With no output schema, the description compensates by naming the exact return fields (national median/p10/p90, per-state percentiles, savings context), the caching cadence, and sibling alternatives. An agent has everything needed to call it and interpret results.

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

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

Schema coverage is 100% and the schema already documents both optional params as state-selection hints. The description restates that origin/destination only drive which per-state percentiles are returned, which reinforces but does not materially extend the schema. 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 (cached US diesel market snapshot) plus the data source and refresh cadence, and enumerates the returned aggregates (national median/p10/p90, per-state percentiles). It is immediately distinguishable from optimize_fuel_plan and the Diesel Prices 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?

Explicitly says when to use it (market questions or cost estimates) and names two alternatives with the conditions that select them: optimize_fuel_plan for stop-by-stop plans and Flow Diesel Prices for posted truck-stop prices. Nothing is left 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 by disclosing that calls are metered ($2.25 new plan, $0.08 replan from trial credit; 10 replans = 1 plan on monthly tiers) and that the tool fails with the structured error no_feasible_plan_under_vendor_rule rather than returning an off-brand stop. It also names the echoed response fields (tripId, vendorRule, appliedDiscounts) so the agent knows what to verify. Nothing contradicts readOnlyHint=false (a paid, server-side trip is created) or idempotentHint=false (each call re-plans).

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 return values, then the replan mechanics, then the vendor rule — a sensible ordering with no wasted opening. The one non-earning passage is the tier price list ('Starter $99/month for 200 plans, Growth $349/month...'), which is marketing detail an agent cannot act on mid-call.

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 10-parameter, nested-object tool with no output schema, the description still covers the return payload, error paths, cost model, and the two coupled-parameter traps (vendorRule + discountSchedule, tripId + currentLocation). Nothing an agent needs to call this 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?

With 90% schema coverage the baseline is 3, and the description adds real cross-parameter semantics: the vendorRule.allowedVendors requirement and the instruction to mirror the same brand string into discountSchedule.vendor in the same call, with a worked example ('10 cents off at Love's'). It also explains tripId's lifecycle beyond the schema's own note. It does not touch most options knobs, but the schema already documents those.

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 ('Build an optimized diesel fuel plan for a truck route') and then enumerates the pipeline it runs: routing, truck-stop discovery, live pricing, discount application, and what comes back (stops, gallons, savings, tripId). An agent can distinguish this from the sibling fuel_market_snapshot (market data) 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?

Gives explicit when-to-use branches: omit tripId for a new trip, pass tripId + currentLocation + updated currentFuelGallons to replan the same trip, and the 14-day/destination-match constraint. It also states a hard mandate ('VENDOR RULE ... you MUST set vendorRule.allowedVendors') with the exact paired discountSchedule call shape, and quantifies the cost incentive favoring replans over new plans.

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