machine-works-broker

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

Annotations already declare readOnlyHint and idempotentHint, so 'Read-only' is redundant, but 'no demand or payment created' adds genuinely new domain-specific context that the annotations cannot express in a quoting/marketplace tool. It is a real value-add, though it stops short of describing what the quote contains or whether it reserves anything.

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

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

Two short sentences with zero filler; the core action and the two lookup keys are front-loaded before the safety note. 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 nested economics/return_path objects and no output schema, the description is far too thin: it neither explains the parameters nor what a 'quote' returns. An agent can invoke it with a capability_id, but cannot use any of the other eight parameters correctly from this text alone.

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% across 9 parameters, and several (client, inputs, output, urgency, economics, freshness, return_path) are nested objects with entirely undocumented semantics. The description only gestures at capability_id and the intent (the 'task' param), leaving the economics and return-path fields, which are the highest-risk ones, 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+resource ('Find and quote a registered capability') and names the two lookup keys, capability_id or an exact supported intent. It is distinguishable in spirit from list_capabilities and next_best_capability, but it never names those siblings or explains how the lookup modes differ.

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 'using its capability_id or an exact supported intent' implies when this tool applies (you already know the target), but there is no explicit when-to-use/when-not guidance versus list_capabilities, next_best_capability, or preflight_capability. The agent must infer the routing from the sibling names.

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

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

Annotations already declare readOnlyHint, idempotentHint and a closed world, so the safety profile is covered. The description goes beyond that by disclosing a behavioral trait about the response itself – that it deliberately withholds original inputs, callbacks and requester identity – which is genuinely useful for interpreting results. It stops short of discussing polling cadence, expiry, or error states.

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

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

Two short sentences with no padding; the core action is stated first and the caveat second. 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?

For a one-parameter, read-only, idempotent lookup with no output schema this is close to sufficient, but an agent still lacks any notion of what status values to expect, whether the status is final, or how to obtain the request_id. The privacy note is the only return-value hint provided.

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 carry the parameter burden. Calling the value an 'opaque Broker status URL' usefully signals it is a token that must not be constructed or parsed, but it never says where the value comes from or reconciles with the schema's name of request_id (a dotted 36-char UUID pair).

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 names a specific verb (read) and resource (the Broker status URL for a request), so the agent knows this fetches the status of a previously submitted request. It does not explicitly contrast itself with siblings like request_capability, but the read-vs-write distinction is inferable from the verb.

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?

No when-to-use guidance, no mention of the companion tool that produces the request_id (request_capability), and no statement of when this is or is not the right call. The agent must infer that this is a follow-up poll after a request was submitted.

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 the safety profile (readOnly, idempotent, not openWorld). The description adds real behavioral context beyond them: results are limited to 'public' capabilities, and frozen capabilities are flagged explicitly in the output. It stops short of describing pagination or result size, which matters for a list-everything tool.

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

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

Two tight sentences with no filler; the return contents are front-loaded and the frozen-marking caveat follows. Nothing redundant.

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 tool with no output schema, the description adequately conveys what fields are returned and the frozen-state marker. Pagination/volume behavior is the only notable omission.

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

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

Zero parameters, so the baseline of 4 applies. The description correctly indicates no filtering input exists, consistent with the empty 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 (List) and enumerates the resource contents (capability descriptions, schemas, prices, endpoints), so the agent knows exactly what comes back. It does not explicitly distinguish itself from the sibling find_capability, leaving the browse-vs-search distinction to inference.

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

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

The word 'List' and the zero-argument schema imply a browse-all operation, but the description never states when to use this instead of find_capability or next_best_capability. Usage is only implied, with no exclusions or 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 already declare readOnlyHint=true and openWorldHint=false, so the safety profile is partly covered. The description still adds real value: it respects budget and current availability, explicitly never purchases, and instructs the agent to copy the attribution header when invoking the recommended endpoint — a non-obvious calling requirement.

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 with no padding; the purpose and the key constraints (budget, no purchase) are front-loaded. Slightly telegraphic but efficient.

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

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

With no output schema the description should explain the return, and it does partially (a recommended endpoint plus an attribution header to copy). However, for a four-parameter tool with zero schema descriptions and no annotation coverage of the budget/availability logic, the parameter contract remains unclear.

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% across four parameters, so the description must carry the burden, yet it only gestures at budget_usd ('respects budget') and availability. recurring, has_snapshot, and the required capability_id are left entirely unexplained in both the schema and the description.

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 clear function: producing a deterministic next-step recommendation after a capability is used. The resource is implicit (a recommended capability/endpoint) rather than named, and no sibling is referenced, 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?

'Optional deterministic next step after using a capability' implies timing and that it is not mandatory, and 'never purchases' hints it is a safe planning step. But it never contrasts itself with preflight_capability or request_capability, which are the obvious alternatives for checking or actually obtaining a capability.

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, idempotentHint, and closed-world, but the description adds genuinely new behavior: no target fetch, no demand, and no payment occur. That is meaningful side-effect disclosure beyond the structured fields, though it does not cover return shape or failure modes.

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

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

Two short, front-loaded sentences with no filler; the key guarantee (free, no side effects) is stated immediately.

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 nested objects, no output schema, and 0% schema coverage, the description is far too thin. An agent cannot know how to fill most parameters or what the preflight returns.

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 9 parameters at 0% schema description coverage, the description must carry the burden, but it only vaguely gestures at "input" and "price" (mapping loosely to inputs and economics). The client, output, urgency, freshness, return_path, and capability_id parameters are entirely 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 action (preflight of input/price) and its scope (free, before a paid endpoint invocation), which distinguishes it from the paid sibling request_capability. It is clear but leaves the exact output of the preflight unstated, so an agent must infer what it gets back.

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?

"Before a paid endpoint invocation" implies the timing condition, so usage is implied rather than explained. No sibling is named (e.g., request_capability) and there is no explicit when-not guidance, so routing is left partly 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 already declare mutation, open-world, idempotent, and non-destructive behavior. The description adds meaningful context beyond those annotations: it states the return is an existing durable request ID/status URL and explicitly bounds the tool to economic intent with no payment or spend.

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 and front-loads the main action before the return and boundary clauses. It is efficient, though the opening remains somewhat cryptic about whether the primary behavior is lookup or creation.

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

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

For a complex tool with nested input objects and no output schema, the description omits prerequisites, side effects, parameter mapping, and detailed return behavior. It gives the economic boundary and return shape but not enough context for confident invocation.

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

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

Schema description coverage is 0% across 9 nested parameters. The description gestures at budget, frequency, freshness, and return path, but leaves required task, client identity, inputs, output, urgency, and capability_id unmapped, so it only partially compensates 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 states a clear dual purpose: find a supported outcome or capture an unmet capability request. It names the resource and the economic scope, though it does not explicitly distinguish itself from siblings like find_capability or preflight_capability.

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 or alternative routing. The description implies use when a supported outcome exists or an unmet request needs capturing, but it never mentions when to prefer siblings such as find_capability, preflight_capability, or get_request_status.

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