wsdot-mcp-server

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

Annotations only declare readOnlyHint=true. The description goes well beyond that: it explains the exact number of entries (eleven), the naming conventions (crossingName as route code, readable name in location.description), the lane structure for each crossing, and the behavior when no data is available (waitTimeInMinutes omitted). This provides rich behavioral context that an agent needs to interpret results correctly.

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 clear and efficient. It front-loads the core purpose, then provides specific structural details (lane counts, naming scheme, data omission behavior) without redundancy. Each sentence adds new information, and the structure flows logically from overview to specifics.

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 the tool has no parameters, is read-only, and has an output schema, the description covers everything needed: the specific crossings, lane variations, naming conventions, and missing-data behavior. Even though the output schema exists, the description explains the semantics of the fields, making the tool self-contained and easy to invoke without external context.

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 has zero parameters, so the description correctly avoids mentioning any. The baseline for 0 params is 4, and the description doesn't need to add parameter semantics. It does provide context about the output structure, which is more relevant than parameter details here.

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 uses a specific verb ('Returns current vehicle wait times') and a clear resource ('WA→Canada land border crossings'). It lists the exact border crossings and lane types, distinguishing it from sibling tools like ferry alerts, mountain passes, or toll rates. The scope 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 final sentence explicitly states when to use the tool: 'Use for "how long is the border wait?" questions.' It also clarifies that crossings without current data are still returned, which sets expectations. It doesn't explicitly say when not to use it, but the sibling tools are clearly distinct domains (ferries, passes, tolls), so exclusions are implicitly obvious.

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: true, so the description correctly avoids repeating that. It adds meaningful behavioral context by explaining the structure of each alert, the presence of route IDs, and the caveat about missing routes. This is more than the annotation provides and helps the agent interpret results. 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?

The description is concise and well-structured. It front-loads the core purpose, then gives a brief overview of content, and finally provides cross-referencing guidance. Every sentence adds value without redundancy. It is appropriately sized for the tool's simplicity.

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 the tool has no parameters and an output schema (though not shown), the description fully explains what the agent can expect: each alert's structure and how to resolve route IDs. The caveat about missing routes is a useful edge case. All necessary information for calling and interpreting results 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 has zero parameters, so the schema is trivially complete. The description doesn't need to explain parameters. Baseline is 4, and the description adds no irrelevant parameter information, so a 4 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 active WSF ferry service disruptions, delays, and bulletins. It specifies the verb 'Returns', the resource 'WSF ferry service disruptions', and includes details about the alert content (summary, title, kind, body). This distinguishes it from siblings like wsdot_get_ferry_routes and wsdot_get_ferry_schedule.

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 gives clear context on when to use this tool (for alerts/disruptions) and provides an important cross-referencing instruction with wsdot_get_ferry_routes. It also notes a caveat about route IDs not appearing. While it doesn't explicitly state when NOT to use it, it implies that this is the go-to for disruptions. The guidance is sufficient for an agent to select it appropriately.

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 readOnlyHint annotation already flags this as a read operation, so the description doesn't need to repeat that. It adds meaningful context by explaining the relationship between route IDs and alert route IDs, including the caveat about excluded alerts. This goes beyond the structured annotation and helps the agent interpret results correctly, though it omits details like refresh timing or sort order.

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, each earning its place: the first states the core function, the second explains the correspondence and exceptions, and the third points to the alternative. The main purpose is front-loaded, and there is no redundant or filler content.

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 the tool's simplicity (one optional parameter, read-only, output schema provided), the description is complete. It covers the tool's purpose, its relationship to alerts, and the alternative for terminals. No missing information would prevent an agent from calling 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?

The schema describes the tripDate parameter completely (ISO 8601 format, optional, defaults to today), achieving 100% coverage. The description does not add further parameter-specific detail, which is acceptable given the schema already handles it. The baseline of 3 applies because the schema carries the full parameter 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 clearly states the tool 'Returns the main WSF ferry routes operating on a given date.' This specifies the verb, resource, and temporal scope. It also distinguishes itself from siblings by explicitly mentioning the correspondence to impactedRouteIds in ferry alerts and naming the alternative for terminal IDs, so an agent can differentiate it 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?

