FreightFA

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

Annotations declare openWorldHint=true, readOnlyHint=false and idempotentHint=false, and the description meaningfully explains the non-idempotent/consumption behavior: "Each question counts toward the account's monthly FreightFA allowance." It also discloses output traits — answers cite sources and may include a priced rate card — which the annotations alone would not convey. Missing only latency/response-time expectations, which keeps it off 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 sentences, zero waste, and front-loaded with the capability statement before the output, session, and cost details. Each sentence carries distinct information: scope, output format, continuation semantics, and billing impact.

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

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

With no output schema, the description carries the return-value burden and does so — answers are source-cited and may include a priced rate card. Combined with the allowance-cost disclosure and session continuation mechanics, nothing an agent needs to invoke 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?

Schema description coverage is 100% and both parameters (question's 2,000-character limit, session_id's continue-vs-start-new semantics) are already fully documented in the schema. The description restates the session_id continuation behavior without adding format or syntax detail beyond the schema's UUID pattern and null option. 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?

The description names a specific verb+resource ("Ask FreightFA's AI freight analyst a question") and then enumerates the domains it covers: lane rates, mode choice, capacity, fuel, carrier vetting, market news, RFP drafting. This is clearly separable from the narrow siblings such as estimate_truckload_rate, get_freight_news, or create_rfp — an agent can tell this is the open-ended catch-all analyst rather than a single-purpose calculator.

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

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

It gives clear context on when to reach for it (broad, plain-language questions spanning many freight topics) and explains the session_id continuation path for follow-ups. It stops short of explicitly naming alternatives or stating exclusions — e.g. that a precise single-mode rate lookup should go to estimate_rail_rate instead — so routing must be inferred from the topic list.

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

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

Annotations declare readOnly/idempotent/non-destructive, and the description adds that it is pure arithmetic with no side effects and does not consume an allowance, which is genuinely useful beyond the annotations (the allowance detail is not in structured fields). Return values are described for a tool with 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?

A single tight sentence covering inputs, all outputs, and the non-billable note. Front-loaded with the core calculation and no wasted phrasing.

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 covering the safety profile, full schema coverage, and the description covering return values and cost implications despite no output schema, an agent has everything needed to call it correctly. The allowance note is a meaningful bonus.

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 each parameter is documented in the schema, so the schema already carries the semantics. The description maps buy to carrier cost and sell to shipper price, reinforcing the schema, but adds no format or edge-case detail beyond it.

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

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

States a specific verb (calculate) and resource (freight margin) with full precision on inputs (buy rate, sell rate) and outputs (margin dollars/percent, per-mile spread, target sell price). No sibling tool name overlaps, so the domain distinction is unambiguous.

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

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

The description frames the calculation context clearly and notes it is pure arithmetic that does not count toward the allowance, which signals when it is cheap to call. It doesn't name an alternative sibling like estimate_truckload_rate, but the input/output contract is specific enough that selection is clear.

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

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

Annotations only declare readOnly/openWorld, but the description adds substantial behavior: verdict sets differ by mode (four verdicts for Dry Van/LTL, no_call for Reefer/Flatbed), the 90-day staleness rule, what is and is not included in the comparison (fuel in, accessorials out), and that each call consumes one estimate from a monthly allowance. It also states a data-handling constraint (never pass document text or PII).

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?

Dense but front-loaded: the core comparison comes first, then usage, then the data-handling constraint, then mode-dependent output and edge rules. Nearly every sentence carries load-bearing information, though the allowance and staleness rules could be tightened.

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

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

With no output schema, the description carries the return-value burden and does so: it names the verdict values, what FreightFA returns for each mode, and the no_call case. Combined with the privacy, staleness, and billing rules, an agent has what it needs to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic guidance beyond the schema: 'takes places, not miles', the all-in-with-fuel vs accessorials split, 'read the fields off the document yourself and pass only those', and the instruction to ask the user when the document omits the mode. Mode-to-document mapping ('a plain truckload or FTL bill is Dry Van') is already in the schema.

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

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

States a specific verb+resource with scope: compare a billed/quoted price for one truckload or LTL load against today's market on the same lane. This clearly separates it from the sibling estimate_*_rate tools, which price a load that hasn't been billed yet.

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 trigger conditions (user uploads, pastes, or describes a bill/invoice/rate confirmation and asks whether the price is fair) plus exclusions (bills older than 90 days are not judged; document contents must not be sent). It does not name a sibling by name when the user is instead asking for a quote on an unbilled load, which is implied but not stated.

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

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

