HaggleBoard

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

Goes well beyond the annotations (readOnly=false, idempotent=false) by disclosing that the server validates budget, item, walk_away, expiry and autonomy, that failure returns human_approval to relay rather than open, and that the approval link is demo-only with no real human factor. This is exactly the pre-call context an agent needs before a mutation.

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

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

Front-loads the action and the critical human_approval relay rule efficiently. The legal disclaimers (not affiliated, not a party to any sale) are relevant to trust but could be trimmed without losing calling guidance.

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?

It surfaces an important alternate return value (human_approval) despite there being no output schema, but does not describe the success response or what a completed acceptance yields. For a non-idempotent mutation with fully undocumented params, more could be said.

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, yet it only implicitly covers message_id ('by message_id'). thread_id and buyer_token carry no explanation in either schema or description, leaving two of three required params undocumented.

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 (Accept) applied to a specific resource (a seller offer) keyed by message_id. Against siblings counter and decline, an agent can immediately tell this is the affirmative action versus the reject/counter paths.

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

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

The description implies you call this when you agree to a seller's offer and explains the human_approval branch, but it never explicitly names when to choose this over counter or decline. Usage conditions are implied rather than stated.

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 this is a non-read-only, non-idempotent, closed-world mutation. The description adds genuine context beyond them: the seller replies immediately (so the agent knows a response follows rather than a queue) and that the offer is bounded by the mandate's walk_away. It omits error/rejection behavior and any auth expectations for buyer_token.

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 operative content is front-loaded and short. But the two trailing sentences ('Not affiliated with any store, brand or platform. HaggleBoard is not a party to any sale.') are legal boilerplate that consumes space without informing tool selection or invocation.

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

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

For a 4-required-parameter mutation with no output schema and no parameter documentation, the description leaves too much out: what the caller passes, how failures or counter-rejections surface, and what the immediate seller reply contains. The walk_away hint is helpful but not sufficient.

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 carries the full burden — yet it names no parameters at all. Only the word 'price' loosely maps to the price field; thread_id, seller, and buyer_token (the credential) are completely unexplained, as are units/currency or the 0–10,000,000 bound.

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 object — counter a demo seller's latest price — which is distinguishable from make_offer (initiating) and accept/decline (ending). The word 'latest' usefully frames it as a response to an existing seller turn, though 'demo seller' leaves the exact resource scope slightly fuzzy.

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 line 'Must respect the mandate's walk_away' is a real constraint that implies you should check update_mandate/get state before calling. However, it never says when to counter versus make_offer or accept/decline, so the choice among siblings 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 already declare readOnlyHint=false, so the write nature is known; the description adds only that the action closes the thread. It does not say whether the decline is reversible, what state the thread enters afterward, or what the required buyer_token implies about authorization. The legal boilerplate ('not a party to any sale') conveys no behavioral information.

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 actionable clause is front-loaded, but two of the three sentences are store/brand disclaimers that add nothing an agent needs in order to invoke the tool. The signal-to-boilerplate ratio is poor.

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

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

For a non-idempotent mutation with no output schema and fully undocumented parameters, the description should explain the effect of declining and the meaning of buyer_token. It instead spends its budget on legal text, leaving the agent without enough to call it confidently.

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 three parameters, so the description carries the compensation burden and fails: thread_id and buyer_token are never explained, and the reason enum (price/terms/other) is not mentioned or clarified. Only 'your thread' loosely gestures at thread_id.

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?

"Decline and close your thread" gives a verb and a loosely-named resource, so the agent can infer this rejects an offer/negotiation thread. However, it never states what is being declined (an offer? a counter?) or how it differs from siblings accept/counter, which share the same negotiation context.

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 indication of when to choose decline over accept or counter, nor any prerequisite context. The remaining sentences are a platform disclaimer rather than usage guidance, leaving the agent to infer routing from sibling names alone.

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 (readOnlyHint, idempotentHint, closed world), so the bar is lower. The description does add real context beyond them: party-only access and the accepted-thread precondition. But 'plus how it is redeemed' dangles without delivering, and the closing sentences are legal boilerplate rather than behavioral disclosure.

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 purpose is front-loaded in a single efficient clause, which is good. But the remaining half is disclaimer text ('Not affiliated with any store, brand or platform. HaggleBoard is not a party to any sale.') that does nothing to help an agent select or invoke the tool.

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 and no parameter documentation, the description needed to explain both what buyer_token is and what comes back (a token string? redemption instructions?). It does neither, and 'plus how it is redeemed' is ambiguous about whether redemption guidance is a return value or just commentary.

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 carries the full burden for two required parameters and fails. thread_id is only obliquely hinted at by 'an accepted thread'; buyer_token is completely unexplained — the agent cannot tell whether it is the caller's credential, a token from a prior call, or the buyer's identity proof.

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 resource (a signed Ed25519 deal token) and its scope (an accepted thread), which is enough to distinguish it from siblings like accept or list_offers. It stops short of explicitly routing the agent away from any named alternative, so it isn't 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?

'Party-only' and 'for an accepted thread' imply preconditions (you must be a participant, and the thread must already be accepted), which is useful implied usage guidance. However, there is no explicit statement of when to call this versus accept/list_offers, and no clear exclusion or failure condition spelled out.

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 openWorldHint=false, so the safety profile is covered. The description adds that results are deduplicated to the latest per seller and that data involves 'demo sellers', but then spends two sentences on legal disclaimers that do not help an agent invoke the 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?

