mq-bridge

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

Annotations only declare readOnlyHint=true; the description adds substantial behavior beyond that — error text of other processes is redacted to `error`, the entry with `pid` == `current_pid` is this server, and other processes' routes cannot be stopped from here. This is exactly the kind of operational context an agent needs and cannot infer from the annotations.

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

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

Front-loaded with the core scope statement, followed by two short, high-signal sentences. The middle enumeration of returned fields is dense and list-like, but each named field earns its place given the absence of an 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, the description compensates by naming the fields returned per process and clarifying identity (`current_pid`) and the redaction behavior. Combined with the read-only note, an agent has everything needed to call and interpret 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?

The tool takes zero parameters, so the schema carries no semantics and the baseline is 4. The description instead documents the returned shape (`outcome`, `throughput`, `average_throughput`, `message_sequence`, `pending`, `started_at_ms`, `pid`), which adds meaning but sits outside the parameter dimension.

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

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

States a specific verb+resource with clear scope: reports every mq-bridge process running for this user on this machine, explicitly enumerating CLI jobs, other MCP servers, the web UI and the desktop app. This distinguishes it from siblings like list_routes and route_status, which operate on routes rather than whole processes.

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

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

Gives clear context for when this tool is the right one (cross-process inventory, including other MCP servers) and states a key exclusion: routes of other processes cannot be stopped from here, implicitly routing the agent to stop_route for its own routes. It does not, however, explicitly name the sibling tools or spell out the when-not 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 declare readOnlyHint=true, so safety is covered. The description goes further by detailing the shape of the payload (endpoint type, URI form, example, typed params, config fields, middleware params) and the CLI equivalence, which is meaningful behavioral context beyond the annotation.

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

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

Front-loaded with the core purpose, then a single closing sentence on the parameter. The middle clause enumerating returned fields is dense but earns its place since there is no 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, the description must carry the return-value burden, and it does so by enumerating the fields returned for each endpoint and middleware. Combined with the 100%-covered parameter and readOnly annotation, an agent has enough 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?

Schema coverage is 100% and the schema description already explains that name accepts a scheme, alias, endpoint type or middleware and that omission returns the whole catalog. The description only adds the 'narrow to one entry' framing, so it stays at the baseline of 3 when the schema does the heavy lifting.

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

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

The generic name 'describe' is rescued by the description, which states a specific resource: the endpoints and middlewares this build supports. It implicitly distinguishes itself from siblings like list_routes/server_info by framing itself as a catalog of available endpoint types and middleware, though it never names an alternative explicitly.

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

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

The description gives parameter-level usage ('Pass name to narrow it to one entry', 'Omit it for the whole catalog'), which implies the two modes of use. However, it never states when to prefer this over siblings such as list_routes or server_info, so the when-to-use guidance is only inferred.

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 substantial context: the command embeds canonical JSON with POSIX shell quoting to preserve fields lacking a copy-URI form, credential values become environment variable placeholders, and the required variable names are returned separately. This is meaningful behavior beyond the safety annotation, though the exact return shape is only implied.

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

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

Three sentences, front-loaded with the core action and followed by the differentiator and the credential/quoting behavior. Every sentence carries weight; only marginally more could be trimmed.

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 generator with no output schema, the description covers the essentials: what it produces, that it does not execute, and how credentials and non-URI-representable fields are handled. It conveys that variable names come back separately, which is the key return-value nuance, though a fuller picture of the returned command/variables would make it 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 description coverage is 100%, so the schema already documents `name`, `route`, `batch_size`, and `concurrency`. The description ties the `route` parameter to `start_route`'s input and alludes to 'tuning overrides', but adds little syntax or meaning beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb (Generate) and resource (a copyable, headless `mqb` command for a route), and explicitly distinguishes itself from the sibling `start_route` by noting it 'does not start anything'. An agent can tell it apart from start_route and the other lifecycle tools without opening any 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?

Clearly frames usage relative to `start_route`: it accepts the same route JSON and tuning overrides but produces a command instead of running one. This gives the agent the selecting condition, though it stops short of stating explicit when-to-use/when-not scenarios or other 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?

The readOnlyHint annotation already establishes that this is a safe, non-mutating operation, so the bar is lower. The description adds useful content context (connection health, message totals, current and average rates), but discloses nothing about freshness of the live metrics, whether routes from other servers are excluded, or any rate/pagination behavior.

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

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

A single front-loaded sentence with a clear verb-resource opening and no redundant or filler content. Every clause adds information about what is returned.

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

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

