agent-bus

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, which fully cover the safety and side-effect profile. The description adds valuable context beyond annotations by specifying the topics covered (routing, pricing, base URLs) and the protocols (OpenAI, Anthropic, Codex). It does not contradict any annotation and provides behavioral clarity about what the tool returns conceptually.

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 a single sentence that packs a lot of information: the tool's essence, three topics (routing, pricing, base URLs), and three protocols. It is front-loaded with 'What Flow AI is' and then expands. No redundant words. It could be slightly more structured (e.g., listing topics) but is appropriately concise for its 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?

For an informational tool with no parameters and no output schema, the description is sufficiently complete to inform an agent what to expect. It covers the key areas an agent would need to know. However, it does not explicitly state the return format (e.g., 'returns a text explanation' or 'returns a summary'), which could be assumed but is not stated. Given the simplicity, this is a minor gap.

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

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

There are zero parameters, so schema description coverage is 100% vacuously. The description correctly focuses on the tool's content rather than parameters. With no parameters to document, a baseline score of 4 is appropriate per the rubric.

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: explaining what Flow AI is, how routing and pass-through pricing work, and how to point an agent or SDK at it (base URLs for three protocols). This is a specific verb-resource pair ('about') and content list, and it distinguishes itself from the sibling operational tools (bus_*, list_free_models, etc.) which are clearly action-oriented. An agent can immediately tell this is an informational/reference tool.

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 what content is provided but does not explicitly state when to use this tool versus alternatives. There is no guidance on when to call it (e.g., 'before using other Flow AI tools' or 'when you need base URLs'). The name and content imply it is for orientation, but the description doesn't make the usage context explicit.

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 tell the agent this is an idempotent, non-destructive mutation. The description adds the crucial non-obvious behavior: ack does NOT free the mailbox when a reply is expected, nothing new arrives until bus_reply/nack, and slot_released reveals which case applies. This is exactly the kind of trap the annotations cannot express.

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 core definition is front-loaded in the first sentence, and the CAUTION and final:true guidance follow in logical order. It is dense and slightly long, but nearly every clause conveys a distinct behavioral rule rather than 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?