The annotations already establish that this is a non-read-only, non-destructive, closed-world operation. The description adds useful behavior context by stating that the alert belongs to the signed-in user and notifies them when the benchmark crosses the threshold, though it does not discuss duplicate handling or permissions.

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 concise sentences with the core action front-loaded and no redundant wording. Both sentences contribute useful information.

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

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

For a five-parameter creation tool with full schema coverage and clear annotations, the description provides sufficient context about scope and notification behavior. It could optionally mention return behavior or duplicate-alert handling, but no output schema is present to require that.

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 five parameters are already well documented. The description adds no parameter-specific meaning beyond the schema, which is acceptable but not additive.

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: 'Create a lane rate alert for the signed-in user.' It also clarifies the alert's purpose, but it does not explicitly distinguish this tool from the sibling `list_rate_alerts`.

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

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

The description implies the tool is used when a user wants notification about a benchmark crossing a threshold. However, it gives no explicit guidance on when to choose this tool versus alternatives or when not to create an alert.

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 non-read-only, non-idempotent, non-destructive, closed-world. The description adds genuinely new context: the object is created as a *draft* (not sent), lanes are benchmarked against market data on creation, output includes an RFP id and a Builder link, and free accounts are capped at one RFP. That account-limit and draft-vs-sent distinction is not derivable from 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?

One compact sentence pairing the action, cap, and side effect, followed by one sentence on return value and one on the account limit. Front-loaded with the verb and 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?

No output schema exists, and the description compensates by naming the return payload (RFP id, Builder link, per-lane benchmarks). The annotations carry the safety profile and the schema carries the parameters. A small gap remains around error handling at the free-tier limit, but the definition is otherwise self-sufficient.

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

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

Schema description coverage is 100%, so the schema fully documents title and lane fields, so a 3 baseline applies. The description reinforces the lane cap ('up to 50 lanes') but adds no field-level meaning beyond what the schema provides.

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

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

States a specific verb and resource ('Create a draft freight RFP'), names the system (FreightFA), and scopes the artifact (up to 50 lanes, per-lane benchmarking). This clearly separates it from sibling read tools like get_rfp and list_rfps.

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

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

The description implies the workflow (create a draft, then finish/send it in the RFP Builder via the returned link) and states a hard constraint ('Free accounts can have one RFP'). However, it never explicitly says when to reach for this versus get_rfp/list_rfps or what to do if the account limit is already reached.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the fallback to the national all-in rate when no benchmark is supplied, and the entitlement gate (FreightFA Pro and Desk accounts). It stops short of describing the return format.

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

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

Four sentences, purpose front-loaded, with the optional counter behavior and fallback rule following logically. Minor redundancy with the schema keeps it from being maximally 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?

No output schema exists, so the description carries the burden of describing what comes back, yet it never says whether the result is plain email text, a structured draft, or a preview. The entitlement and fallback details are helpful, but the absent return-format description is a real gap for a drafting tool.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including what want_counter and benchmark_per_mile do. The description's notes on want_counter=true and the null-benchmark fallback largely restate the schema, adding little beyond the baseline.

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

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