With no output schema, the description carries the burden of describing the response, and it does so by naming the four metric families returned. It is nearly complete for a zero-parameter read-only tool, though it omits whether results are paginated or scoped beyond the implied current server.

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 per the rubric the baseline is 4 and there is no parameter semantics for the description to compensate for. The schema is empty and fully self-explanatory.

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

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

States a specific verb and resource ('List the routes') plus a scope qualifier ('started by this server'), and enumerates the returned metrics. It never names or contrasts with the closely related sibling route_status, so an agent must infer the distinction between listing all routes and querying one route's status.

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 explicit when-to-use guidance and no mention of alternatives such as route_status, wait_route, or route_messages. The enumeration use case is only weakly implied by the verb 'List'; nothing tells the agent when this is preferable to the sibling status 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?

No annotations are provided, so the description carries the burden. It usefully discloses the return behavior ('Returns the send outcome (an acknowledgement, or the endpoint's reply for request/reply endpoints)') and that the target is inline and route-independent. It says nothing about failure modes, permissions, or side effects of publishing.

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

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

Four sentences, front-loaded with the core action, then the endpoint shape, the message/messages choice, and the return value. Reasonably tight with no filler, though the parenthetical example is somewhat long.

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-parameter publish tool with no output schema and no annotations, the description covers purpose, the inline publisher format, the message vs messages choice, and the return value. It omits error/failure behavior, which is a minor gap rather than a blocking one.

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

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

Schema description coverage is 100%, so the schema already documents `publisher`, `message`/`messages`, and the payload/metadata fields. The description restates the `publisher` shape with an example and the message/metadata conventions that the schema's InputMessage and Endpoint defs already provide, adding little beyond the schema.

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

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

States a specific verb ('Publish') and resource ('one message or a batch of messages to any endpoint'), and the phrase 'independent of routes' implicitly distinguishes it from the route-based sibling route_messages. It stops short of naming that sibling explicitly, so the differentiation is suggestive rather than 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?

It gives parameter-level usage ('Provide either `message` or `messages`') and notes the endpoint is independent of routes, which implies a context. But it never states when to choose this tool over route_messages or the other siblings, so usage is only implied.

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

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

Annotations already declare destructiveHint=true/readOnlyHint=false, but the description explains the mechanism behind that: each message is returned once and repeated calls yield only newly arrived messages. This is exactly the behavioral context annotations cannot convey, and it matches the annotations rather than contradicting them.

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

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

Three sentences, zero filler, and the ordering plus capture precondition are front-loaded before the destructive-read caveat. Every sentence carries distinct 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?

With no output schema, the description still discloses return ordering ('newest last') and the once-only return semantics, which is what an agent most needs here. Safety profile is covered by annotations and reinforced coherently by the text.

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?

One parameter with 100% schema description coverage ('The route name.'), so the schema already carries the meaning. The description adds no syntax or format detail for the name parameter; baseline 3 is appropriate.

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

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

States a specific verb and resource ('Return the most recent messages captured on a route') plus ordering ('newest last'), and the capture_last constraint scopes it away from status/list style siblings. An agent can tell what it fetches without opening the schema.

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

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

Explains the precondition for any result ('Only routes started with capture_last capture anything') and warns that reads are one-shot, which strongly shapes when to call it. It does not name alternative tools (e.g. list_routes, route_status), so it stops short of explicit 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?

With only readOnlyHint=true in annotations, the description adds meaningful behavioral context beyond safety: it specifies which metrics are returned (connection health, completion, message count, current rate, average rate) and warns that the current rate decays to ~0 after a route stops moving data, which is crucial for interpreting results correctly. It does not cover auth or rate limits, but the added output semantics are valuable.

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 purpose and then efficiently details the returned metrics, followed by a single practical caveat. Every clause earns its place, especially since there is no output schema to convey return values elsewhere.

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 status tool with one fully documented optional parameter, no output schema, and only a readOnlyHint annotation, the description is complete enough for an agent to invoke it correctly and interpret the response. It covers scope, returned fields, and a key interpretation caveat, leaving no critical 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 coverage is 100%, and the single optional `name` parameter is fully documented in the schema ('omit to report every running route'). The description restates that omitting the name reports all routes but adds no new syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Report the live status of one route ... or all routes') and enumerates the exact status fields, which clearly differentiates it from siblings like list_routes (listing) and stop_route/start_route (control). An agent can identify this as the read-only status-reporting tool without inspecting other 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 gives clear context for use: retrieve live status, either for one named route or all routes, and it includes interpretation guidance ('Quote the average for a finished job'). It does not explicitly name alternatives or exclude when-not-to-use, so it falls short of full routing 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?

Beyond the annotations, the description provides deep behavioral context by detailing the exact elements reported: version, profile, build time, and crucially, the specific logic for the git_hash (including the '-dirty' suffix condition).

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 definition is highly concise, front-loading the main purpose and then efficiently detailing the specifics of the output in a clear, structured manner.

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?