The description provides explicit guidance: it tells when to use this tool (to get routes for a date) and when it may be insufficient (some alert route IDs like seasonal, San Juan interisland, or Sidney B.C. may not appear). It also directs the agent to wsdot_get_ferry_terminals for terminal IDs, leaving no ambiguity about the appropriate tool choice.

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

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

Beyond the readOnlyHint annotation, the description discloses crucial behaviors: the timezone mismatch (UTC vs Pacific service day), the fact that cancellations are dropped rather than flagged, and the need to check alerts separately. This adds significant context not captured by annotations.

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

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

The description is efficiently structured: starts with the core function, then usage requirements, then behavioral caveats, and ends with guidance on related tools. Every sentence earns its place; no redundant 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?

Given the presence of an output schema and the moderate complexity, the description covers prerequisites, timezone pitfalls, cancellation semantics, and cross-tool references. It fully equips an agent to call the tool correctly without 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?

The input schema already has 100% coverage for all four parameters. The description adds extra meaning for tripDate (Pacific service day and timezone note) and reinforces the terminal ID lookup, providing subtle value beyond the schema without repeating verbatim details.

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 begins with a clear specific action: 'Returns departure times for a specific WSF ferry route on a given date.' It distinctly separates from siblings by referencing wsdot_get_ferry_terminals for ID resolution and wsdot_get_ferry_alerts for disruptions, making the tool's scope 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?

Provides explicit usage instructions: requires numeric terminal IDs, directs to wsdot_get_ferry_terminals for resolution, explains the remainingOnly behavior for today's future sailings, and advises checking alerts for disruptions. It effectively tells when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true, so the description adds value with the stability and size notes (small, rarely changes), which are useful behavioral traits beyond the safety flag. 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?

Three sentences, each earning its place: what it returns, why to call it first, and a note on data stability/size. Front-loaded and perfectly sized 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?

For a simple list endpoint with an output schema, the description covers purpose, usage, and data characteristics completely. An agent has everything needed to invoke 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?

The tool has zero parameters, so the description appropriately ignores parameter details. Baseline of 4 is correct; nothing needed to be added.

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 exactly what it returns — all WSF ferry terminals with numeric IDs, names, and abbreviations — and explicitly links it to resolving names for schedule and space tools, distinguishing it from siblings like schedules and 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?

Gives explicit direction to 'Call this first' and explains the use case (resolving human-readable names to numeric IDs needed by other tools). Also notes the list is small and rarely changes, signaling it's a stable lookup.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds context about the data returned (status, weather, etc.) and the full scope of 16 passes, which is useful behavioral context beyond the annotation. However, there is no disclosure of rate limits, authentication needs, or any side effects, and the description does not go beyond what the annotation plus its own purpose statement already communicate.

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 three sentences with no waste. The first sentence states purpose and data fields, the second lists the passes, and the third gives usage examples. It is front-loaded with the core function and efficiently structured.

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 zero parameters, a read-only hint, and an output schema present, the description covers everything an agent needs to call this tool: what it returns, the full scope of passes, and typical use cases. There is no missing information 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?

The tool accepts zero parameters, and the schema coverage is 100% (there is nothing to document). The description properly indicates the tool needs no input and focuses on the output scope. Per the rubric, a 0-parameter tool receives a baseline of 4, and the description does not need to add parameter details.

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 ('Returns') and a precise resource ('current road conditions for all Washington State mountain passes'), and lists the data fields it provides (status, weather, road condition, traction laws, temperature, elevation). It also mentions all 16 passes by name, clearly distinguishing this tool from siblings that handle ferries, borders, and cameras.

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 gives explicit use cases: 'Use for "is the pass open?", traction law status, or winter driving planning.' This provides clear context for when to call the tool. However, it does not explicitly mention alternatives or when not to use it, though the sibling differentiation is implicit given the highly specific scope.

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

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

Beyond the readOnlyHint annotation, the description discloses critical behavior: paging is by terminal (offset/limit select terminals, not sailings), totalCount counts terminals, every sailing for a returned terminal is included (so page size varies), and driveUpSpaceCount=0 means the lane is full. These nuances are not in the annotation and materially affect how the agent interprets results.

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

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

Every sentence in the description adds value, from purpose to use cases to field semantics to paging behavior. It is front-loaded with the core purpose, then progressively deepens. No wasted words; the length is justified by the tool's complexity.

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?

