LaneRouter

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: the fixed status vocabulary an agent may receive (including 'wall' meaning agents blocked) and the path-normalization rule that IDs in paths are ignored. It omits what happens when no reports exist for a target.

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, zero waste: purpose and status vocabulary first, usage condition second, with the normalization caveat appended compactly. Fully 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 simple two-parameter read tool with no output schema, the enumerated status values effectively stand in for return-value documentation. The remaining gap is edge-case behavior — empty results, report freshness, or whether conditions are keyed per action — which an agent would need to know but can likely discover from the response.

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

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

Schema description coverage is 100%, so both parameters are already documented with examples, setting the baseline at 3. The description adds one useful rule beyond the schema — 'IDs in paths are ignored' — which clarifies matching/normalization, but does not explain how the optional 'action' verb affects lookups.

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 ('check') and resource ('live conditions reported by other agents') and enumerates the exact status vocabulary: clear, slow, rate_limited, wall, changed, broken, plus working detours. This makes it unambiguously the read counterpart to report_road among the 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?

Gives a clear triggering condition: run it 'before acting on a website or API.' That is strong pre-flight guidance, but it names no explicit alternative (e.g., report_road for submitting a condition, watch_road for ongoing monitoring) and gives no when-not 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 annotations already state readOnlyHint=true and openWorldHint=false, so the safety profile is covered. With no output schema, the description takes on the job of describing what comes back, and it does so by naming current light and last delivery. It doesn't cover pagination or the empty case, so it stops short of full transparency.

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 sentence, front-loaded with the verb and scope, with every clause carrying information (resource, key scoping, returned fields). Nothing is redundant or 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?

For a zero-parameter read-only list tool with no output schema, the description gives enough for an agent to choose and call it: what is listed, what scoping applies, and what each entry contains. Only the handling of empty results or volume limits is unaddressed.

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

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

The tool takes no parameters, so there is nothing for the description to explain and the baseline of 4 applies. The description correctly doesn't waste words on nonexistent inputs.

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 ("List") and a specific resource ("the roads this key watches") and even names the two values returned, current light and last delivery. It is clearly distinct from the mutating siblings watch_road and unwatch_road, though it doesn't explicitly contrast itself with check_road or red_lights.

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 roads this key watches" implies that this lists only watched roads, not all roads; that scoping is the only usage guidance. There's no explicit when-to-use or when-to-use-instead guidance, and nothing steers an agent to check_road or red_lights for other questions.

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=false, so safety and data-source locality are covered. The description adds that results reflect 'right now' state and the inclusion criterion (agent blocked OR service broken), but says nothing about snapshot freshness, how often it updates, or result shape.

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

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

A single sentence that front-loads the resource and scope, with the usage rationale as a compact trailing clause. No wasted wording.

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-parameter, read-only list tool with no output schema, the description conveys what is returned in domain terms (roads, with the reason for inclusion). It would be slightly stronger if it hinted at the result fields or the freshness of 'currently'.

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 no parameter semantics to explain and the baseline of 4 applies. The description correctly implies the call is unfiltered and takes no arguments.

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 ('List') and a precisely scoped resource ('roads where agents are currently blocked or the service is broken'), which is far clearer than the opaque tool name 'red_lights'. It does not, however, explicitly contrast itself with siblings like check_road or list_watches, so the agent must infer the boundary.

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 trailing clause 'so you can plan around them' implies the situational use case (pre-planning around outages), which is helpful context. It stops short of stating when to prefer this over check_road for a single road, or any 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?

Beyond the annotations (which only flag it as non-read-only and non-idempotent), it discloses the data-handling rule (no page content, personal data, or credentials) and the acceptance boundary for detours. It doesn't state that reports are shared/persisted for other agents beyond a brief 'so the next agent knows'.

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 front-loaded sentences: purpose, privacy constraint, then detour rule. No filler, and the constraint ordering matches how an agent would reason about what to submit.

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 7-parameter write tool with a nested object and no output schema, it covers purpose, safety, and the trickiest decision (detour legitimacy). The omission of three optional telemetry fields is minor since the schema documents them.

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 57%. The description adds meaningful guidance on the detour object (what counts as legitimate) but says nothing about action, framework, latency_ms, or http_status, and leaves the outcome enum values 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: 'report the outcome' after acting, so the next agent benefits. It implicitly contrasts with siblings like check_road (pre-action) and watch_road, though it never names them 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?

Timing is clear ('After acting'), and it specifies when to include a detour and what kinds are acceptable. It does not explicitly route to or away from sibling tools by name, 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 already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that structured data — it does not say whether deletion is immediate or reversible, whether a non-existent id errors or is silently ignored (relevant despite idempotency), or whether any notification/confirmation follows.

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 short, front-loaded sentence with no filler. It is efficient but borders on under-specification rather than being genuinely concise, since the single clause is all the information provided.

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?

This is a destructive mutation with no output schema, no parameter documentation, and no usage context. The description should at minimum identify the source of the id and confirm the deletion's effect; neither is present, so an agent cannot call it confidently without inspecting sibling schemas.

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 0% for the single required parameter, so the description carries the burden and only offers "by id". It never clarifies whether this id is a watch identifier (from list_watches) or a road identifier as watch_road likely takes, which is a meaningful distinction against the sibling tools.

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

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

The description gives a specific verb and resource ("Delete a watch") plus the keying parameter ("by id"), which is more than the bare title repeats. However, it never distinguishes the operation from the sibling watch_road (its inverse) or list_watches, and it shifts vocabulary from "road" in the tool name/title to "watch" here, leaving the agent to infer the relationship.

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 no when-to-use guidance at all: no mention of how a watch id is obtained (presumably from list_watches), no note that this is the inverse of watch_road, and no statement about what happens if the id does not exist. The agent must infer the entire workflow from sibling names.

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 annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false), the description discloses the auth requirement, the return shape (watch id plus signing secret), and critically that the secret is 'shown once' and used to verify the LaneRouter-Signature header — operationally important, irreversible-to-recover information. It does not explain repeat-call behavior on an already-watched target, which is the main remaining gap given the non-idempotent hint.

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 outcome, then the prerequisite, then the return contract. Every clause carries information an agent needs; nothing is 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 non-idempotent write tool with no output schema, the description covers the essentials: what it produces, the credential needed, and the one-time secret that governs downstream signature verification. Only the lifecycle counterpart (unwatch_road / duplicate-watch handling) is left unstated.

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 defines target, url, and action; the description adds little beyond echoing that a road is watched and a webhook is signed. The optional 'action' filter is not mentioned at all in the description, so no extra meaning is layered on top of 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?

The description gives a specific verb and outcome — 'Get a signed webhook when a road changes light (green, amber, red)' — which clearly frames this as creating a persistent change subscription rather than a one-off query. It implicitly separates itself from check_road and list_watches, but never names a sibling, so the differentiation is left to inference.

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

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

Usage is only implied: the tool is for ongoing notification on a watched target, and the auth prerequisite ('Needs a LaneRouter key') is stated. There is no explicit when-to-use versus check_road (one-off status) or unwatch_road (teardown), and no guidance on what to do if a watch already exists on the same target.

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