commutescout

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

Far exceeds the annotations (which only cover readOnly and openWorld): it discloses the 16-departure cap, data sources per departure (TomTom, NWS hazards, CommuteScout history), how recommended is chosen (quickest without severe weather, or latest arrival if arrive_by set), and time-zone handling.

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 in the first sentence and organized into useful blocks. Slightly long and prose-heavy, but nearly every sentence carries distinct return-value or behavior detail.

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 complex 9-param tool with no output schema, the description fully explains the return shape (recommended, summary, departures, per-departure fields, time_zone) and the selection logic, so an agent has what it needs to 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%, so the baseline is 3, but the description adds real meaning: it explains that step_minutes fits the window into 16 departures and clarifies the arrive_by mode interplay with earliest/latest and the recommended pick.

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 ('when to leave/visit to beat traffic and weather') and gives concrete example questions it answers. It also distinguishes itself from plan_trip, so an agent can route between them without opening schemas.

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?

Provides concrete when-to-use examples ('what's a good time to visit X', 'when should I leave for the airport') and names plan_trip as the live-state alternative. Lacks an explicit 'don't use this for X' exclusion, but the context is otherwise 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?

Adds significant behavioral context beyond annotations: sweeps all sources, severity-sorted incidents, full closure callouts, capping for large regions with exact counts and truncation notice, and freshness details (CHP live, others 5-min cache). Contradicts nothing in annotations.

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

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

Concise, well-structured, and front-loaded. First sentence states core purpose. Subsequent lines list contents, regions, and edge cases. Every sentence earns its place with no 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?

For a complex tool covering multiple data sources with truncation and caching, the description fully explains behavior, output contents, and limitations. No output schema needed as description covers return structure.

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 parameter 'region' is detailed with a list of recognized values (Bay Area, Sacramento metro, etc.) and behavior for unrecognized input. Schema says only type 'string', so description adds essential semantic 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?

Description clearly states it provides a full current-conditions report for a California region, differentiating it from point-query siblings like get_incidents or check_route. It specifies the verb 'check' and resource 'region', and explicitly contrasts with stitching together point queries.

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 tells when to use: for area-scale questions ('how is the Bay Area?', 'what's happening in SoCal?') and recommends it over multiple point queries. Also notes that an unrecognized region name returns the list, providing guidance on error handling.

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?

Description adds value beyond annotations by providing freshness details (CHP incidents ~1 minute, others ~5 minutes), return format (events ordered by miles, plus summary), and behavioral constraints (coordinates clip the route, cannot forecast). No contradiction with readOnlyHint=true or openWorldHint=true.

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 well-structured with a clear opening, followed by coordinated guidance, corridor coverage, and freshness info. While every sentence adds value, it is somewhat lengthy; a bit more brevity could improve conciseness.

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 complex tool with optional coordinates, multiple corridors, and freshness considerations, the description is complete. It covers when to use, how to use coordinates, what corridors are supported, data freshness, and limitations. No output schema exists, but the description states the return includes events and summary, which is 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?

Despite 0% schema coverage, the description explains the purpose of all four parameters: required from_place and to_place, optional from_coords and to_coords as 'lat,lon'. It details what coordinates do—resolving unlisted places and clipping the route—which is critical for effective use.

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 clearly states the tool 'checks current conditions along a major California highway corridor' using the specific verb 'check' and resource 'route conditions'. It distinguishes itself from sibling tools by calling itself the 'flagship trip-check tool' and later instructing to fall back to filtered tools for other corridors.

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?

Explicit instructions on when to use: 'give it a start and end place'. Provides guidance on passing coordinates ('ALWAYS pass from_coords and to_coords when you know where the places are') and explains the role of coordinates. States covered corridors and explicitly says 'This is NOT a general router', advising fallback to filtered tools.

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

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

With readOnlyHint and openWorldHint already declared, the description still adds value by disclosing the return shape (up to `limit` matches, each with a ready-to-pass `coords` string for *_coords arguments) and the implicit US-only scope, which no annotation states. It stops short of mentioning ambiguity ranking or failure modes when nothing matches.

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

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

Two short sentences, purpose front-loaded, usage routed in the second. No repetition of the title or schema fields, and every clause 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?

Without an output schema, the description steps in to describe the return value (matches with a `coords` string) and its downstream use, which is the key missing piece. Minor gap: nothing on how ambiguous matches are ordered or what an empty result means.

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

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

Schema coverage is 67%: `query` and `near` are documented, but `limit` has no schema description. The description partially compensates by saying results are capped at `limit` matches, but it never explains when to pass `near` or how proximity affects ranking. Baseline 3 fits a schema doing most of 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 ('look up a US address or place') plus the concrete output ('get its coordinates'). This clearly separates it from all seventeen siblings, none of which do geocoding.

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

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

Explicitly names two triggering situations: confirming which place the user means before planning, and when a trip tool answers needs_clarification. That is a real use/when-not contract tied to concrete sibling behavior, not just implied usage.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds useful context: the data comes from official feeds and is not a crash database, and it describes the return structure (counts by hour/weekday, incident types, durations). Rate limits or auth needs are not mentioned, but that is minor for a read-only tool.

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

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

The description is front-loaded with a clear statement of what the tool returns, followed by helpful usage examples and a data caveat. It is appropriately sized and every sentence adds value.

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

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

Given no output schema and four parameters, the description sufficiently explains the tool's purpose, usage, and return content. It covers the key caveat about data source, though it could be slightly more explicit about output format.

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

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

Schema coverage is 75%, with days, place, and center having descriptions; radius_km lacks a description. The tool description does not add meaning beyond the schema (e.g., it doesn't clarify the radius unit or effect). With coverage near the high threshold, a baseline of 3 is appropriate.

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

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

The description clearly states it returns historical incident patterns around a place, by hour/weekday with incident types and durations. It does not explicitly differentiate from sibling tools like get_incidents or get_lane_closures, which could cause ambiguity for an agent choosing between 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?

It provides concrete example questions that indicate when to use the tool (e.g., 'is this intersection bad at rush hour'). It does not state when NOT to use it or mention alternative tools, but the context is clear enough for selection.

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 indicate readOnlyHint and openWorldHint, but the description adds valuable behavioral details: images are verified live, offline cameras are filtered out, refresh rate (~1 minute), and existence of HLS stream_url. No contradictions.

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 concise, well-structured into clear sections (data, filters, usage). Every sentence adds value, and the key information is front-loaded. No wasted words.

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

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

For a read-only tool with 4 parameters and no output schema, the description covers essential behavior: data freshness, filtering, ordering, and purpose. It could mention rate limits or auth, but annotations don't hint at those. Overall complete.

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

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

Schema coverage is 0%, so the description must compensate. It explains center (lat,lon), radius_km, route (with examples), and limit, plus adds ordering behavior (nearest-first when center given). This goes beyond schema structure.

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 clearly states the tool's purpose: returning live Caltrans roadside camera snapshots near a point or on a route. It differentiates itself from sibling tools by focusing on visual conditions (fog, snow, traffic) and data quality (verified live images).

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 provides explicit usage guidance: 'Use a camera to let the user SEE conditions...' and explains when to use (visual assessment) and how filtering works. It doesn't explicitly state when not to use alternatives, but the context and sibling list make it clear.

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

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

Annotations already provide readOnlyHint and openWorldHint. Description adds value beyond: 5-minute cache, response format (explicitly says if no controls), data_as_of time. 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?

Description is well-structured: summary, data details, levels, refresh, filters, seasonal behavior, advisory. No fluff, every sentence adds value. Front-loaded with main purpose.

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

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

Given complexity (multiple routes, levels, filters, dynamic data), description covers all: what it returns, filter usage, caching, seasonal behavior. No output schema, but explicitly mentions response includes data_as_of time and explicit statement when no controls, which is 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 has 3 params with 0% description coverage (only types). Description adds meaning: route examples ('80', 'US-50', 'SR-88'), center as 'lat,lon' with radius_km for filtering around a place. This fully compensates for lack of schema 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?

The description clearly states the tool retrieves current chain-control requirements on California mountain highways, listing specific routes and data source (Caltrans). It distinguishes from sibling tools like check_route and get_incidents by focusing on chain controls.

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?

Provides explicit guidance: explains filter usage (route, center, radius_km), seasonal behavior (off-season usually no controls, response says so), and warns about hour-to-hour changes, advising to check data_as_of time and carry chains. This helps the agent decide when to use.

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 this as a read-only, open-world lookup. The description adds the useful facts that coverage is current and includes feed freshness, but it does not describe return shape, granularity, or any limitations beyond that.

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

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

Two short sentences with no filler: first states what it returns, second states when to call it. Front-loaded and efficient.

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

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

For a simple zero-parameter coverage lookup with no output schema, the description is nearly complete. It could say a bit more about the response format, but the core information an agent needs is present.

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 clarify. The baseline for a no-parameter tool is met.

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 clearly identifies the resource as current coverage by state/source and feed freshness. It lacks an explicit action verb, but the intended return value is unmistakable and distinct from sibling tools like check_region or get_traffic.

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

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

It gives a concrete diagnostic trigger: 'Check it when an answer is unexpectedly empty.' That is clear when-to-use guidance, though it does not mention when not to use it or name an alternative sibling.

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

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

Adds rich behavioral context beyond annotations: refresh rate, incident lifecycle (disappear when CHP closes log), live fetching, no history, and data quality issues (free-text, missing coordinates). 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?

Well-organized with sections (summary, data source, filters, limits). Every sentence adds value; no fluff. Information-dense yet readable.

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?

Despite no output schema, description covers data type, freshness, filtering options, limitations, and usage cautions, making the tool fully understandable and usable.

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 has 0% coverage, but description explains each parameter thoroughly: highway matches route in location text, center uses lat,lon with radius_km, area is substring on dispatch area. Includes examples and usage tips, compensating fully for missing schema 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?

Clear verb 'get' with resource 'live CHP traffic incidents statewide, optionally filtered', and detailed data description distinguishes it from sibling tools like get_cameras or get_chain_controls.

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?

Provides explicit guidance on when to use each filter (e.g., center for a town, area for dispatch areas) and warns not to pass a town to area. Does not explicitly compare to siblings, but context makes usage 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 indicate readOnlyHint and openWorldHint. Description adds refresh rate (5-minute cache), data source, exclusion of shoulder-only work, and detailed explanation of closure_class meanings. No contradictions. Provides rich behavioral context beyond 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?

Description is multi-paragraph but dense with information. Each sentence adds value. Could be slightly more structured (e.g., bullet points), but effectively communicates all necessary details without fluff.

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, so description explains output fields: closure_class, estimated_delay_minutes, lanes. Also covers refresh rate and data source. For a read-only tool with 4 parameters and no nested objects, this is comprehensive and leaves no major gaps.

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 has 0% description coverage for parameters. Description fully compensates by explaining each parameter: route with examples, district with district numbers and regions, center as lat,lon string, radius_k with default 40 km. This adds significant meaning 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?

Description clearly states tool returns physically in-place Caltrans lane closures right now. It specifies data source (LCS) and excludes scheduled closures, distinguishing it from a construction calendar. This differentiates it from sibling tools like get_incidents or get_road_signs.

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?

Provides explicit context: use for current closures only, not scheduled. Explains filters (route, district, center/radius) with examples and guidance (e.g., center catches all roads around a place). Does not explicitly state when not to use, but context 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?

Goes well beyond readOnlyHint/openWorldHint by disclosing the auth prerequisite (CommuteScout API key), the degraded state (connected=false with a message explaining how to connect), and a privacy constraint about not repeating the data to others. These are operationally critical traits an agent could not infer 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?

Three short paragraphs, each front-loaded with a distinct concern: what the data is, when to call it, and how to handle it safely. No filler or repetition.

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

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

For a zero-param read tool with no output schema, the description covers the resource, the auth-dependent failure mode, the return signal, and the privacy handling — everything an agent needs to call it and interpret the result responsibly.

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 baseline is 4. The description adds value by naming two response fields (connected, message) that govern whether the call succeeded, compensating for the absence of an output 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 resource (the user's saved places: Home, Work, favorites, recent destinations) and its origin (synced from CommuteScout site and apps). This is clearly distinguishable from siblings like find_place or check_route, which deal with arbitrary locations rather than the user's personal saved set.

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 scopes usage: 'the trip tools already accept "home", "work" or a place's name directly, so call this only to show or choose among them.' It names the alternatives and the precise condition (display/selection) under which this tool is the right call.

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 readOnlyHint and openWorldHint, and the description adds real value beyond them: multi-state normalization, that every event names its publishing agency in the source field, that coverage varies per state (some roadwork-only), and that newly added states appear automatically. It does not describe the event record shape or result ordering, keeping it short of 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?

Well front-loaded: scope and data sources first, then California-escalation guidance, then parameter guidance. It is somewhat long and references external docs (state-coverage.md), but nearly every line carries actionable 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 4-optional-param, read-only, open-world lookup with no output schema, the description covers scope, data provenance, per-state variability, escalation rules, and all four parameters. The main omission is a hint about what a returned event contains beyond the source field.

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 0% schema coverage the description must carry the parameter burden, and it largely does: center as 'lat,lon', place as an alternative address/name, kinds as a comma list with per-value meaning (including that toll adds live and fixed prices), and radius_km capped at 160. It omits the default values (radius 40, default kinds set), which leaves a minor gap.

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

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

States a specific verb and resource (live road events near a point) with an explicit geographic scope (37 states, not just California). It directly distinguishes itself from the dedicated California sibling tools by naming what they offer that this one does not.

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 routing: prefer the dedicated California tools for California questions, use THIS tool outside California, near a border, or as a fallback when a California tool returns empty. It also points to get_coverage for state lists, covering both selection and exclusion conditions.

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 set readOnlyHint and openWorldHint; description adds valuable behavioral context: blank/out-of-service signs filtered, 2-minute cache, and that data reflects road truths before other sources. No contradiction.

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?

Compact yet information-dense, organized into clear sections (Data, Refresh, Filters, Usage). Every sentence serves a purpose with no fluff.

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?

Fully explains data content, refresh cadence, and filtering parameters. Without output schema, it describes what users get (sign text). Could mention typical response size or pagination, but sufficient for the tool's simplicity.

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 0% schema description coverage, description fully compensates by explaining all three parameters: route (e.g., 'I-80'), center 'lat,lon', and radius_km with default value. Adds examples and usage context.

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?

Description clearly states the tool returns 'what Caltrans changeable message signs are displaying right now,' distinguishing it from siblings by emphasizing real-time operational truth before other feeds.

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?

Provides clear usage guidance: 'Quote sign text verbatim to the user - it is the most current and most local signal.' Implicitly contrasts with other feeds but does not explicitly list when not to use or name specific alternatives.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the description's job is to add context, which it does: it names the data source (TomTom), the geographic limit (US only), and the semantics of the reading (live speed vs free-flow). It says nothing about rate limits, quota, or freshness lag, but the core behavioral picture is clear.

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

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

Two short sentences, front-loaded with the core purpose and immediately followed by the use case and the alternative. 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 say what the reading represents (speed vs free-flow). Full schema documentation covers the inputs. Units and per-point response shape are left implicit, but nothing an agent needs in order to choose and call the tool 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%, so the schema already explains place, center precedence, and the up-to-10 points format. The description adds only the interpretive detail that each point is resolved to its nearest road, which is useful but thin 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 and resource: live traffic speed compared against free-flow speed, on the road nearest each point, US-only, sourced from TomTom. That is concrete enough to separate it from incident, camera, and route-planning siblings without opening a schema.

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

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

Gives an explicit trigger ('is the bridge backed up right now') and names the alternative (plan_trip) for a whole drive. It does not address other near-neighbors such as get_incidents or check_route, so routing is clear but not exhaustive.

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 and open-world behavior. The description adds useful behavioral context about the data sources and coverage: NWS forecast, active alerts, and state DOT road-weather sensors where a state publishes them, including pavement/air temperature, wind gusts, and visibility.

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

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

The description is front-loaded, appropriately short, and the second paragraph earns its place by clarifying what road-weather stations are and that availability depends on state publication.

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 three-parameter, read-only weather lookup with no output schema, the description sufficiently lists the returned components: hourly forecast, alerts, stations, and driving hazards. It could be slightly more explicit about response shape, but no major invocation detail 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%, so hours, place, and center are already documented in the input schema. The description adds general scope ('any US place') but no additional parameter semantics beyond the schema.

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

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

The description clearly identifies the resource as an hourly NWS forecast plus active alerts and nearby road-weather stations, scoped to any US place, with driving hazards flagged by hour. It is distinguishable from siblings like get_traffic or get_incidents, though it does not explicitly name alternatives.

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 through 'for any US place' and 'driving hazards flagged by hour,' giving a clear weather-for-driving context. However, it does not explicitly state when to use this instead of route-focused tools such as check_route, plan_trip, or best_time_to_go.

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

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

Beyond annotations (readOnlyHint, openWorldHint), description adds refresh rate (5-min cache), update frequency (once/twice daily), data limitations (origin vs perimeter, small fires may lag), and the near_highways attribute. No contradictions.

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?

Well-structured with clear sections: purpose, data details, filter options, and warnings. Every sentence adds value; no fluff. Front-loaded with essential information.

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

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

For a read-only list tool with no output schema, the description covers data fields, geographic scope (California), filtering options, and limitations. Cross-references to sibling tools ensure the agent can make informed decisions.

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?

Despite 0% schema description coverage, the description fully explains each parameter: near_route (highway name with ~10 mile radius), center (lat,lon with radius_km, default 50), and the behavior when neither is provided. This compensates entirely for the missing schema 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?

The description clearly states the tool returns active California wildfires, with specific data source (WFIGS/NIFC) and fields (name, size, containment, discovery). It distinguishes from sibling tools like get_incidents by noting that small fires may appear there first.

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 describes when to use filters (near_route or center) and the behavior without filters (returns all active CA fires). Also explicitly states what the tool does not do (road closures) and recommends cross-checking with get_incidents and get_lane_closures.

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

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

Annotations only say readOnly and open-world; the description adds substantial context beyond them — the closure-aware ranking logic, TomTom historical speed profiles with live traffic only when departing within the hour, inclusion of a `notes` field for missing/degraded data, and a needs_clarification escape hatch. That is exactly the kind of behavioral detail an agent needs before calling a heavy aggregate tool.

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

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

Purpose line first, then use cases, then a scannable bulleted return manifest, then output-shaping guidance. Every block is load-bearing; the enumeration of ten event types is on the long side but compensates for the absent output schema.

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 six optional params, the description carries the return-value burden and does so fully — route, times, on-route events, weather, summary/notes — plus how to order the answer. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds meaning by tying depart_at to which traffic model is used ('for that departure', live traffic within the hour), which the schema does not say. It does not elaborate on the `preference` enum values, leaving that 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?

Opens with a specific verb and resource plus scope: 'Everything about one drive between any two US places, in one call.' The enumerated return contents (route, drive time, on-route events, alerts) make it immediately distinguishable from lighter siblings like check_route or rank_routes.

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

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

Gives concrete user phrasings that select this tool ("how's the drive to X", "anything on the way to Z") and explicitly routes the departure-time decision to best_time_to_go. It also tells the agent how to handle a needs_clarification response. It stops short of excluding the other route-related siblings (check_route, rank_routes), so it isn't fully exhaustive.

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

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

The description discloses key behavioral traits: fallback to activity if traffic feed is unusable, weighting by event severity, and inclusion of reason in output. Annotations mark it as readOnly and openWorld, but the description adds valuable context beyond those hints.

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 structured into clear paragraphs: purpose, ranking criteria, fallback, and output format. It is slightly verbose but every sentence adds value. The main purpose is front-loaded.

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

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

The description covers the tool's purpose, ranking logic, fallback behavior, and output format (counts and reason). Without an output schema, this provides sufficient context for an agent to understand what to expect.

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

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

The description explains the 'by' parameter's values ('activity' vs 'congestion') and their meanings. The 'limit' parameter is not explicitly described, but its default and role are implied by the output description. Given 0% schema coverage, the description compensates well but could be more explicit about 'limit'.

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 clearly states the tool ranks major corridors by activity or congestion, answering broad traffic questions. It distinguishes itself from sibling tools like check_route or get_incidents by providing an aggregated overview across all 17 tracked corridors.

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 provides clear context on when to use the tool (for broad questions like busiest routes) and implies not for specific details (handled by siblings). However, it does not explicitly state when not to use it or name alternative tools.

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