Combined with the schema and annotations, the description covers all necessary aspects: what it returns, how to filter, how paging works, relation to sibling tools, and key output field interpretation. Given the output schema exists, return values need not be fully spelled out, and the description fills every practical gap an agent would face.

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?

Although schema coverage is 100%, the description adds significant semantics: it explains that limit/offset operate on terminals rather than sailings, that departingTerminalId is optional and sourced from a specific sibling, and that the key output field (driveUpSpaceCount) has meaning. These go well beyond the parameter descriptions to ensure correct invocation and interpretation.

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 opens with a specific verb and resource: 'Returns real-time drive-up and reservable vehicle space available at WSF terminals for upcoming sailings.' It immediately distinguishes itself with concrete use cases ('will I make the ferry?') and links to sibling tools (wsdot_get_ferry_terminals for IDs, wsdot_get_ferry_schedule for arriving terminal IDs), making the purpose 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?

It explicitly states when to use the tool ('Use for "will I make the ferry?" or "how full is the next sailing?" questions'), advises how to obtain the terminal ID via a sibling tool, and clarifies the difference between arrivingTerminalIds and itineraryLabel to avoid misrouting to ferry_schedule. This is clear contextual routing with alternatives named.

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=true, and the description adds meaningful behavioral context: rates are time-banded, change dynamically, and results are paged with a notice reporting the next offset. This goes beyond the annotation safety profile. However, it does not mention error handling or rate limits, but given read-only and output schema exists, the added value is solid.

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 compact (three sentences) and front-loads the primary purpose. The paging explanation is useful, but the 'stateRoute' sentence is tangential and could mislead since it does not appear in the parameter list. Overall efficient, but not perfectly focused.

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 paginated tool with an output schema, the description covers core usage: what data it returns, dynamic nature, and how paging works. It does not explicitly state that repeated calls may be needed to fetch all toll rates, but the notice about next offset implies it. The output schema covers return structure, so no missing critical info.

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 and offset are already described in the schema. The description mentions paging, but the schema already covers defaults and bounds. The odd mention of 'stateRoute' is not a parameter and could confuse, adding no semantic value for the parameters. 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 the tool returns current dynamic toll rates, names the specific WA express lanes and tolled facilities (SR 99, SR 167, I-405, SR 509, SR 520 Bridge). This distinguishes it from siblings like ferry or border tools, which are unrelated. The verb 'returns' and resource are explicit.

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 when to use it (when toll rate data is needed) and provides practical paging guidance. It does not explicitly exclude alternative tools or state when not to use it, but given the distinct sibling types (ferries, passes, cameras), the context is clear enough. No misleading guidance.

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 readOnlyHint=true annotation already signals a safe read operation, so the description does not need to restate that. However, it adds valuable behavioral context: the two-way route filter match, paging behavior with offset/limit and next offset notice, and the congestion criterion (current time > average). This goes beyond annotations and helps an agent use paging correctly.

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 three sentences, each serving a purpose: what it returns, when to use it, and how filtering/paging work. It is front-loaded with the primary purpose and uses examples efficiently. Slightly dense but not verbose, and it avoids repeating schema details.

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 an output schema exists (so return format need not be described) and annotations cover read-only behavior, the description covers all key operational aspects: filtering behavior, paging mechanics, and the congestion definition. No critical information is missing for an agent to correctly call this 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% — every parameter (limit, route, offset) has a thorough description that already explains the route matching modes and paging semantics. The description adds little beyond what the schema already documents, so the baseline of 3 is appropriate; it does not need to compensate for gaps.

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 current vs. average travel times for named WA highway corridors and provides specific route examples (I-5, I-90, SR 520). It uses a specific verb ('returns') and resource, and the scope is unambiguous, easily distinguishing it from sibling tools that handle ferries, borders, or cameras.

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 use cases are given ('how congested is I-5?' or commute time estimates), which clearly indicate when to invoke this tool. It does not explicitly state when not to use it or name alternatives, but the purpose statement is specific enough that an agent can infer the right context, and sibling names make alternative tools obvious.

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, so the read-only nature is known. The description adds valuable behavioral context: position data may lag by 30–60 seconds and many fields are null for non-operating vessels, which helps manage expectations about data freshness and completeness.

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 sentences efficiently pack the return payload, usage guidance, and data caveats. The main functionality is front-loaded, and every sentence earns its place.

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

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