Although there is no output schema, the description is perfectly complete by explicitly listing every piece of data returned and defining the logic behind that data (e.g., the conditional nature of the git_hash).

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?

Since the tool has zero parameters and the schema coverage is 100%, the description meets the baseline score for input parameter semantics.

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

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

The description uses a clear verb ('Report') and identifies a specific resource ('MCP server's build identity'). It is distinct from its siblings, which are primarily operational or routing tools.

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

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

The description provides explicit guidance on when to use the tool ('to confirm which binary is actually running before trusting throughput numbers'). While it doesn't compare it to a sibling, the defined use case is highly specific.

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=false` and `destructiveHint=true`, so the writing nature of the tool is covered by structured data. The description adds useful behavior: the route runs continuously until stopped unless `exit_on_empty` is set, and it returns the tuning that took effect. It stops short of disclosing startup failure modes, connection requirements, or what happens to existing routes of the same name.

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 dense paragraph that front-loads the core action before the option/middleware detail. Every sentence carries information, though the middleware enumeration and the worked example make it longer than strictly needed for selection.

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

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

No output schema exists, yet the description covers the return value (route name plus the effective tuning). For a 5-parameter tool with deeply nested endpoint configs it is nearly complete, with the only real gap being the `capture_last` parameter, which is left entirely to the schema.

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 schema carries the per-field detail, but the description still adds the cross-field rule (top-level `concurrency`/`batch_size` wins over the in-`route` value, and an unset value becomes the app default 4/1024). It also enumerates the middleware set inline, which helps the agent compose a valid endpoint without drilling into `$defs`.

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 pair ('Create and run a route') and immediately scopes it as moving messages from an `input` endpoint to an `output` endpoint. It distinguishes itself from the stop/status siblings by describing the creation-and-run action and returning the route name for use with `wait_route` / `route_status` / `stop_route`.

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 lifecycle context: it names the follow-up tools that consume the returned route name, and explains `exit_on_empty` as the toggle between drain-and-exit and continuous operation. It does not, however, state when to prefer this over siblings like `publish` or `generate_cli_command`, and offers no explicit 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?

No annotations are supplied, so the description carries the full behavioral burden. It usefully discloses the return payload (total messages moved, average_messages_per_second over elapsed_s), which compensates somewhat for the missing output schema, but says nothing about behavior when the route is not running, idempotency, or error/permission conditions.

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 tight sentences with zero filler; the operation is front-loaded and the return semantics follow immediately. Every clause 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 no output schema, the description steps in to describe the return values, and the single parameter is fully covered by the schema. Only failure modes and preconditions (e.g., what happens if the route is already stopped) are left 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?

There is a single parameter with 100% schema description coverage ('The route name'), so the schema already documents it. The description adds no format, uniqueness, or naming-convention detail beyond 'by `name`', making the baseline 3 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 states a specific verb+resource ('Stop a running route') and names the identifying parameter (`name`), which is unambiguous against siblings like list_routes or route_status. It does not explicitly contrast itself with start_route, but the operation is self-evident.

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

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

Usage is implied by 'a running route' — the agent can infer this applies only to an active route, and start_route is the obvious counterpart. However, no explicit when-to-use/when-not-to-use guidance or named alternative is provided.

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, so the description carries the rest and does so well: the route is left running on timeout, `finished: false` signals the timeout case, and a `failed` outcome carries the cause in `error`. It also discloses the blocking semantics and timeout limits, which are behavioral traits beyond the safety 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?

Four dense, front-loaded sentences with no filler; the core behavior and the sibling routing come first. The final sentence restating the timeout default/maximum duplicates schema content and is the one slightly redundant line.

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

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

There is no output schema, so the description takes on the return-value burden and covers it: `finished`, `outcome`, messages moved, rate achieved, and error propagation. Combined with the timeout semantics, an agent has everything needed to call and interpret this correctly.

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

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

Schema coverage is 100%, and the timeout default, clamp, and 'route keeps running' semantics are already documented in the schema's own parameter description. The description largely repeats that, though it does tie `timeout_ms` to the returned `finished: false`. Baseline 3 is appropriate.

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

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

States a specific verb and resource — block until a route finishes, then report the outcome — and explicitly distinguishes itself from the polling sibling `route_status`. An agent can pick this over `route_status` without opening either schema.

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

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

Gives an explicit when-to-use ('a job started with `exit_on_empty`') and a named alternative to avoid ('instead of polling `route_status`'), plus the rationale (one tool call regardless of duration). Nothing is left to inference.

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