The behavior is front-loaded in the first sentence, but two of the four sentences are liability boilerplate ('Not affiliated...', 'not a party to any sale') that adds no invocation value.

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 convey the return shape; 'latest offer or counter from each demo seller' gives cardinality and ordering but not the offer fields (price, currency, status) an agent would need to parse. The auth prerequisite is stated, which is the main missing piece otherwise.

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

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

Schema description coverage is 0% for both required parameters, so the description must compensate. It only says buyer_token is needed (an auth credential, which is useful), while thread_id is never mentioned explicitly — 'your thread' only hints at it — and no format, length, or scoping semantics are given.

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 retrieval: the latest offer or counter per demo seller on a thread, which is materially different from the write-oriented siblings (make_offer, counter, accept). It never uses a verb like 'list'/'get' explicitly nor names a sibling to contrast with, so it is clear but not sibling-differentiating.

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 indication of when to call this versus get_deal_token or the action tools; the only usage note is the prerequisite 'Needs your buyer_token'. An agent must infer the workflow position from the tool name alone.

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 this as a non-readonly, non-idempotent mutation. The description adds useful behavioral context: visibility is limited by a disclosure filter and only the seller's own messages are seen, plus legal disclaimers about non-affiliation and non-party status. It does not cover error conditions or authentication requirements beyond the public key, but the added 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?

The description is four sentences, front-loading the core action and side, then adding visibility constraints and disclaimers. The legal disclaimers are somewhat ancillary but may be required; overall it is efficiently structured with no redundant phrasing.

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 mutation tool with three required parameters, a nested object, and no output schema, the description is adequate but incomplete. It covers the offer and key conceptually, but leaves 'thread_id' unexplained and provides no information on return values or error behavior, which the agent may need for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It partially explains 'message' as a 'signed HBP offer' and 'seller_public_key' as an Ed25519 public key, but completely omits 'thread_id' and provides no format or structural details for the nested message object.

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 (submit) and resource (a signed HBP offer plus public key) and indicates the seller side. It distinguishes from generic 'post_need' by focusing on offers, but does not explicitly contrast with siblings like 'counter' or 'accept', leaving some ambiguity about the exact offer lifecycle stage.

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 'for testing your own seller agent' gives a usage context, but there is no explicit guidance on when to use this versus 'counter', 'accept', or 'decline'. The agent must infer that this is for the initial offer rather than a response.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses several non-obvious behaviors: sellers respond immediately, the buyer_token is shown only once and must be preserved, budget_band=true leaks budget precision via a 50-wide band, and personal data must be excluded. This is exactly the context an agent cannot get from the 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?

The required-parameter roster is front-loaded and every sentence carries information about constraints, defaults, or side effects. The closing disclaimer sentences (not affiliated, not a party to any sale) are boilerplate-adjacent but do convey a legal/trust caveat an agent may need to relay.

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 11-parameter, deeply nested mutation with no output schema, the description covers the essentials (required fields, token handling, expiry cap, privacy rule) but omits the semantics of the autonomy and walk_away negotiation structures. An agent could call it, but would be guessing at the negotiation-behavior parameters.

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 11 parameters, so the description must carry the load; it lists the six required fields and explains the optional share.budget_band default and effect, which is useful. However, it never explains the autonomy modes (collect / auto_accept_under / full), walk_away, target_price, max_rounds, or priorities, leaving nearly half the parameters undocumented in both places.

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 first sentence names a specific verb and resource ("Post a demo need with a shopper mandate") and immediately enumerates what the need must contain, so an agent knows exactly what operation this is. It does not, however, contrast itself against siblings such as make_offer or update_mandate, leaving that 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?

Usage context is implied rather than stated: the note that the returned buyer_token is "required for every other buyer call" tells the agent this must be invoked first, and the expires_at cap of 7 days is a hard constraint. But there is no explicit when-to-use/when-not-to-use guidance versus make_offer or update_mandate.

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?

Adds behavior beyond the annotations: it discloses the human_approval escalation path for loosening changes, enumerates which fields count as loosening (budget, autonomy, sharing, expiry, must-haves), and warns the agent never to open the approval link itself. This is meaningful operational context for a mutation tool whose annotations only say readOnly=false, idempotent=false. It stops short of covering response shape beyond human_approval and any 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?

The first sentence is well front-loaded and the approval rules earn their place, but the final two sentences ('Not affiliated with any store, brand or platform. HaggleBoard is not a party to any sale.') are legal boilerplate that consume space without helping the agent invoke the tool.

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 mutation tool with no output schema and 0% parameter documentation, the critical approval behavior is covered, but an agent still lacks guidance on replace-vs-merge semantics, token scoping, and error conditions. Adequate but with clear gaps for a schema this complex.

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 a large nested mandate object, so the description must carry the burden. It does add meaning for the loosening-sensitive fields and for the approval flow, but says nothing about thread_id, buyer_token, or whether omitted optional fields (target_price, walk_away, max_rounds, priorities) are dropped or preserved under 'Replace'.

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: 'Replace your thread's mandate', which is distinguishable from sibling negotiation tools (make_offer, counter, accept). It does not explain what a mandate is or how full replacement differs from a partial update, but the operation itself is unambiguous.

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

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

The description gives one useful usage rule — tightening applies immediately, loosening escalates to human approval — but provides no when-to-use versus siblings guidance and no prerequisites (e.g., token validity, whether the thread must be in an active state).

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