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?

The description discloses several key behavioral traits not found in annotations: it mandates that 'The seller replies at once,' details the auto-decline logic, and outlines the specific E_COOLDOWN mechanic (pausing the seller for 15 minutes).

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

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

The definition is dense but highly efficient; every sentence conveys either a functional rule or an operational constraint that an agent would need for correct usage.

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 high complexity of the operational logic (cooldown, auto-declines), the description provides a complete operational picture of the tool's behavior, making it highly actionable for an AI agent.

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

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

Since schema description coverage is 0%, the description adds necessary context by defining the 'price' as a counter against a 'demo seller's latest price,' clarifying the nature of the input.

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 action ('Counter') and the resource ('a demo seller's latest price'). This distinguishes it from other negotiation siblings like 'make_offer' or 'accept'.

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 provides crucial usage context by defining automatic outcomes (e.g., auto-declined if under 50%) and adherence to operational rules ('Must respect the mandate's walk_away').

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?

The description adds critical operational behaviors that are not covered by the annotations (e.g., it requires a 'signed HaggleBoard offer (format v0)' and the 'Ed25519 public key'). These requirements are specific to the technical behavior of the invocation.

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 detailed and necessary due to the complexity and specific technical requirements. While slightly longer than necessary, every sentence provides unique value (e.g., safety disclaimers, format versions).

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 successfully defines the full context for the tool: it is a seller-side tool for agents, operating in a testing environment, utilizing specific cryptography (Ed25519), and adhering to format v0 standards.

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?

Given the 0% schema description coverage, the description does an excellent job of explaining the semantics of the required parameters: 'message' must be a 'signed HaggleBoard offer (format v0)' and 'seller_public_key' must be an 'Ed25519 public key.'

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 title and description clearly state the purpose is to submit a HaggleBoard offer (make_offer). It specifies the operational context of being 'Seller side' and 'for testing your own seller agent,' immediately distinguishing it from other potential seller actions.

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

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

The description provides explicit usage constraints, including warnings that the tool is 'Not affiliated with any store, brand or platform.' and detailing the specific scope ('You see the need through a disclosure filter'). This helps prevent agents from using it in real-world or unauthorized scenarios.

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?

Goes well beyond the annotations: names the 24-hour expiry refusal and its error code E_EXPIRY_TOO_LONG, explains that fictional demo sellers answer immediately, warns that buyer_token is shown once and unrecoverable, and notes the privacy constraint on personal data. All consistent with readOnlyHint=false (a create) and openWorldHint=false (fictional sellers).

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?

Required fields are front-loaded and the expiry constraint and token warning follow in priority order with no filler. The trailing disclaimers ("Not affiliated with any store...", "HaggleBoard is not a party to any sale") consume space without helping the agent decide or invoke, though they are brief.

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 12 parameters, nested objects and no output schema, the description does well to explain the return value (buyer_token) and the expiry rule. But half of the optional negotiation parameters are undocumented anywhere, so an agent cannot confidently populate walk_away, target_price, priorities or max_rounds.

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 8%, so the description has to carry the load; it does document all six required fields and the tricky share.budget_band behavior (50-wide band). However, walk_away, max_rounds, priorities, target_price and include_test_sellers are never mentioned and have essentially no schema prose, leaving the negotiation surface of a 12-parameter tool 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 ("Post a demo need with a shopper mandate") in the opening clause, so an agent knows this creates a buyer-side request. It does not explicitly contrast itself with siblings like make_offer or update_mandate, leaving the buyer/seller-side split 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?

"Returns a private buyer_token, shown once, required for every other buyer call" effectively establishes this as the entry-point call and routes the agent to the sibling tools. What is missing is an explicit statement of when NOT to use it (e.g. to modify an existing need, use 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?

Annotations cover the basics (readOnlyHint=false, non-idempotent, closed-world), and the description adds genuinely non-obvious behavior: loosening triggers an approval gate, the agent must never open the approval link itself, and approval is a weak demo-only proof. It omits what 'replace' means for omitted optional fields (dropped vs. retained), which matters for a non-idempotent 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?

The first clause and the approval sentence are tight and front-loaded, but the trailing "Not affiliated with any store... HaggleBoard is not a party to any sale" is legal boilerplate that gives the calling agent nothing to act on and dilutes the 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?

For a 3-parameter mutation over a deep nested mandate object with an approval workflow and no output schema, the description covers the approval hazard well but leaves the return shape (beyond the human_approval mention) and the full-replacement semantics of the mandate object unexplained.

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 reported as 0%, but the nested schema itself carries enums, patterns, defaults and two prose descriptions, so the description's added value is modest. It does supply the tight-vs-loose classification across budget, autonomy, sharing, expiry and must-haves, which is not visible anywhere in the schema and is the single most consequential thing to know. However, it never maps those words to actual fields (walk_away, target_price, priorities, max_rounds) nor explains thread_id/buyer_token.

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?

"Replace your thread's mandate" gives a specific verb (replace) and resource (thread mandate), and the full-replacement framing distinguishes it from the offer-level siblings (make_offer, counter, accept). It stops short of naming any sibling tool explicitly, so the differentiation is inferable rather than stated.

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 does give one real usage rule: tightening applies immediately, loosening returns human_approval. But it never says when to call update_mandate versus posting a new need or starting a new thread, nor what prerequisites (buyer_token validity, thread state) apply.

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