With an output schema and readOnlyHint annotation, the description covers all essential aspects: what is returned, when to use it, and important caveats about data lag and nulls. No parameters means nothing else needs explaining.

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 has 0 parameters, so per the rubric the baseline is 4. The description doesn't need to explain parameters, and no additional parameter-related value is required.

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 ('Returns') and resource ('real-time AIS positions, speed, heading, ETA, and dock status for all active WSF vessels'), clearly distinguishing it from sibling tools like ferry schedules or border waits. It also provides concrete use cases ('where is the ferry now?').

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 explicitly says 'Use for' and lists three clear usage scenarios. It does not mention when not to use or alternatives, but since no sibling tool covers vessel location, this is sufficient context without exclusions.

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

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

Annotations only declare readOnlyHint=true, so the description adds valuable behavioral context: ordering by alertId, pagination with offset/limit and next-offset reporting, and filter matching semantics (full extent, overlap). These are not inferable from annotations or schema. No contradictions. Slightly loses a point for not mentioning anything about error behavior or edge cases, but for a read-only query tool this is adequate.

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 dense sentences, packed with functional details without fluff. It front-loads the primary purpose, then filters, then paging. While it is not minimal, every clause earns its place, and the structure is logical. Slightly long but efficient enough for 4, not quite 5 due to the complexity of 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?

The description covers all necessary aspects for an agent to call this tool correctly: what it returns, all filter options with matching behavior, the ability to fetch all alerts, and pagination instructions. Since an output schema exists, return-value details are not needed. Combined with the rich schema, no critical information is missing. This is complete for a search/query 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 schema descriptions for all 6 parameters are thorough (100% coverage), providing the baseline of 3. The tool description adds extra meaning: for stateRoute it explains natural forms and the prefix-matching rule, and for startMilepost it explains extent-overlap matching. These clarifications go beyond the schema, raising the score to 4. Some param details (e.g., region list) are already in the schema, but the additions are meaningful.

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 verb 'Returns' and the resource 'active WA highway alerts', listing the alert types (incidents, construction, closures, restrictions). It distinguishes itself from sibling tools, which focus on ferries, tolls, mountain passes, etc., by explicitly targeting highway alerts. No ambiguity about what this tool does.

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 explains when to use it: to search for alerts, with optional filters and paging. It states 'Omit all filters to return all current statewide alerts' and explains paging. It doesn't explicitly mention alternatives or when not to use, but the sibling set is obviously distinct (ferry alerts, border waits, etc.), so the usage context is clear. Lacks explicit 'use when' or 'use instead of' guidance, hence 4.

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

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

Beyond the readOnlyHint annotation, the description discloses that camera images are copyrighted and only metadata/URLs are returned, not image bytes. It also reveals ordering by cameraId and pagination behavior (next offset), which are not covered by annotations and add meaningful behavioral context for an agent.

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 concise sentences lead with the core return value, then the copyright caveat, filtering options, and pagination behavior. Every sentence carries distinct information with no fluff, and the most important details are 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?

For a read-only camera search tool with an output schema available, the description covers all essential aspects: what is returned (metadata, image URLs), what is not (image bytes), filtering capabilities, and paging. No critical gaps remain for an agent 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?

The schema already covers all parameters thoroughly (100% coverage), so the baseline is 3. The description adds value by summarizing filter options and giving concrete examples of accepted route formats ('I-90', '90', 'SR 520') and by explaining the next-offset pagination mechanic, which is not in the schema. This enriches understanding without redundancy.

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 opens with a specific verb ('Returns') and a precise resource ('WSDOT highway camera locations, descriptions, and image URLs'), immediately clarifying the tool's scope. It clearly distinguishes itself from sibling tools (ferry, toll, alerts) by focusing on cameras, and the mention of filtering by route/region/milepost confirms its search purpose.

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 explicit guidance on how to filter (by state route, region, or milepost range) and how to page through results (offset/limit, next offset notice). It does not explicitly state when not to use this tool versus alternatives, but given the sibling set is thematically distinct (ferries, tolls, etc.), the usage context is clear enough.

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