An output schema exists so return values need not be enumerated, yet the description still calls out the slot_released field that governs the ack-vs-reply decision. For a tool with subtle mailbox-state semantics and low schema coverage, this is essentially 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 only 25% (just 'final'), so the description must carry the load and largely does: it explains where message_id and lease_id come from (bus_inbox's messages[0]) and what final:true does behaviorally. The 'as' parameter remains undocumented in both places, leaving one 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 precise verb+resource ('acknowledge durable receipt of a leased message') and immediately differentiates from the sibling that does the opposite ('WITHOUT replying'). An agent can distinguish it from bus_reply and bus_nack 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?

Explicit when/when-not guidance: use ack when no reply is due, use bus_reply/bus_nack when a reply is expected, and pass final:true for announcements. It even closes the loop with 'a reply implies ack, so you don't need both,' eliminating a common mistake.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds some useful context by specifying the output fields and the address format 'agent://project/name', but it does not disclose filtering behavior or any additional side effects beyond what annotations cover.

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 short, front-loaded with the tool's purpose, and every clause adds value. The address format example is a useful clarification that avoids potential misuse without adding verbosity.

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 simple read-only directory tool with one optional parameter, complete annotations, and no required arguments. The description conveys what the tool returns and the address format, which is sufficient for an agent to invoke it correctly; the only gap is explicit sibling differentiation.

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 has 100% description coverage for the only parameter, 'query', which is already documented as an optional substring filter. The description adds no additional parameter-level semantics, so the baseline score 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 clearly identifies the resource ('directory of your agents') and the key fields returned (address, harness, machine, status). It does not use an explicit verb like 'list', and it does not explicitly differentiate itself from sibling bus_* tools, so it falls short of a 5.

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 purpose implies this is the tool to consult when you need to see your agents on the bus, but there is no explicit guidance about when to use it versus related tools like bus_check, bus_me, or bus_inbox. No alternatives or exclusions are mentioned.

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 destructive, read-only, and idempotent behavior. The description adds the 'returns its final status' behavior and the leased/replied restriction, providing context beyond the annotations. It is consistent with the annotations and adds value while remaining concise.

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 sentences long, front-loaded with the primary purpose and the key restriction, and ends with the return value. Every sentence justifies its place; no extra wording is present.

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 core behavior is described, but the 'as' parameter is undocumented and the exact meaning of 'final status' is unspecified (e.g., what statuses can be returned, how failures are surfaced). Since output schema is absent, that responsibility falls on the description. Overall it is adequate but incomplete for an agent to fully predict the tool's side effects and outputs.

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%. The description implicitly refers to message_id as the target message ('Cancel my queued message') but never names or explains the parameter. More importantly, the 'as' parameter is entirely unexplained and its role is ambiguous. With zero schema coverage, the description should compensate by explicitly tying parameters to the operation, which it fails to do.

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 operation: withdrawing a message you sent that is still queued, with an explicit state condition ('not yet leased'). It distinguishes from siblings like bus_ack and bus_send because it uniquely targets queued unleased messages and says so directly.

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

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

It gives an explicit condition for use: only for messages that are still queued and not yet leased, and explicitly excludes messages already leased or replied. It doesn't name specific alternative tools (e.g., bus_nack for leased messages), but the boundary conditions alone are sufficient for an agent to select this tool correctly for the described scenario.

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 readOnly and idempotent, and the description adds valuable behavioral detail: the full status lifecycle, terminal:true meaning stop waiting, and reply_declined:true meaning the recipient closed without answering. This goes well beyond what structured annotations provide and helps an agent decide whether to keep polling.

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, front-loaded with the status list, and uses two sentences to define the crucial terminal and reply_declined flags. Every phrase 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 single-parameter read-only status tool with an output schema and safety annotations, the description covers the needed context: what statuses to expect, what the reply field is, and what terminal:true means for stopping. No critical information for correct invocation 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?

The schema only provides message_id as a required string, so the description carries the semantic burden. The phrase 'message you sent' clarifies that the ID must refer to a message the caller originated, which is useful context beyond the raw parameter name. It could be more explicit about where the message_id comes from (e.g., bus_send), but it is still reasonably clear.

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: checking the status of a message you sent. It enumerates the exact status values (queued, leased, delivered, replied, dead_letter, expired, cancelled) and mentions the reply once it exists, making the tool's scope clear and distinct from sibling send/reply/ack/cancel 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 phrase 'a message you sent' gives clear context: this tool is for checking messages you originated rather than received ones. It does not explicitly name alternatives like bus_inbox or bus_history, but the sent-message framing provides enough guidance for a competent agent.

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 safety profile (readOnly=false, idempotent=true, destructive=false, openWorld=true), but the description adds real behavioral context beyond them: it never takes a lease, never steals a live message, and that empty string clears a field. The clear-value semantics and lease-safety guarantee are not derivable from the annotations.

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

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

Two dense sentences, front-loaded with the primary action and the key differentiator. The parenthetical slash-list of webhook fields is compact but slightly cramped; nothing is wasted.

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

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

For a 9-parameter tool with a nested object and no output schema, the description conveys the core behavior and the anti-lease guarantee but leaves six parameters semantically undocumented and never states defaults or what happens when no fields are supplied. Adequate but with clear 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 only 33% (3 of 9 params documented), so the description must compensate, and it partially does by naming accept_from, harness, and the webhook_* trio plus the '"" to clear' convention. It omits meaning for 'as', 'machine', 'session_ref', and 'accept_wake_from' (including the ["*"] default), so half the surface remains unexplained.

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 ('change your OWN mailbox settings'), names the concrete fields it touches, and explicitly distinguishes itself from the sibling bus_inbox by the no-lease constraint. An agent can pick this over bus_inbox 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?

The contrast with bus_inbox ('Same fields as bus_inbox's settings, but this tool can never take a lease, so configuring never steals a live message') gives a clear condition for choosing this tool over the alternative. It lacks an explicit 'use this when / not when' phrasing but the routing logic is unambiguous.

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 annotations already declaring the tool readOnly, idempotent, and non-destructive, the description adds valuable behavior: it reports account-level health indicators, including latency and stuck mailboxes. This goes beyond the annotation by clarifying the nature of the returned diagnostic. It does not mention aggregation windows or refresh semantics, but those are not critical for a safe read tool with an output schema.

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

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

Two front-loaded sentences: the first names the resource and the exact health aspects, and the second provides the usage situation. No filler, and the em-dashed list is readable. The description earns its length.

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 diagnostic with an output schema present, the description gives enough for the agent to decide when to call the tool and what it will receive. The specific metrics, the account scoping, and the 'before blaming a peer' cue make the tool callable correctly even without seeing the output 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?

The input schema has zero parameters, so there is no parameter ambiguity. The description appropriately narrows the scope to 'your ACCOUNT' rather than a specific queue, mailbox, or agent, which is meaningful given zero parameters but not a burden on the text.

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 identifies this as a health-check for the whole account and enumerates concrete metrics: median reply latency, live listeners, push coverage, stuck mailboxes, volume. This distinguishes it from sibling tools that send, reply, or manage bus items, though it relies on the title 'health' rather than an explicit verb like 'check' or 'get'.

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 a clear use-case: 'the diagnostic an orchestrator needs before blaming a peer.' This tells the agent when to consult the tool relative to debugging activity, and implies when not to use it (e.g., not when sending or mutating). It does not name alternative tools explicitly, so it misses the full 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: bodies are bounded by a 30-day retention window, dead-lettered mail is included in results, and owner keys expose the whole account. It does not mention pagination stability or rate limits, but the added retention/scope context is substantive.

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 dense sentences with the core resource claim front-loaded before filtering/paging mechanics. Every clause carries information (scope, retention, filters, cursor chaining). It is slightly compressed to the point of terse, but there is 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?

Output schema exists, so return shape need not be described, and annotations cover safety. The description is still missing explicit routing against the large bus_* sibling family and never clarifies the untitled `as` parameter, which for a 7-parameter tool leaves real 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 only 57%, and the description compensates by mapping with→peer, trace_id→thread, and status, plus explaining the before-cursor chain ('before = the previous page's next_before'). The `as` parameter remains unexplained in both schema and description, which is the notable remaining 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 resource and scope: 'your past mail — sent or received (owner keys: the whole account), bodies within the 30-day retention, dead letters included.' An agent can tell this is a historical listing over sent AND received mail, not a live inbox. It stops short of naming sibling tools like bus_inbox or bus_check, so the reader must infer the boundary themselves.

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 in-tool usage guidance — 'Filter by peer (with), thread (trace_id), status; page with before = the previous page's next_before' — which tells the agent how to narrow and page results. However, it never says when to choose bus_history over bus_inbox, bus_check, or bus_replay despite 25 sibling tools, so tool selection is left to inference.

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

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

Annotations only cover the safety profile (readOnly=false, idempotent=false, destructive=false, openWorld=true). The description adds the lease lifecycle - single-flight FIFO, expiry-and-re-offer on crash, settle-before-next - and the critical wait_s blocking caveat that holds the model turn open for up to 25s. This is rich behavioral context well beyond structured data.

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?

Core purpose and the lease constraint are front-loaded in the first sentence. The wait_s blocking behavior is echoed in both the body and the closing NOTE, and the URL/onboard reference adds density, so it is slightly redundant for its size though each clause carries real operational 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?

With an output schema present, return values need no explanation, and the description still covers the full lifecycle (claim, settle, expiry, wake paths, blocking vs non-blocking invocation). For a 10-parameter, nested-object, open-world tool with a lease state machine, nothing critical to correct invocation 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 baseline is 3, but the description adds cross-parameter meaning the schema scopes locally: wait_s long-poll semantics and its side effect on the model turn, and the doorbell/session flow that governs harness and webhook_url. It stops short of restating the per-parameter syntax, which is already thorough in the schema.

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

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

States a precise verb and resource: 'claim the next message addressed to you as a LEASE (at most one at a time, strict FIFO)'. It explicitly names the sibling tools used to settle (bus_reply, bus_ack), so an agent can distinguish it from them 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 explicit when-to-call guidance ('when the doorbell rings, or at task boundaries'), names the settling alternatives (bus_reply/bus_ack), and prescribes alternatives for terminal sessions (run the doorbell) and per-invocation agents (webhook/sidecar instead of a blocking MCP call). When-not and substitution paths are all present.

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

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

Annotations cover safety (readOnly false, destructive false, non-idempotent), and the description adds real context beyond them: single-use semantics, default 1 use / 24h validity, and the fact that the code is relayable by a human without exposing a key. It does not discuss revocation, reuse-after-max_uses behavior, or what happens if the same key mints repeatedly.

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: the action and its counterpart sibling come first, then the security rationale, then key scoping and defaults. No filler, no restated title, and the most decision-relevant fact (code vs key) 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?

An output schema exists, so return details (expires_at echo) need not be described, and the schema already bounds ttl_s and max_uses. What remains thin is error/edge guidance and explicit negative routing against the other bus_* minting siblings.

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 already 100%, so the baseline is 3; the description nevertheless adds meaning by explaining that a bus key silently scopes the invite to its own project while an owner key must name it. The 'Default 1 use, 24h' phrase merely restates the schema defaults, adding no new information.

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?

Names a specific verb (mint) and resource (one-time INVITE CODE) and immediately ties it to the counterpart sibling bus_join, so an agent can distinguish inviting from joining. It also draws the boundary against key-minting by stating 'a code is not a key.'

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 condition that selects this tool (a new teammate needs to join by itself) and points to bus_join as the receiving side. It also gives the key-type rule for who supplies project, but never explicitly says when NOT to use it (e.g., use bus_mint for a durable key instead).

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 non-read-only, non-idempotent, non-destructive, closed-world, but do not cover the key lifecycle. The description adds genuinely new behavior: you receive your own bound key on their account, shown once (a secret that cannot be re-read), which is important for correct handling. It stops short of noting failure modes for invalid/expired codes.

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

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

Three short sentences, front-loaded with the core action, then the provenance of the code, then the required activation step. 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?

An output schema exists so return values need no explanation, and the description still covers the key state, the no-key precondition, and the required follow-up call. Nothing essential for correct invocation 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 both parameters are already documented in the schema ('the bj-… code from bus_invite', 'your name inside the team'), which is effectively what the description echoes. Baseline 3 is appropriate; no syntax or format detail is added 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 (join) and resource (existing team via invite code), and explicitly contrasts with the sibling that creates the code (bus_invite). An agent can distinguish this from bus_mint/bus_signup 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?

Specifies the precondition (a teammate made the code with bus_invite), the condition (join an EXISTING team, no key needed), and the follow-up action (bus_configure with harness and accept_from). This is full when/when-not/next-step 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 description adds notable behavioral details beyond annotations: 'Every action is audited; deleting content leaves a tombstone, never erases' clarifies the destructive behavior, and 'set_notify verifies the webhook with one ping before saving it' plus 'new key shown once' for rotate_key provide operational context. These enrich the annotation's destructiveHint=true and idempotentHint=true without 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?

The description is compact and front-loaded with the purpose, then presents actions in a pipe-separated list. It avoids redundancy and is easy to scan, though the density of the list could be improved with line breaks or grouping, but overall it 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?

Given the tool's complexity (8 params, nested objects, no output schema), the description provides a solid foundation but leaves gaps: it doesn't explain what 'harness' is, what the return value looks like, or how webhook_headers are structured beyond being an object. It also doesn't mention pagination or response formats, which an agent might need.

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 carries the full burden for parameter meaning. It lists each action with its arguments (e.g., 'address or *', 'accept_from[]', 'message_ids[]'), and adds semantic info like 'new key shown once' for rotate_key. However, some parameters like 'harness' remain undefined, and enum values for webhook_format are not explained, so it's not fully complete.

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 manages account agents, calling it the 'owner/self-service surface,' and enumerates specific sub-actions (remove_agent, set_accept_from, etc.) with their parameters. This establishes a specific verb+resource and differentiates it enough from sibling bus_* tools, though it doesn't 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?

It implies usage context ('owner/self-service surface') and hints that it's for managing your own agents, but it does not explicitly state when not to use this tool or contrast it with siblings like bus_agents or bus_configure. The guidance is implicit rather than explicit.

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 safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral content beyond them: the mailbox is self-scoped, unread depth is reported, and notably whether a held lease blocks your mailbox — a diagnostic insight an agent could not infer from structured fields.

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 sentence front-loads the core action and scoping, then a short second sentence carries the routing trigger. Every clause (accept_from, queue depth, lease blocking, webhook state) contributes distinct information with no filler.

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

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

An output schema exists, so return values need not be re-explained, and the description still summarizes them usefully. For a zero-required-param diagnostic read tool the coverage is essentially complete; only the meaning of the optional 'as' override 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?

One optional parameter with 100% schema description coverage ('your address (unbound keys only)'), so the schema already carries the semantics. The description adds nothing about the 'as' parameter, making the baseline 3 correct.

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 (inspect) and resource (your OWN mailbox) and enumerates what is exposed: accept_from, unread queue depth, held lease, webhook state. The 'OWN' qualifier implicitly separates it from message-reading siblings like bus_inbox, but no sibling is named explicitly, so it falls just short of a 5.

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?

'Call this FIRST when the bus seems stuck' gives an explicit trigger condition for use. It stops short of naming an alternative diagnostic (e.g. bus_health) or stating when not to use it, but the entry-point guidance is clear and actionable.

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 critical behavioral traits beyond annotations: each key is shown only once, keys are bus-only and cannot spend on inference, and limits exist per call and per project. These are exactly the kind of operational caveats an agent needs and are not visible in the annotations alone.

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 slightly longer than strictly necessary but remains tightly packed with relevant constraints and caveats. It front-loads the core purpose and every sentence contributes actionable information, with only minor redundancy like 'Flow Agent Bus:'.

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 simple schema, the presence of an output schema, and the annotations, the description covers all essential context: scope limitations, per-call and per-project limits, one-time key display, security handling, and inference restrictions. An agent has enough information to invoke the tool correctly and safely.

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 documents the parameter fully, so the baseline is 3. The description adds semantic value by explaining how the key scope affects acceptable name formats, such as using simple names under a bus-scope key versus full agent://project/name with an owner key. This helps the agent form valid parameter values.

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 action and resource: 'create bus keys for NEW teammates.' It clearly distinguishes the tool's scope from other bus operations by emphasizing 'NEW teammates' and 'mint,' making the purpose unambiguous and distinct from 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?

The description gives clear context for when to use the tool: minting keys for new teammates, with scoping rules for bus-scope vs. owner keys. It does not explicitly name alternatives or exclusion conditions, but the 'NEW teammates' framing and security guidance ('never as a bus message') provide strong usage direction.

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

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

Annotations cover the safety profile (idempotentHint=true, destructiveHint=false), but the description adds substantive behavior the annotations do not: the four-failure dead-letter threshold, the re-offer-on-next-poll timing, and the immediate dead-letter path. It does not state auth requirements or what the caller receives back, which is partly offset by the output schema.

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

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

Three tight sentences, no filler, with the core action first, then the option semantics, then the anti-pattern warning. Every clause carries decision-relevant 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 5-parameter mutation tool with an output schema, the description covers invocation semantics, the retry/dead-letter policy, and sibling disambiguation well. The only real omission is the undocumented 'as' parameter, which an agent cannot interpret from any supplied 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?

Schema description coverage is only 40%, so the description must compensate, and it does for the important parameter: retryable is explained in detail (re-offer later vs dead-letter now) and the required message_id/lease_id/error are named. The 'as' parameter remains undocumented in both schema and description, leaving one 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?

The description opens with a precise verb+resource+scope: 'return a leased message you could NOT process'. The emphasized negation ('could NOT') distinguishes it immediately from bus_ack, its closest sibling, so an agent can route correctly without inspecting 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?

It gives explicit when-to-use conditions (retryable:true vs retryable:false) with the consequence of each, plus an explicit when-NOT-to-use case: 'Never nack something that merely needs no reply — use bus_ack with final:true for that.' That names the alternative and the condition that selects it.

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 says each renewal adds a 15-minute lease and the total is capped at 6 hours, which implies repeated calls change state. The annotations declare idempotentHint=true, so a repeated identical call should produce the same result. This is an annotation 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, no filler, with the core behavior front-loaded and the use case stated compactly. The 15-minute increment and 6-hour cap are concrete and immediately useful.

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 main behavior, duration, cap, and motivation, but leaves the optional 'as' parameter unexplained and does not address what happens at the cap. Combined with the idempotency contradiction, the agent lacks full operational clarity.

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 provides zero description coverage, so the description must explain parameters. It names message_id and lease_id, but does not describe their roles, formats, or the meaning of the optional 'as' parameter. This is only partial compensation for the schema 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?

The description opens with a specific verb and resource: 'extend the lease on a message.' It clearly explains that the tool renews a lease for a message being worked on, and names the two required identifiers. This is immediately distinguishable from siblings like bus_cancel or bus_nack.

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 concrete usage context: use it to keep working instead of letting the lease expire and the message be re-offered to someone else. It does not name or contrast sibling tools explicitly, but the intended scenario is clear enough for an agent to route to this tool.

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 beyond the annotations: attempts are reset, a fresh 24-hour lifetime applies, and the doorbell rings (presumably notifying the recipient). The annotations already indicate idempotentHint=true and destructiveHint=false, and the description does not contradict them. It could add more about side effects or failure modes, but it provides meaningful behavioral context.

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 and front-loaded: it states the action, the target, the scope, and the behavioral effects in two sentences. Every sentence earns its place, and the pointer to bus_history is a useful addition without bloat.

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 tool with two parameters, no output schema, and no enum constraints, the description covers the main action, the target, the behavioral effects, and the discovery path. The only notable gap is the undocumented 'as' parameter, which prevents a perfect score. Overall, an agent has enough context to invoke this tool correctly for the primary use case.

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

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

Schema description coverage is 0%, so the description must compensate for the two parameters. It explains the purpose of message_id implicitly (the message to replay) but does not explain the 'as' parameter at all. The description adds some context for message_id but leaves 'as' undocumented, which is a gap given zero schema coverage.

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 ('re-queue') and resource ('a dead-lettered or expired message'), and explicitly scopes it to messages addressed to the agent ('addressed to you'). It also distinguishes itself from related bus operations by naming the candidate source (bus_history with status 'dead_letter'). This is clear and differentiates from siblings like bus_send, bus_ack, and bus_nack.

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 tells the agent when to use this tool: to replay a dead-lettered or expired message. It also tells the agent where to find candidates ('Find candidates with bus_history {status:"dead_letter"}'), which is a direct pointer to the sibling tool to use before this one. This is strong usage 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description adds substantive behavioral context: the call creates a first-class reply message, implies acknowledgment of the original, and that lease_id fences a stale worker. That is real value beyond the structured fields.

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 dense sentences with the core action front-loaded and the lease-fencing detail following. No wasted words, though the parenthetical note is compact enough that it 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 present, return values need not be explained, and annotations cover the safety profile. The description supplies the mutation intent, acknowledgment implication, and lease fencing, leaving only minor gaps around message/message_id semantics.

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 50%: 'as' and 'lease_id' are documented, but 'message' and 'message_id' carry no schema description. The description compensates for lease_id by explaining where it comes from (messages[0].lease.lease_id in the bus_inbox response) and its fencing role, but says nothing about message/message_id semantics.

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

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

States a specific verb (reply) and resource (a message received via bus_inbox) and distinguishes the action from a plain send by noting it creates a first-class reply message and implies acknowledgment. It does not name the sibling it is contrasted with (bus_send/bus_ack), so it stops short of 5.

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 ties usage to messages obtained via bus_inbox and explains the lease_id fencing purpose (fencing a stale worker), giving concrete context for when to invoke it. No explicit when-not or named alternatives, so not 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 declare the safety profile (readOnly=false, destructive=false, openWorld=true, idempotent=false) but say nothing about delivery mechanics; the description fills that gap with durable delivery, doorbell/webhook wake-up versus queued waiting, the recipient_status/delivery_note fields that report which happened, quota reporting {limit, remaining, reset_s}, and the key requirement ('Requires your bus or owner key'). Those are real behavioral traits an agent needs and none are inferable 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?

Five short sentences, front-loaded with purpose and delivery behavior before branching to the ask/check workflow and auth. It is dense with distinct facts rather than padded, though the quota sentence sits slightly awkwardly at the end.

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 10-parameter mutation tool with an output schema, the description covers what the schema and annotations cannot: delivery/async semantics, the ask-then-check workflow, auth requirements, and quota signaling. Return-value structure is left to the output schema, which is correct.

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 — every parameter is already documented in the schema. The description goes beyond that by framing verb semantics behaviorally ('ask' expects a reply and is fetched via bus_check) and by tying the response's recipient_status to the request, adding meaning the schema alone doesn't convey.

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

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

States a specific verb and resource ('send a durable message to another agent on your account') and pins the address format agent://team/name. It differentiates itself partially from siblings by naming bus_check as the retrieval counterpart, though it doesn't explicitly distinguish itself from bus_reply or the other bus_* send-adjacent 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?

Gives a concrete decision rule: 'Need an answer? verb:"ask" and fetch it with bus_check' — this tells the agent when to pick ask versus a plain message and what alternative tool completes the round trip. No explicit when-not-to-use guidance or mention of bus_reply, so it falls 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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. Description adds rich context: returns agent:// address and key shown once, refusal semantics (already_on_bus), the force_new_account capability, and the post-signup sequence (bus_configure, doorbell, bus_invite/bus_mint).

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

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

Dense and front-loaded: purpose first, then the alternative, then failure mode, then outputs, then next steps. Very information-packed but every clause earns its place; slightly long but justified by the onboard 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?

Output schema exists but the description still notes the return (agent:// address and key, shown once) since it is critical for the key-shown-once semantics. Covers activation flow and manual reference link. Complete for a multi-step onboarding 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 coverage is 100% (baseline 3). Description adds meaning to force_new_account ('a second signup cannot see the first account' / 'presents an existing key is refused'), which explains the reasoning behind that flag beyond the schema's wording. team and agent are covered by 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?

States a specific verb+resource (create a NEW, ISOLATED team account/free, no registration) and immediately distinguishes from siblings: 'FIRST agent of a team only' and names bus_join and bus_invite as alternatives. An agent can tell it apart from bus_join 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?

Explicit when-to-use ('FIRST agent of a team only; if your user already has agents, use bus_join with a code from a teammate's bus_invite'), when-not (a second signup cannot see the first account), and failure mode (a signup presenting an existing key is refused with already_on_bus). Complete 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?

Annotations only signal read-only false and non-destructive, so the description adds useful behavioral context: it requires an API key, costs money, and involves independent assessment plus synthesis. It does not contradict the annotations and discloses relevant operational side effects.

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, front-loaded with the core purpose, followed by the key authentication/cost fact. Every sentence earns its place; 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 tool with four well-described parameters, no output schema, and non-destructive but billed behavior, this description covers the necessary context: what it does, when to use it, and the cost/authentication implication. Minor details about exact return format are not supplied, but the overall behavior is clear enough.

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 already explains all parameters with descriptions. The tool description reinforces the idea of diversity and synthesis but adds little meaning beyond what the schema already states, fitting the baseline 3.

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

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

The description clearly states a specific action (convene a council), the resource (diverse AI models), and the outcome (critique and synthesis). It is easy to distinguish from most siblings, though it doesn't explicitly name an alternative to contrast with.

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

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

The description gives clear context on when to use the tool: when uncertain about a proposal or decision. It does not, however, name alternatives or provide when-not-to-use guidance, so it stops short of a fully explicit routing.

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

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

Annotations already cover read-only/idempotent/destructive safety. The description adds valuable behavioral context: it returns the result, serving model, and exact cost, and requires a Flow AI API key in the Authorization header. This goes beyond the schema and 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?

Two tight sentences, with the primary purpose and benefit front-loaded, followed by return value and authentication requirement. Every sentence earns its place with no filler.

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

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

For a 5-parameter tool with no output schema, the description covers the essential behaviors: what is delegated, what is returned, and what auth is needed. It could mention error cases or model-selection behavior in more detail, but the current information is sufficient for correct invocation in most cases.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level syntax or format details beyond what the schema already provides, but it does reinforce the overall cost-saving intent that ties the parameters together.

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 ('Hand … to the cheapest model') and identifies the exact resource and intent: offloading a self-contained subtask. It clearly distinguishes itself from the sibling bus/council/search tools by focusing on cost-saving delegation.

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 applicability criteria: use it for self-contained subtasks that don't require your own expensive model, to save tokens and move faster. It does not name explicit alternatives or exclusion cases, but the context is strong enough for an agent to decide when to invoke it.

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

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

Annotations already declare it as read-only, idempotent, non-destructive, and closed-world. The description adds that prices are those requests actually clear at, implying real-time data, but it does not disclose return format, pagination, or freshness 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?

Three short sentences, front-loaded with the core purpose, then a key detail about savings and sorting, and a clarifying statement about clearing prices. No waste.

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 a simple read-only tool with one optional parameter and no output schema, the description covers purpose, data content, and sorting. It could mention default limit or result format, but overall it is nearly 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 100%, so the schema fully documents the limit parameter. The description adds no additional parameter semantics beyond what the schema provides.

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

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

The description states a specific verb+resource: it returns Flow AI's live market book of clearing vs published list prices per model, with savings percentage. It clearly distinguishes itself from siblings like list_free_models or search_models by focusing on actual clearing prices.

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 implies the tool is for viewing live prices and indicates sorting by savings, which hints at when it's useful (e.g., to find best savings), but it does not explicitly state when to use this over alternatives like list_free_models or search_models.

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 mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful context beyond the annotations: models are canary-verified, currently promoted into the default routing pool, and served at $0 per token. This helps an agent understand what the returned set represents.

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, well-structured sentence that front-loads the core fact (free models), adds verification context, and states pricing. No filler or repetition of the annotations.

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 listing tool, the description is complete. It explains what is included, why it is trustworthy, and the key property ($0 per token). No return format is specified, but the absence of an output schema is mitigated by the simple nature of the tool and its obvious list semantics.

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 and the input schema is empty, so the baseline applies. The description adds no parameter details because none are needed; there is no schema gap to compensate for.

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 (canary-verified FREE models promoted into Flow AI's default routing pool) and the key attribute ($0 per token). It stops short of an explicit imperative verb like 'List', but the intended action is obvious from the name and phrasing.

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 rather than stated: an agent can infer this tool is for discovering currently available free models. There is no explicit guidance about when to choose it over siblings like search_models or get_live_prices, and no exclusions or alternatives are mentioned.

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 mark the operation as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond this: it is a live catalog search, returns specific fields, and caps results at 20 matches. No contradiction with annotations exists.

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 sentence carries all essential information with no filler. The verb, resource, search criteria, return fields, and result limit are front-loaded and easy to parse.

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

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

For a single-parameter, read-only search tool with no output schema, the description is complete: it explains what is searched, what is returned, and the result limit. Nothing critical is missing for an agent to select and call the tool 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 documents the single 'query' parameter with 100% coverage and a clear description of substring matching. The tool description mostly restates that the search is by name/provider/family, adding limited new semantic detail 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 states a specific verb ('Search'), a clear resource ('Flow AI's live model catalog'), and the search dimensions (name/provider/family). It also distinguishes itself from siblings like list_free_models by emphasizing 'live' catalog and verified capabilities rather than just free models.

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: use this tool when you need to find models by substring matching against id/provider/family. It does not explicitly mention alternatives or exclusions, but the search-oriented framing makes the intended use obvious.

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