States a specific verb (draft) and resource (pushback email on a truckload quote) and names the audience (broker or carrier). It is immediately distinguishable from sibling tools like estimate_truckload_rate or create_rfp.

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 scenario implies when to use it (a truckload quote you want to push back on) and it references sourcing the benchmark from the market data, but it names no explicit alternatives or when-not-to-use conditions (e.g., LTL or intermodal pushback, or simply calling estimate_truckload_rate).

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, non-destructive, non-idempotent, closed-world), and the description adds substantial behavior on top: the failure mode (returns available:false with the reason), the pricing basis (river miles), the minimum shipment threshold, the benchmark nature of the result, and a quota cost of one estimate against a monthly FreightFA allowance.

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 dense sentences, front-loaded with the purpose and then the qualifying conditions. Every sentence carries load (eligibility, failure mode, pricing basis, quota), though the eligibility clause packs several conditions into one long sentence.

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 explains what comes back (a directional benchmark, or available:false with a reason) and the constraints that govern whether a price exists at all. For a 5-required-parameter estimate tool with full schema coverage, nothing an agent needs 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, but the description adds meaning the schema does not: distance is interpreted as river miles, weight must clear roughly 1,500 short tons / 3,000,000 lb for a barge-load, and commodity_type is implicitly constrained to bulk goods that barges carry.

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 (estimate) plus the resource (inland waterway barge freight rate) and enumerates the five inputs that drive it. It also roots the estimate in a named source (USDA's weekly downbound grain barge rates), which distinguishes it from the rail/truckload/intermodal estimators in the sibling list.

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 eligibility rules: priced only when both ends are Mississippi/Illinois/Ohio River ports, the lane is downriver, and the shipment is at least one barge-load. It even points at recommend_mode for deriving distance. It stops short of naming which sibling estimator to use when the barge conditions fail, so routing to rail or truckload 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?

It discloses a real cost behavior the annotations do not: every call consumes one estimate from the monthly FreightFA allowance, which explains the idempotentHint=false and is critical for an agent deciding whether to retry or batch. It also notes the no-service case. It stops short of describing accuracy, validity period, or rate currency.

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?

Purpose and scope are front-loaded in the first sentence, followed by two short sentences covering the no-service outcome and the quota cost. No filler or restatement of the tool 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 usefully frames what the estimate contains (drayage legs, line-haul, ramps used) and covers the no-service case and quota consumption. Minor gaps remain around pricing units/currency and whether the estimate is a single point or range, but the agent has enough 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 coverage is 100% and origin/destination/weight are each documented there, so the baseline is 3. The description adds that the two places are U.S. origin/destination points for a door-to-door move, but says nothing about the weight parameter or accepted location formats 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 (estimate a domestic intermodal rate) and breaks the product into its components: origin drayage, rail line-haul, destination drayage, plus the ramps used. This clearly separates it from sibling estimators like estimate_rail_rate, estimate_truckload_rate, and estimate_ltl_rate.

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 scopes the tool to domestic U.S. door-to-door lanes and states it flags lanes without intermodal service, which implies when results are usable. However, it never explicitly says when to choose this over estimate_rail_rate or the truckload estimator, nor does it state a mode-selection rule, leaving the agent to infer the boundary.

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, destructiveHint=false), so the bar is lower. The description adds genuinely useful non-schema behavior: each call consumes one estimate against the account's monthly FreightFA allowance, and the result is a directional benchmark rather than a binding rate. It does not discuss accuracy limits, currency, or turnaround.

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, all front-loaded: what it does, what it returns, what it costs. No filler and nothing an agent must hunt for.

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 tell the agent the result is a directional benchmark rather than a firm quote, and it discloses the quota cost. Missing details about the response shape (rate value, currency, breakdown) keep it short of a 5, but it is adequate for a fully-specified read-only estimation tool.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including units and null semantics. The description adds no parameter-level detail beyond naming the tariff method, 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 (estimate), resource (less-than-truckload rate), and even the pricing basis (FreightFA's CzarLite-basis tariff calculator). This cleanly distinguishes it from the many sibling estimators such as estimate_truckload_rate, estimate_intermodal_rate, and estimate_rail_rate.

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?

"Returns a directional benchmark for planning" implies the appropriate context (early-stage planning rather than binding quotes), but it never states when to choose this over estimate_truckload_rate or estimate_intermodal_rate for a given shipment, nor any prerequisites beyond the schema's required fields.

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 cover safety (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), so the bar is lower, and the description still adds value: the result is persisted ('Saved to the user's Network Builder') and a trial run is a one-time, consumed resource. It does not state what happens on repeated calls with the same name or any account-tier prerequisites beyond the Desk mention.

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 core operation and scope before the persistence note and the pricing/trial caveat. No filler or restatement of the tool 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 carries the burden of describing returns and does so partly ('each leg's mode, cost, and transit time', or costless legs without a Desk plan). It still leaves open whether an identifier is returned, how the saved network is later retrieved, and what the total looks like.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: it explains the pricing/paywall consequence of use_trial_run ('otherwise legs come back without costs') and reinforces the 10-leg cap. Legs' internal fields (origin, destination, weight_lbs, commodity_type) are left entirely to 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 ('Price a supply chain of up to 10 legs ... and total it') and makes the scope explicit (factory-to-store, domestic or international, 10-leg cap). This clearly separates it from the single-mode siblings such as estimate_truckload_rate or estimate_ltl_rate, which price one lane rather than a totalled multi-leg network.

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 conditional for use_trial_run: Desk accounts get full costs, other accounts can 'spend the account's one-time trial run', otherwise legs return without costs. That is real when-to-use guidance, but it never routes the agent away from the single-mode estimate siblings for simple lanes.

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 cover safety (readOnly, non-destructive, open-world), yet the description adds the real behavioral payload: the USDOT rail-access check, the 50-mile threshold, the available:false + reason fallback instead of a price, and the per-call quota against the monthly FreightFA allowance. None of this is derivable 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 sentences, front-loaded with the purpose and then layering the access-check behavior, the caveat, and the billing note. Each sentence carries information; only the 'directional benchmark' sentence is somewhat soft.

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 real work explaining the failure return shape (available:false plus reason) and the nature of the result. It stops short of describing the successful price payload's structure, which an agent calling without an output schema might want.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates that origin/destination enable the rail access check, which the schema already documents ('Recommended: enables the rail access check'), so it adds little semantics beyond the structured 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 and resource with scope: 'Estimate a Class I carload rail freight rate for a commodity, distance, and weight.' That immediately separates it from the sibling estimators (estimate_barge_rate, estimate_intermodal_rate, estimate_ltl_rate, estimate_truckload_rate, estimate_network_cost).

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 triggering condition for the origin/destination inputs and an explicit exclusion: 'Don't quote rail on such a lane.' It also frames the output as a planning benchmark rather than a firm quote. It doesn't route the agent to an alternative tool when rail is unavailable, which keeps it 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 cover safety (readOnlyHint=true, destructiveHint=false) but not the metered cost, so 'each call counts as one estimate toward the account's monthly FreightFA allowance' is genuinely additive — it warns the agent to avoid redundant calls. 'Directional benchmark' also sets expectations on precision, though the actual response shape is left 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?

Three short sentences, front-loaded with purpose. The quota warning and the precision caveat are each a single clause with no filler.

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

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

For a 9-parameter tool with no output schema, the description omits the location-input alternatives (origin/destination vs origin_zip/destination_zip) and says nothing about what the returned rate looks like beyond 'directional benchmark'. The quota note is a strength, but the input-mode ambiguity is a real 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?

At 67% schema coverage, the schema documents weight, distance, pickup_date, request_id, and origin, but leaves origin_zip, destination, and destination_zip bare. The description does not clarify the either/or input pattern (city pair vs ZIP pair) that the schema's param descriptions only hint at, so it adds 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 ('Estimate a full-truckload freight rate for a lane') and names the engine behind it (FreightFA). 'Full-truckload' immediately separates it from estimate_ltl_rate, estimate_rail_rate, estimate_barge_rate, and estimate_intermodal_rate among 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?

'Returns a directional benchmark for planning' implies the use case (rough planning, not a booked quote), which is useful context. But it never says when to prefer recommend_mode first, or when a different mode estimator is appropriate, and gives no exclusion 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 cover read-only, idempotent, non-destructive, and closed-world traits, so the bar is lower. The description adds value beyond them by disclosing return content (who publishes it, how to read it, why it matters) and a non-annotation behavioral attribute: that calls do not count toward the allowance.

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?

Purpose is front-loaded in the opening clause, and the long term enumeration, while lengthy, functions as a useful discovery aid for matching. The sentence structure is tight and each sentence carries information, though the example list is on the verbose side.

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

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

For a single-optional-param lookup tool with annotations and no output schema, the description is largely self-sufficient: it explains what is returned and the fallback behavior. Minor gaps remain around matching behavior (abbreviations vs. full names) and result format, but nothing essential is missing.

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

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

Schema description coverage is 100% and the single `term` parameter is already documented with examples and the omit/null behavior in the schema. The description restates 'omit the term to list every entry' but adds no format or matching semantics (e.g. case sensitivity or fuzzy matching) beyond the schema. 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 deliverable (plain-English definition) and a specific resource (freight market index, ratio, or charge from the FreightFA glossary), with a concrete list of covered terms. An agent can distinguish this lookup tool from analysis tools like get_freight_index_outlook or ask_freight_analyst 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 clear context for use (defining/decoding a term) and explicitly describes the no-arg fallback behavior (omit the term to list every entry with its link). It does not, however, name sibling alternatives such as ask_freight_analyst for interpretive questions, so routing vs. those tools 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds a genuinely non-schema behavioral fact — 'Does not count toward the allowance' — a quota/cost disclosure that helps the agent decide how freely to call it, plus a summary of what the result contains. It stops short of richer context (e.g., completeness of coverage, freshness).

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 purpose, followed by the return contents and the null-case behavior. No filler or redundancy.

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

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

With no output schema, the description usefully enumerates the returned fields so the agent knows what it gets back. Combined with the quota note and null-case rule, it is nearly complete for a simple two-parameter lookup, though it does not state coverage scope (all U.S. hubs vs. a subset) or result-size expectations.

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

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

Schema description coverage is 100% and the description's parameter content ('by city or state', leave both out for all) merely restates what the schema already documents. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb ('look up') and resource ('U.S. intermodal rail hubs') and describes the returned content (serving Class I railroads, named ramps, notes). An agent can distinguish this from siblings like estimate_intermodal_rate or get_rail_market_outlook 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 gives one useful usage rule — 'Leave both out to list every hub' — which tells the agent how to enumerate all hubs. However, it offers no guidance on when to prefer this over adjacent tools such as lookup_carrier, recommend_mode, or the various estimate_intermodal_* siblings. Usage is implied rather than routed.

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), and the description adds genuinely useful behavior beyond them: the data is USDA weekly, the outlook is only produced 'where it has passed a backtest,' it reports when places aren't on a priced corridor, and it 'does not count toward the allowance.' That quota/backtest/edge-case disclosure is strong context, though return format and staleness are still 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?

Three tight sentences, front-loaded with what the tool returns, followed by the outlook condition, the failure case, and the quota note. Every sentence earns its place with no padding.

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

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

For a two-parameter read tool with strong annotations but no output schema, the description covers data source, cadence, the outlook caveat, an error path, and billing impact. It stops short of describing the returned fields or units, which is the only notable gap given no output schema exists.

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 origin/destination are already documented. The description nonetheless adds a real constraint the schema lacks: the places must lie on the Mississippi, Illinois, or Ohio River corridor, which directly shapes valid values for both parameters.

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 ('USDA weekly downbound grain barge rates') plus the exact scope (two Mississippi/Illinois/Ohio River places). This distinguishes it from estimate_barge_rate (a point estimate) and the broader get_market_outlook/get_rail_market_outlook siblings without needing to name them.

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

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

The description never says when to reach for this tool versus estimate_barge_rate or the other outlook tools, and names no alternatives or exclusions. The sentence about unpriced corridors describes behavior, not usage selection, so the agent is left to infer the 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 declare it read-only, idempotent, non-destructive and closed-world, and the description adds substantial extra context: it is rebuilt several times a day, every figure carries date and source, failed figures are surfaced as held back with a reason rather than hidden, and it does not count toward the estimate allowance. That freshness, quality-control and quota information goes well beyond the annotations.

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

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

The entry-point guidance is front-loaded and every clause maps to something an agent needs (contents, data provenance, held-back behavior, caching/citation rule, quota). It is a dense single paragraph rather than a run-on, though it is long enough that a structure break would help.

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 and no parameters, the description carries the full burden and discharges it by enumerating the return payload, its provenance, and how withheld figures appear. An agent has everything needed to call it and interpret the result.

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?

Zero parameters, so the baseline is 4. The description explicitly confirms 'no inputs,' which matches the empty schema, but there is no additional parameter meaning to convey.

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 concrete verb and resource ('daily freight brief in one call') and enumerates exactly what the call returns (truckload rates, diesel, outlook, capacity, rail/ocean/air/barge readings, stories). The opening 'Start here for any general freight market question' positions it against the narrower siblings like get_market_snapshot and the estimate_* 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?

'Start here for any general freight market question' gives clear entry-point guidance, and the enumerated contents imply which specific questions it covers. It stops short of naming an alternative tool or stating exclusions, so it falls below the explicit when/when-not bar.

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 it read-only, idempotent, non-destructive and closed-world, and the description goes further: it discloses output behavior ('a forecast band is shown only where it has passed a backtest and the source readings are consistent; otherwise the answer says what was held back and why') and a quota trait ('Does not count toward the allowance'). These are valuable behavioral facts not derivable from the annotations.

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

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

Front-loaded with the core purpose, then indices, then omit behavior, then the forecast-band caveat and quota note. It is denser and longer than strictly necessary, but every sentence carries distinct information, so little is wasted.

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

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

With no output schema, the description does useful work explaining the forecast-band conditional and quota handling, and the single optional param is fully covered. It could say more about the return shape (e.g., source readings, dates, units per index), which is the remaining gap.

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

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

Schema coverage is 100% and the enum is documented, but the schema only lists the four enum strings with no meaning. The description adds genuine semantics by labeling each (drewry_wci = Drewry WCI $/40ft container, baltic_dry_index = dry bulk, tac_air_index = air cargo, iata_jet_fuel = jet fuel) and restating the omit/null behavior.

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 ('Latest reading and next-period outlook for a global freight index') and enumerates the four supported indices with plain-language meanings. An agent immediately understands the resource is ocean/air freight indices, distinguishing it from rail/barge/market outlook siblings by scope.

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

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

Guidance is limited to the parameter ('Omit the index to get all four'), which is really usage of a field. There is no explicit when-to-use or when-not-to-use vs alternatives such as get_market_outlook, get_rail_market_outlook, or ask_freight_analyst, so selection context is only implied by the enumerated indices.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the bar is lower, and the description still adds real context: result ordering ('newest first'), the shape of each item, and the non-obvious fact that it does not count toward the monthly allowance. It stops short of noting pagination or that limit caps at 20 items per 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?

The content is front-loaded with what the tool returns and how to filter, with no filler sentences. 'Works with no inputs' is marginally redundant given zero required parameters, but it is a defensible one-line reassurance.

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 compensates by describing the return fields (titles, dates, summaries, links) and ordering, and annotations carry the safety profile. It is essentially complete, missing only minor operational details like maximum result count and pagination behavior.

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 limit, topic, and source are already fully documented in the schema, and the description's 'filter by source or by a topic keyword' plus examples largely restates that. This is the baseline 3 case where structured fields do the heavy lifting and the description contributes little extra meaning.

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 verb (get) and resource (FreightFA freight news) and enumerates the content types returned: Pulse market stories, Brief newsletter articles, videos, and podcasts. That scope separates it from pure-outlook siblings like get_market_outlook, but it never explicitly distinguishes itself from the closely overlapping get_freight_brief sibling, which blurs selection.

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

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

It gives a usable trigger ('Use it for what is happening in freight right now; cite the linked page') and notes it works with no inputs. However, no alternative is named or excluded, which matters here because get_freight_brief, get_market_snapshot, and get_freight_index_outlook all plausibly compete for the same 'what's happening' request.

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 establish the safe read-only/idempotent profile, and the description adds real context beyond them: the 'does not count toward the estimate allowance' quota behavior and the shape of the returned forecast including caveats. No contradiction with annotations.

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

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

Front-loaded with the purpose before the payload details, and the scope and allowance caveats follow in a tight sequence. Dense but each clause carries information; 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?

With no output schema, the description correctly carries the return-value burden by spelling out average, band, trend, rationale and caveat. A single optional parameter is fully covered, so an agent has enough to call it correctly; only the sibling-routing detail is thin.

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

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

Schema coverage is 100% and the single enum-like parameter is fully documented in the schema, so the baseline is 3. The description's 'Omit the equipment type to get all three' merely restates the schema's 'Omit or null for all three' 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?

States a specific verb+resource ('forecast for next week's U.S. national spot rate per mile') and enumerates the exact payload (weekly average, p10/p50/p90 band, trend direction, rationale, caveat). 'National, not lane-specific' plus the named equipment types distinguish it from siblings like estimate_truckload_rate and get_rail_market_outlook.

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: use for national aggregate view, not lane-specific work, and 'Omit the equipment type to get all three' tells the agent exactly how to widen the query. Also discloses that it does not consume the estimate allowance. It stops short of naming the sibling outlooks (rail, barge, index) as alternatives, so no explicit when-not 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 readOnly/idempotent/non-destructive/closed-world, so the safety bar is met. The description adds real context beyond them: the rates are all-in including fuel, each figure carries an as-of date, the change window is 7 days, and the call has no allowance cost.

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?

Content is front-loaded: outputs first, then usage, then the allowance note. The first sentence is dense and heavily parenthetical, but every clause earns its place and nothing is redundant.

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

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

With no output schema, the description enumerates the returned fields (three equipment types, live-quote index, EIA diesel, as-of dates, 7-day change), which is exactly what an agent needs to use the result correctly. No gaps remain for a zero-parameter read tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly implies the call is unfiltered (national, today), which confirms no inputs 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 a concrete resource (today's U.S. national truckload rates per mile, live-quote index, EIA diesel) and the scope (national, today, 7-day change), so the agent knows exactly what it returns. It stops short of naming the sibling tools it is not (e.g. estimate_truckload_rate, get_market_outlook), so differentiation is inferred rather than stated.

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

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

It gives an explicit trigger phrase ('what are truck rates right now') and an instruction to cite FreightFA with the as-of date, plus the useful note that it doesn't count toward the estimate allowance. It doesn't state when to prefer a sibling such as estimate_truckload_rate or get_market_outlook instead, so exclusions are 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 already cover the safety profile (read-only, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real context: the data source (SEC filings), fuel surcharges included, the backtest qualification on the outlook, and notably 'Does not count toward the allowance', a quota disclosure.

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 core outcome, and each clause (source, surcharge treatment, backtest, omit behavior, national scope, allowance) earns its place. It is dense as one long sentence but not padded.

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

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

With no output schema, the description usefully characterizes the returned quantity (YoY change in revenue per carload) and scope. For a one-param read tool this is nearly complete; only the exact return shape/pagination is left implicit, which is minor.

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

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

Schema coverage is 100% and the single enum param is fully documented in the schema, so the schema carries the load. The description restates the group choices and the omit-for-both behavior without adding format or edge-case meaning beyond it — baseline 3.

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

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

It states a specific verb and resource — how U.S. rail carload prices are moving, measured as Class I revenue per carload YoY from SEC filings. The scope ('National, not lane-specific', Agricultural/Industrial freight) clearly separates it from lane-level siblings like estimate_rail_rate and from the broader get_market_outlook.

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

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

There is clear context: 'Omit the group to get both' and 'National, not lane-specific' guide invocation and implicitly rule out lane-level use. It stops short of naming an explicit alternative (e.g., estimate_rail_rate) for the lane-specific case, so it is 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds that access is scoped to the signed-in user's own documents and that lanes are included in the payload — modest but real additions beyond the annotations.

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

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

A single front-loaded sentence with the resource and scope stated immediately; no filler or redundancy. Every clause (ownership scoping, lanes payload) carries information.

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

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

There is no output schema, so the description must hint at the return payload — it does by noting lanes are included. For a simple single-id read this is nearly sufficient, though a fuller sense of the returned document structure is not given.

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 a single parameter at 100% schema description coverage, the schema fully documents rfp_id (type, UUID format, pattern, meaning). The description adds no syntax or format detail beyond that, 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 (fetch), resource (RFP document), and scope (one of the signed-in user's, singular, so keyed by id). This implicitly separates it from list_rfps and create_rfp, though it never names a sibling explicitly.

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

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

The phrasing 'one of the signed-in user's RFP documents' implies this is the detail-lookup path keyed by id, but there is no explicit when-to-use vs. list_rfps or when-not guidance, and no prerequisites stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the per-user scoping detail; it says nothing about pagination, result limits, or ordering, so it adds modest value beyond the annotations.

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

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

A single short sentence with no wasted words, and the scope qualifier is placed immediately after the verb-resource pair. Appropriate size for a one-parameter read 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 simple read-only list tool with full schema coverage and no output schema, the description covers the essential scope. It could note default result ordering or the effect of the active_only flag, but nothing critical is missing.

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

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

Schema description coverage is 100% and the single required parameter 'active_only' is fully documented in the schema. The description mentions no parameters at all, 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 ('List') and resource ('lane rate alerts') scoped to the signed-in user, which cleanly distinguishes it from the sibling create_rate_alert. It does not, however, differentiate itself from other list_* siblings or explain ordering/content.

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 'signed-in user's' implies the scope of use, but there is no explicit when-to-use guidance, no mention of when-not to use it, and no reference to alternatives such as create_rate_alert. Usage is only weakly implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety bar is covered. The description adds genuinely new behavioral context: results are newest-first, cover multiple channels, and include per-search frequency plus a five-part price breakdown, which tells the agent what to expect in the payload.

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

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

A single front-loaded sentence that opens with the verb and resource, with no filler. It is dense and somewhat run-on, but every clause (sources, ordering, breakdown fields, frequency) contributes information an agent can use.

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

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

No output schema exists, so the description must convey returns — and it does, enumerating ordering, channels, and the price breakdown/frequency fields. The only minor omission is any hint about pagination beyond the documented limit.

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 (limit) with 100% schema coverage, including its default and max, so the schema fully documents it. The description adds nothing about the limit or how it interacts with the result set, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource ('List the signed-in user's recent freight rate searches') and scopes it further by source channel (website, chat, assistant) and ordering (newest first). This clearly separates it from sibling list tools such as list_rate_alerts, list_rfps, and the estimate_* rate 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?

Usage is implied by the phrase 'recent searches' — an agent can infer this is a history/retrieval call — but there is no explicit when-to-use guidance, no exclusions, and no named alternative (e.g. list_rate_alerts for alerts vs. this for past pricing). Adequate but leaves routing 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds useful behavioral context beyond that: the result ordering ('newest first') and that lane counts are included. It does not address pagination behavior despite a limit parameter existing.

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 tight sentence with the resource front-loaded and sort/return details appended. Every phrase earns its place; nothing is redundant.

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

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

For a simple list tool with annotations carrying the safety profile and a fully documented schema, the description covers scope, ordering, and return content. Lacking only explicit pagination behavior, which is minor given the documented limit parameter.

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

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

Schema description coverage is 100%, so both status and limit are already documented with defaults and constraints. The description adds no parameter syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

Specific verb+resource: 'List the signed-in user's RFP documents,' which distinguishes it from the singular get_rfp and the write-oriented create_rfp. It adds sort order ('newest first') and return content ('lane counts'), though it does not explicitly name the sibling it contrasts with.

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 — an agent gathers its own RFPs, presumably to then call get_rfp on one — but there is no explicit when-to-use statement, no mention of alternatives like get_rfp, and no exclusions. Adequate but leaves routing 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?

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the description's added value is the operational context: 24-hour cache, no charge against the estimate allowance, and null means not available. Missing only failure behavior when a carrier is not found.

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 core action and return contents, and every sentence carries information (data source, output pairing, null semantics, identifier choice, cache, quota). Slightly dense as a single block but 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?

With no output schema, the description carries the return-value burden and does so well by listing the data categories and the FreightFA report contents. The gap is ambiguity around name searches returning multiple matches and the not-found case.

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

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

Schema coverage is 100% and each param is documented, so baseline would be 3. The description adds genuinely new meaning: only one of the three identifiers should be supplied, which resolves the schema's otherwise confusing requirement of all three.

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 ("Vet a U.S. motor carrier from FMCSA SAFER data") and enumerates the returned dimensions: authority, safety rating, insurance, out-of-service rates, and the FreightFA report. No sibling tool performs carrier vetting, so the agent can confidently route here.

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?

"Search by USDOT number, MC number, or carrier name (give one)" tells the agent how to invoke it, and the vetting framing implies the pre-qualification use case. It stops short of explicit when-not-to-use or alternative routing, though no sibling overlaps.

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, openWorld), so the bar is lower. The description still adds genuine behavioral context beyond them: what the response contains (ranked modes with reasons plus distance) and the business constraint that it 'does not count toward the estimate allowance'.

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, each carrying distinct information (outputs, workflow ordering, international edge case, allowance note). The core capability is front-loaded and nothing is wasted.

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

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

With no output schema, the description steps in to explain the return values (ranked modes, reasons, distance). Combined with the 100%-covered input schema and the workflow guidance, 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 all four parameters are already documented. The description's mentions of 'city names or ZIPs' and U.S. lanes only echo what the schema's origin/destination descriptions already say, adding no new syntax or format detail. 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?

Uses a specific verb ('Rank') with the exact resource (the seven named freight modes) and states the two concrete outputs: ranked modes with reasons and lane distance in miles. It clearly differentiates itself from the estimate_* siblings by framing itself as the routing/distance step that precedes them.

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

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

Gives explicit ordering ('Use it first when you only have city names or ZIPs, then pass the distance to an estimate_* tool'), which names the alternative and the condition that selects it. It also handles the edge case by stating that international lanes return ocean/air routing instead.

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