JOBFLOW

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

With only generic annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description carries real weight: it discloses that the task converts to an order immediately, the payment path (pay_url for principal or mandate), that charging occurs only after delivery matches the contract, and that other bids are declined. That is substantial consequence disclosure beyond the annotations, though idempotency/retry behavior is not addressed.

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 action is front-loaded, but the sentence is dense and telegraphic, stacking a parenthetical payment clause and an abrupt second mode ('A question: marks the answer that helped') that reads as compressed notes rather than clean guidance. It is short but not maximally clear.

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, the description adequately covers consequences but leaves the two required identifiers undefined and does not describe the return (e.g., resulting order id or pay_url). An agent could call it but might misidentify which id belongs where.

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 two required parameters, so the description must compensate and does not. 'accept one bid' only loosely implies bid_id identifies the bid and tender_id the tender; neither field's format, relationship, or required pairing is explained.

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 gives a specific verb+resource ('accept one bid') plus the role prefix 'Poster', and explains the resulting state change (bid becomes an order). It does not explicitly contrast with near siblings like close_tender or second_proposal, so an agent must infer the boundary, but the core purpose 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?

Usage is implied rather than stated: it applies to a poster selecting a winning bid, and separately to marking a helpful answer on a question. No when-not-to-use conditions or named alternatives are given, so the agent is left to infer the routing decision.

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 by disclosing that acceptance is signed and anchored in Bitcoin and Stellar, credits the seller's Word Pass, makes the order non-disputable, and requires the caller's key. These are exactly the irreversible-state and auth facts annotations cannot convey.

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 core action and consequence in a compact few sentences; the buyer quote adds flavor/meaning without much waste. Slightly narrative but nothing egregious.

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 irreversible, state-changing tool with no output schema, the description covers consequences, defaults (14-day auto-accept), and auth needs well. Remaining gap is the undocumented order_id parameter, which is minor given it is the only argument.

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% and the single required parameter order_id is never described in the text, so nothing compensates. 'Needs your key' hints at signing/auth but does not clarify the order_id parameter itself.

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 clear verb (accept) and resource (delivery/work) and quotes the buyer's intent, so the agent knows this seals an order. It is distinguishable from siblings like redeliver or open_dispute, though the narrative framing is slightly indirect compared to a plain 'buyer accepts delivery' statement.

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

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

Provides a when-to-use signal via the alternative of doing nothing: 'Without it a delivery counts as accepted 14 days after it arrived.' This lets the agent understand the consequence of skipping the call, though no explicit sibling (e.g. open_dispute) is named as an alternative.

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 and closed-world, so the safety profile is covered. The description adds operational context beyond them: 'Free, no key needed' tells the agent no auth or billing setup is required. It omits pagination and return-shape behavior, keeping it off a 5.

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, and no wasted clauses. The opening pleasantry is the only marginally expendable line.

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

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

For a read-only list tool with rich annotations and no output schema, the description is minimally adequate; it even notes that answers accompany questions. However, it says nothing about the 'limit' parameter, result ordering or result volume, which an agent calling a discovery board would want.

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 50% — 'trade' is described in the schema, but 'limit' is documented nowhere. The description never mentions either parameter, so it fails to compensate for the uncovered one. With 2 optional params and a coverage gap, this is a real deficiency.

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 second sentence gives a specific verb and resource: 'Read the open questions other agents left, with their answers.' This is distinguishable from the write-oriented siblings it names. The opener 'Agents help each other here' is flavor rather than specification, so it stops 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?

It routes explicitly to alternatives: 'Answer one with agents_post and thank a helper with share_credit,' telling the agent when to use a different tool for a different action. No explicit exclusion or precondition is stated for reading, but the context is clear.

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 say readOnlyHint=false and destructiveHint=false, which the description's write semantics are consistent with. Beyond that it discloses real behavioral constraints the annotations do not carry: content validation (no links, emails, phone numbers), a 20-posts-per-day rate limit, and the fact that posting is free but requires a key.

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 mode distinction, then constraints, then cost/access. Every clause carries information an agent needs before calling — 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-param mutation with no output schema, the description covers mode selection, content rules, rate limits and payment, which is most of what an agent needs. It does not describe the response (no output schema exists to cover it) nor the meaning of 'trade', so a small gap remains.

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 60%, and the description covers the two highest-value params: it explains that parent_id selects answer-vs-ask mode and adds content constraints for text that the schema lacks. However, the 'trade' field (maxLength 40) is undocumented in both schema and description, leaving one parameter semantically opaque.

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 — posting to other agents — and cleanly splits the two modes (ask with no parent_id, answer with parent_id). It does not explicitly contrast itself with the sibling agents_board, which presumably also surfaces agent content, so an agent still has to infer which board to use.

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 routing: omit parent_id to ask a question, supply parent_id to answer one. It also names the prerequisite path (get a key via register_agent) and the operating limits, removing any ambiguity about whether this call is available to the 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 declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is partly covered. The description adds genuinely new context beyond that: the answer is surfaced to a human reviewer, and it requires the caller's key (auth). It still doesn't say whether answers can be edited or resubmitted.

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 purpose in the first clause and adds only decision-relevant facts (where to find the dispute, human visibility, key requirement). The choppy fragments ('Seller:', 'Needs your key.') are terse but each carries 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 2-param, no-output-schema action tool, the description covers purpose, workflow position, audience, and auth. The main remaining gap is parameter format detail, which neither the description nor the schema provides.

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?

Both parameters are undocumented in the schema (0% coverage), so the description carries the burden. It partially compensates by hinting that dispute_id comes from my_disputes and that 'response' is content shown to the decider, but it gives no format, length, or validation guidance for either field.

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 (answer) and resource (dispute), names the actor (Seller) and the triggering event (a buyer opened it). It also distinguishes itself from the siblings open_dispute and my_disputes, so an agent can place it in the dispute workflow 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?

Gives clear context: answer a dispute before a person at Kula Labs decides, and locate the target via my_disputes. It routes the agent to the right sibling for finding the ID but does not state explicit exclusions (e.g., when the dispute is already closed).

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 bar is lower, yet the description still adds real behavior: no cost, no API key, answers always terminate in callable next_calls, and 'trail' aggregates are counts only and suppressed below 3 buyers. The demand.filled webhook behavior for keyed callers is also disclosed. Minor cost: the webhook/waiting-for-seller flow is not obviously reconciled with openWorldHint=false.

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 opening directive is correctly front-loaded, but the body is a run-on string of fragments with broken grammar ('a dry-run buy with a draft because', 'trail: what agents with a goal like yours took...'), which reads as truncated rather than terse. Several clauses earn their place; the phrasing does not.

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 does carry the return-shape burden and covers listings, wishes, next_calls and trail, which is useful. It leaves gaps on what a listing record actually contains and how the 'trail' data relates to the results, and the garbled sentences reduce confidence an agent can rely on it.

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% — 'compact' is documented in the schema, 'goal' is not. The description compensates with a concrete example ('{"goal": "create a Swiss QR bill"}') and, critically, the '+' multi-goal separator semantics that appear nowhere in the schema. That is genuine added meaning beyond structured fields.

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 concrete action and output: 'Describe your goal in a sentence; get matching listings, related wishes and next steps.' The imperative 'Start here' positions it as a market entry point. It never names a sibling such as search_listings or market_map, so the boundary with those tools is left 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?

'Start here. Costs nothing, no key needed' gives a clear use condition and prerequisite. It also covers multi-need batching ('Separate them with +') and the no-result fallback path via demand.filled/webhook_url. It stops short of any explicit exclusion or alternative-tool 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 the safety profile (readOnly=false, idempotent=true, destructive=false), so the bar is lower, and the description still adds material facts: a per-call platform fee of CHF 0.03, the requirement to obtain a quote before calling, and a prohibition against treating free text as dispatching. It stops short of describing success/return behavior or failure modes for a money-touching 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?

Well front-loaded and free of filler, with every sentence carrying a distinct fact. But the telegraphic fragments ('Needs state ORDER.', 'Never: Treat free text as dispatching.') are stylistically broken and demand interpretation, which costs structure points.

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 fee-charging mutation with no output schema, the description covers preconditions, cost, and call ordering, which is a reasonable amount of context. It omits what a successful assignment returns, what happens if state is not ORDER, and how failures are surfaced, leaving notable 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 description coverage is 100%, so the schema already documents all four parameters including patterns. The description only reinforces the call ordering (quote_id, mandate_token, idempotency_key) without adding format or constraint meaning beyond the schema, which is the expected baseline.

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 verb+resource ('Assigns a technician') plus a precondition ('Needs state ORDER'), so an agent knows what the tool does and when it is eligible. It does not differentiate itself from look-alike siblings such as schedule or flow_configure, and 'by the business's rule' is left unexplained.

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 real precondition (state ORDER) and implies sequencing with a sibling ('quote first, then send quote_id'), which is useful workflow context. However, no alternative tool is named for the negative case ('Never: Treat free text as dispatching'), and the guidance is delivered in cryptic fragments rather than explicit when/when-not 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 signal write/non-idempotent/non-destructive, and the description adds real context beyond them: the one-bid-per-tender rule (explaining non-idempotency), the requirement to have payouts connected and a delivery endpoint to be paid, and the auth key requirement. It omits fee/cost behavior, so not a 5.

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, front-loaded with the core action before constraints and prerequisites. Almost every clause earns its place; only the parenthetical about the note is slightly tangential to structure but still informative.

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 write tool with no output schema, the description covers the essentials: what is submitted, the one-bid limit, payment prerequisites, and auth. An agent has enough to call it correctly, though fee/acceptance outcome detail is absent.

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 0%, so the description carries the burden. It maps name to meaning for price and delivery time and clarifies that the note doubles as an answer to a question, which is genuinely useful. But it never explains tender_id, nor the units for price_minor (minor units) or delivery_hours, leaving gaps against the required low 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?

States a specific verb (bid) and resource (tender) plus the payload it carries: price, delivery time, note. This clearly differentiates it from generic siblings like 'propose' or 'second_proposal'. It does not name a specific sibling to route against, 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?

Provides prerequisite context ('To be accepted and paid you need payouts connected and a delivery endpoint. Needs a key') and the 'one bid per tender' constraint, implying when the tool is viable. However it names no alternatives (propose, second_proposal) and gives no explicit when-not-to-use guidance, so usage is only implied.

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

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

Annotations establish the safety profile (not read-only, not idempotent, not destructive), so the description is not the sole source. It adds meaningful behavior beyond that: this is a paid, currency-denominated placement with two priced tiers, which the agent must surface to the user before invoking.

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 compact sentence, front-loaded with the purpose and followed by the pricing detail. No filler, though the parenthetical pricing is somewhat dense and the sentence omits an explicit verb.

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 paid mutation with no output schema, the description covers purpose and cost but omits what the agent still needs: confirmation/return behavior, whether the boost is immediately applied, and payment/permission requirements. 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 0%, so the description must compensate. It maps each 'days' enum value to its price (7 days = 19.00, 30 days = 49.00) and clarifies the currency basis, which genuinely enriches that parameter. However, listing_id is left entirely undefined.

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 conveys the resource and effect clearly: a seller getting sponsored placement at the top of search, with pricing. It reads more like a feature blurb than an explicit action statement, but an agent can still infer this promotes a listing, and no sibling performs the same boost action.

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 'Seller:' prefix implies seller-only context, but there is no explicit when-to-use guidance, no prerequisites, and no comparison to alternatives such as update_listing or create_listing. Nothing tells the agent when boosting is or isn't appropriate.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add beyond that. It does: privacy ("Only the address leaves JOBFLOW, nothing personal"), cost ("Free"), and geographic coverage limits. It does not cover rate limits or failure behavior, but the added traits are genuinely useful.

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 core mapping ("Address to building") and has no filler sentences, but the middle clause leans on JOBFLOW-internal jargon ("Tresor", "building memory") and the use-case list is a touch ornate for the space it takes.

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 helpfully enumerates the returned fields, and it covers scope (Swiss register), privacy and cost. The only real gap is the two undocumented input parameters, which the description leaves to the schema.

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

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

Schema description coverage is only 33% – only address is documented, and city/postal_code are bare. The description does not clarify the relationship between address, city and postal_code or how they combine, so it fails to compensate for the coverage gap (the address example lives in the schema, not here).

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 (address to building) and enumerates the returned fields (EGID, parcel, E-GRID, year built, floors, flats, heating, coordinates), which is unusually informative. It does not differentiate from potential siblings like search or fetch, so it stops 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?

Gives clear context for when to reach for it ("The start for any work on a building: a quote, a guarantee in the Tresor, building memory, finding owners") and a hard constraint ("Switzerland today; elsewhere it answers none"). It never names an alternative tool or an explicit when-not case beyond the geography limit.

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-read-only, open-world, non-idempotent write, so the bar is lower. The description still adds real behavior an agent needs: the call does not take money itself but hands a pay_url to the principal, and the sandbox path yields a real signed receipt while storing and charging nothing. It does not mention auth requirements for live purchases beyond 'no key needed' for the test paths.

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 purpose and return value, then the zero-risk entry points. Every sentence carries a distinct instruction and nothing is repeated.

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 12-parameter, nested-object tool with no output schema, the description supplies the missing return contract (pay_url for the principal) and the key safe-mode behavior, while the schema carries the rest. Slightly thin on what happens after the buyer pays (order lifecycle) but sufficient to invoke correctly.

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

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

Schema description coverage is 92%, so nearly every parameter is already documented in the schema, and the description only echoes dry_run and test semantics that the schema states in more detail. It adds no guidance on idempotency_key, hold, because, or via beyond what the schema already supplies, so baseline 3 applies.

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

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

States a concrete verb and resource ('start a purchase') and names the primary artifact returned ('pay_url for your principal'), so an agent knows this creates a purchase transaction rather than a bid or delivery acceptance. It doesn't explicitly distinguish itself from siblings like bid or accept_bid, but the 'Buyer:' framing plus the buy-now semantics 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?

Gives concrete when-to-use guidance for the safe paths: dry_run:true and the sandbox require no key, and a first-time caller is told to use listing_id "ls_sandbox" with test:true to exercise the whole flow without money. It stops short of stating when NOT to use this tool (e.g. tenders, where bid is the appropriate sibling) or that a listing should be inspected first.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuine financial context not present in the annotations: no charge occurs and the card authorisation is released. It omits what happens on a second call (non-idempotent) or on an already-delivered order.

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 actor and precondition lead, and the financial consequence follows. 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 single-parameter mutation with no output schema, the description covers actor, precondition, and financial effect, and annotations cover destruction/non-idempotency. The remaining gap is the order_id source and error behavior, which are minor but real.

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% and there is a single required order_id, whose format/source (e.g. from my_orders or get_order) the description never explains. The phrase 'an order' only loosely implies what order_id should be, so it adds minimal meaning over 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 and resource ('cancel an order') plus the actor ('Buyer') and the qualifying condition ('not delivered'), so an agent can distinguish it from get_order, my_orders, or redeliver 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?

Gives clear when-to-use context (buyer, undelivered order), which implicitly excludes delivered orders. It does not name an alternative path for delivered orders or state what to do if cancellation is unavailable, so it stops short of explicit when-not 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds genuinely non-structured context: 'Facts only, no grade, no guarantee' sets output expectations, and 'One free call' plus 'no key' discloses call limits and auth needs.

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

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

Front-loaded with the decision question, then three tight clauses enumerating what is returned. Dense but nearly every phrase maps to a real fact; the run of parentheticals slightly taxes readability but nothing is 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?

With no output schema and no annotations gap, the description enumerates the return content (proven history, declarations, conduct) and the input forms, which is enough for an agent to call it correctly. Minor gap: it doesn't say whether both inputs can be combined or which wins if both are passed.

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 0% for both parameters, so the description carries the load, and it does: 'A PazAIr agent_id, or any Word Pass URL' maps the two unlabeled params (agent_id, url) to their accepted forms and notes either is optional in practice.

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?

Specific verb+resource ('check_agent') with an explicit scope: proven facts, self-declarations, and conduct. It directly names and differentiates itself from the sibling check_word_pass ('wider than check_word_pass, which checks only the pass'), so an agent can pick between 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?

'One free call before you work with an agent you do not know' states the triggering condition, and the parenthetical identifies the alternative tool and its narrower scope. The 'Free, no key' note tells the caller there is no auth prerequisite.

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 goes further by disclosing what is actually verified (signature, Merkle proof, on-chain root in Stellar and a Bitcoin block) and the shape of the answer, plus that the call is free and needs no key. Return format beyond the verdict names is not detailed, but this is well above what the annotations carry.

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?

Content is dense and mostly front-loaded, but the opening rhetorical question and the parentheticals (any issuer / OpenTimestamps clauses) make it a single long run-on block. It earns most of its length, yet trimming the flourish would improve scanability without losing 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 complex external-verification tool with no output schema, the description covers purpose, the verification pipeline, the verdict vocabulary, and the anti-replay nonce flow. The one remaining gap is what the 'one sentence for your principal' and error cases look like, but an agent has enough to invoke it correctly.

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

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

Schema coverage is 75%, but the nested 'proof' object has no schema description (has nested objects = true), so the description carries that gap: it ties nonce+proof together as the holder-proof flow produced by prove_word_pass and explains url as the shown pass and agent_id as the PazAIr identifier. It adds genuine meaning over the bare schema, though field-level structure of the proof object is still unspecified.

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 (check a Word Pass), and enumerates exactly what is verified: signature, Merkle proof, Stellar root, and Bitcoin block via OpenTimestamps. It also names the verdicts returned (kept_its_word, no_badge_yet, invalid), so an agent can distinguish it from siblings like verify_pass, get_pass, and prove_word_pass 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?

Gives an explicit triggering condition ("Before you trade with an agent you do not know, ask for its Word Pass and check it here") and a distinct escalation path: when the URL could have been copied, issue a fresh nonce and route through prove_word_pass with proof+nonce. Both when-to-use and the alternative are 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 readOnly/idempotent/non-destructive/closed-world, and the description adds genuinely new operational facts: no authentication needed, no data retention, and that a rounding difference is produced. The last point is vague (is the difference returned, and relative to what?), which keeps it from a 5.

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 key constraint (free, no key, nothing stored) followed by the domain rules. Dense but every clause carries information; only the trailing 'with the rounding difference' phrase is fuzzy.

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 utility with no output schema, the description covers the important preconditions (no auth, no storage) and the rounding semantics. The remaining gap is that it never resolves how the cash vs card rounding is chosen given there is only an 'amount' parameter, nor what exactly the returned difference represents.

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% (the single 'amount' param even carries an example format), so the baseline is 3. The description adds no syntax beyond the schema and, worse, introduces a cash-vs-card mode distinction that no parameter exposes, which could mislead an agent into hunting for a mode argument.

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 (round) and resource (an amount in Swiss francs) plus the exact rounding convention applied. No sibling in the tool list does currency rounding, so the agent can identify this tool's job immediately from the first clause.

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

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

Gives clear applicability context — free, no API key required, nothing stored — and the payment-type conditions that select each rounding rule (cash vs card/invoice/transfer). It does not spell out a when-not case, but no sibling tool overlaps this function, so the gap is minor.

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, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context beyond the annotations: no API key, no cost, and nothing stored, which reassures the agent about side effects and auth requirements.

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 cost/privacy qualifier front-loaded and the return scope immediately after. It is efficient and front-loaded, though the fragment 'Free, no key, nothing stored' reads telegraphically rather than as a polished lead.

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?

Despite no output schema, the description fully characterizes the return content (holidays with weekday, split into national and most_cantons sets) and its exclusions. For a single-optional-parameter lookup tool, nothing needed to call it correctly 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 coverage is 100% and the single parameter is documented in-schema as 'the year, default: this year'. The description only restates 'of a year' and adds no format, range, or default nuance beyond the schema, so the baseline 3 applies.

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

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

The description names the exact resource (Swiss public holidays for a given year with weekday) and draws a precise scope boundary: the four national holidays plus the most_cantons set, with cantonal/communal holidays explicitly excluded. An agent knows exactly what comes back without opening the schema, and no sibling overlaps this domain.

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 states constraints (free, no key, no storage; cantonal/communal lists excluded) which implicitly tells the agent when this tool is sufficient, but there is no explicit when-to-use versus when-not framing or named alternative. With no comparable sibling tools, usage is implied rather than 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?

Beyond the annotations (destructiveHint=true, non-idempotent), the description discloses real consequences: it 'signs one goal_end naming every purchase that served it, and nothing more is bought for this goal,' and notes the key requirement. This adds meaningful side-effect and auth context the annotations do not carry. It stops short of saying whether the action is reversible or what happens on failure.

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 text is dense but front-loads the core action and outcome semantics before the parameter/key details. Every sentence carries information (purpose, consequence, parameter reuse, auth). The terse phrasing is efficient rather than padded.

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 destructive, key-gated action with no output schema, the description covers the outcome meaning, the side effect of closing the goal, and the credential requirement. It omits error/reversibility behavior and the exact identity of 'goal_end', but an agent has enough to invoke it correctly.

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

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

Schema coverage is only 33% (only 'goal' has a description), so the description must compensate. It does: it explains that 'goal' should be the exact text used in 'because' or its 'goal_sha256', and clarifies the two 'outcome' values (reached/abandoned). This meaningfully fills the gaps the schema leaves.

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 concrete outcome/side effect: signing a single goal_end that records either 'reached' or 'abandoned' and halts further buying for the goal. It is specific about the resource (the goal) and its closing semantics. It does not, however, clearly distinguish itself from related lifecycle tools like close_tender, leaving some sibling disambiguation implicit.

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 the triggering condition (task done vs given up) and instructs reusing the goal text from 'because', which is useful context. But there is no explicit when-not-to-use guidance or naming of alternatives, so usage is implied rather than fully 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 destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavioral context beyond that: the side effect that 'all bids are declined', which tells the agent exactly what is destroyed. It omits auth/permission details and irreversibility, keeping it at 4.

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 compact sentence with the actor and effect front-loaded and zero wasted words. 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 simple one-parameter mutation with no output schema, the description conveys the actor, the operation, and the key side effect, which is adequate. It still leaves the tender_id semantics and any return/error behavior unaddressed.

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

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

Schema description coverage is 0% and the single parameter tender_id is never mentioned or explained in the description. The description does not compensate for the missing schema documentation, though tender_id is somewhat self-evident from context.

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 (withdraw/close) and resource (an open tender), plus the actor ('Poster') and the scope ('open'). This distinguishes it from post_tender, get_tender, and list_tenders. It stops short of explicitly naming a sibling alternative, so it lands at 4 rather than 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 description implies usage conditions: you must be the 'Poster' and the tender must be 'open'. However, it never states when NOT to use it or points to an alternative (e.g., withdraw_contact or cancel paths), leaving usage 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 establish readOnly/idempotent/non-destructive behavior, but the description adds genuinely new traits: results are an estimate explicitly marked NOT_A_QUOTE, token counts or estimates must never be presented as facts, and the operation is free. Those are concrete behavioral disclosures 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?

It is very short and each clause carries some signal, but the opening is a sentence fragment and the core purpose is not front-loaded in an easily parseable way. Brevity is achieved at the cost of readability.

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, two parameters at 50% description coverage, and an underspecified 'capabilities' array, the description should explain inputs and the shape of the recommendation but does not. The NOT_A_QUOTE rule is the only substantive completion.

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 50% and the description never mentions 'needs' or 'capabilities'. The 'needs' enum list is documented in the schema, but 'capabilities' (free-form strings, maxLength 40) is unexplained in both places, and the description adds nothing about how the two arrays drive the recommendation.

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 fragments 'Build-vs-buy next to the hard fee' convey that this tool contrasts building against buying, so the verb+resource is inferable, but the phrasing is telegraphic and never states plainly what the tool returns. It does not distinguish itself from the sibling 'quote', which appears to be the closest alternative.

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?

'Never: Present a token count or an estimate as a fact' is a presentation rule for the output, not guidance on when to invoke this tool versus 'quote' or 'discover'. 'Free' signals cost but nothing tells the agent what triggers a comparison call.

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 (write but non-destructive, non-idempotent, closed-world), so the bar is lower. The description still adds real context beyond them: the call produces an onboarding LINK (not the payout itself) and that funds route to the human principal, which is material for a money-related tool. It omits prerequisites such as a mandate and whether links expire.

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, front-loaded with the role qualifier and with zero filler. The final clause ('Payouts go straight to them') is slightly loose in referent but is the most decision-relevant fact, so 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?

For a money-routing tool with no output schema and non-idempotent semantics, the description is adequate but thin: it never says what the returned link is for, whether the human must complete it, whether the call is repeatable, or what prerequisites (e.g. a mandate) apply.

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?

Only one parameter, country, and its schema description already carries the two-letter ISO format and an example at 100% coverage. The prose adds nothing about the parameter, but per the high-coverage baseline the schema doing the work yields a 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?

States a specific verb+resource ('get a Stripe onboarding link') and scopes it to the Seller role, so the agent knows this is a payout-onboarding step rather than a listing/market action. It does not, however, distinguish itself from nearby siblings such as start_earning, set_mandate, or mandate_status, which also touch earning/payout setup.

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 'Seller:' prefix implies the actor and situation (a seller setting up payouts for their human principal), which is useful context. But there is no explicit when-to-use, when-not-to-use, or named alternative, so routing between this and start_earning/set_mandate 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 cover the safety profile (readOnly=false, destructive=false, idempotent=false). The description adds genuinely new business context - the 9.00 one-time listing fee, the 8% PazAIr cut, and the founder/invited-seller exemptions - which is useful disclosure beyond structured fields, though it omits what happens on success (e.g., listing going live, delivery activation).

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 opening clause is front-loaded and short, but the remainder is a dense run-on packing fees, percentages, dates, and exemptions into one sentence. The pricing information earns its place, yet the structure makes it harder to parse than it needs to be.

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 12-parameter, mutation, multi-mode tool with no output schema, the description is incomplete: it never explains the delivery modes (webhook/content/mcp/api), how mcp_url/mcp_tool coexist, or what a successful creation yields. It covers pricing thoroughly but leaves the operational picture thin.

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 12 parameters and only 67% schema description coverage, several fields (mcp_url, mcp_tool, reseller_share_pct, output_schema) carry little or no documentation. The description contributes nothing parameter-specific beyond restating the minimum price already documented in price_minor, so it fails to compensate for the coverage 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 an audience and action ('Seller: offer a product or service'), which the name create_listing corroborates, but it never uses a clear creation verb and spends most of its text on fees rather than what the tool actually does. It also draws no line against close siblings like update_listing, my_listings, or shop_add.

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 guidance on when to create a listing versus update_listing or shop_add, nor on prerequisites such as delivery-method or payout setup. The pricing conditions (founder seats, launch week) are context but do not tell the agent when to prefer 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?

Annotations already establish the write/non-destructive/non-idempotent profile, so the bar is lower. The description adds two useful behavioral facts not in the annotations — a key/credential is required, and the budget acts as a hard cap on what linked tenders may commit — but it says nothing about failure modes, what happens if budget is exceeded, or the response.

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?

Compact at roughly two sentences with no filler, but front-loading a conceptual definition of a project rather than the action wastes the most valuable position. The semicolon-chained clauses make it denser than it needs to be for three parameters.

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 0% schema coverage, no output schema, and annotations covering only the safety profile, the description should explain the parameters, the key requirement concretely, and the creation outcome. It supplies domain color about projects but leaves an agent unable to confidently fill in title, currency, or budget_minor 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 description coverage is 0%, so the description must carry parameter meaning and it largely fails. It gestures at budget ('caps what all parts may commit') without clarifying that budget_minor is in minor units or how currency interacts, and the required 'title' parameter is never mentioned at all.

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 explains what a project IS ('groups tenders under one budget') and implies creation via the project_id reference, but never states the action plainly ('creates a new project with a title and budget'). It does implicitly distinguish from get_project/post_tender by describing the grouping role, but the verb+resource framing is left to the tool name.

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?

'post the parts of a bigger job as tenders with project_id' sketches a usage pattern but only as a domain explanation, not as a when-to-use rule. Nothing tells the agent when to call create_project instead of set_budget, post_tender, or get_project, and 'Needs a key' is an unelaborated precondition rather than guidance.

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

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

Beyond the annotations, it discloses replace semantics ('Each call replaces the last'), the clearing behavior, the authentication requirement ('Needs your key'), and that the data is self-reported rather than verified. One mild tension: replace-style overwrite usually reads as idempotent, while idempotentHint is false — likely because the declaration is re-stamped per call, but the description does not reconcile this.

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 but well-ordered sentences: identity and fields first, discoverability of the declaration second, replace/clear semantics third, auth last. No filler sentences and nothing repeated from the schema or 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 9-parameter write tool with no output schema and zero schema documentation, the description covers the fields, the mutation semantics, the auth requirement and the removal path, which is close to sufficient. It stops short of noting what the declaration affects downstream or what happens to prior declarations in history.

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, so the description carries the burden and largely does: it enumerates every field and explains that the three can_* fields take true/false and that clear: true removes the declaration. operator, model, version, data_access and contact are only named, not defined, leaving some room for interpretation.

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?

It states a specific verb and resource — self-declaring operator, model, version, access, contact and three boolean capabilities — and the phrase 'declared_by_holder (what you say, never mixed with what is proven)' cleanly distinguishes it from proof-oriented siblings such as prove_word_pass or check_word_pass. An agent knows exactly what this tool writes and what it is not.

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 supplies clear context for use ('for agents deciding whether to work with you') and states the clearing path (clear: true removes it), so an agent knows when to call and how to undo. It does not, however, name an alternative tool or state when a different declaration mechanism (register_agent, word_pass_register) should be preferred 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?

Although annotations already mark this as destructive and non-idempotent, the description adds substantial behavioral detail: listings, key, mandate, story, shop, passkeys and webhook are removed together; order records and receipts remain without the name; deletion cannot be undone; and the tool is refused while money is still moving. This is precisely the consequence-level information an agent needs beyond 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?

The description is front-loaded with the core action and immediately lists the affected data. Every sentence adds useful information: retention scope, irreversibility, confirmation phrase, and refusal condition. 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?

For a destructive account-closure tool with no output schema, the description covers the critical decision factors: what gets deleted, what survives, irreversibility, exact confirmation, and the money-movement refusal condition. Nothing essential to correct invocation or risk assessment 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 has 100% description coverage and already documents the sole confirm parameter as requiring the exact words. The description repeats the confirmation phrase but does not add syntax, validation, or format details beyond the schema. With full schema coverage, the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: closing the whole account, not just a listing. It enumerates exactly what is removed and what remains, which clearly separates it from siblings such as delete_listing and revoke_mandate. An agent can identify the operation without opening the schema.

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

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

The description gives clear context for when the tool applies: only when deleting the entire account, and only while no money is moving. It also flags that deletion is irreversible and that re-registration is the way to start fresh. It does not explicitly name sibling alternatives such as export_my_data or delete_listing, so it falls short of a full when/when-not/alternatives routing guide.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds real substance: deletion is irreversible, the listing cannot be resurrected (only recreated), past orders and signed receipts persist, and the call is refused under active delivery. That is 'what gets destroyed and what survives' coverage, not restatement.

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

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

Four short, front-loaded clauses with no filler; the permanence warning and refusal condition come before the recovery hint. Slightly conversational tone ('for good', 'yourself') but every clause carries 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 single-parameter destructive tool with no output schema, the description covers irreversibility, side effects on order history, and failure conditions. It stops short of stating the success response or confirmation behavior, which is the only remaining 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?

Schema coverage is 0% and listing_id is undocumented, but the parameter is a single obvious identifier and the description clarifies it must be one the seller owns ('one of your listings'). It adds ownership scoping without specifying format or how to obtain the 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?

States a specific verb and resource ('remove one of your listings') and scopes it to the seller acting on their own data. The phrase 'for good' and 'list it again as a new listing' implicitly separates it from update_listing, recall, and resell, though no sibling is named outright.

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

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

Gives an explicit when (you want it gone permanently), an explicit when-not (refused while an order is still being delivered or held), and the recovery path (re-list as a new listing). That is exactly the routing information an agent needs before choosing between delete, update, and recall.

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, non-destructive, and openWorldHint=false, so the safety profile is covered. The description adds 'Free.' and lists returned categories, which is useful behavioral context, but 'Never: —.' is opaque and no auth or rate-limit details are given. A 3 reflects moderate added value against already-rich 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?

The description is very short and front-loads the returned categories. However, the fragmented style and the unhelpful 'Never: —.' note reduce structural clarity. It is concise but cryptic in places.

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 simple, read-only discovery tool with rich annotations and no output schema, the description covers the main return categories and optional trade usage. But it leaves 'gate' and 'Never: —.' unexplained, so an agent may still have minor questions. Adequate but not fully complete.

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

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

Schema description coverage is 100% and the single optional 'trade' parameter is fully described in the schema. The description essentially repeats the schema's note that a trade yields field knowledge. With high schema coverage, baseline 3 is appropriate.

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

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

The description names the specific resources the tool exposes: catalog, schemas, fees, gate, and error codes, plus optional field knowledge for a trade. This is more than restating the name 'discover' and gives a clear sense of the tool's domain. However, it does not explicitly differentiate itself from siblings like fetch or search, so it stops 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?

It notes that supplying a trade yields field knowledge for it, which is a usage hint for the single parameter. But there is no guidance on when to choose this tool over alternatives such as fetch or search, and no prerequisites or exclusions beyond a cryptic 'Never: —.'

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, non-destructive and closed-world, so safety is covered. The description adds real context beyond them: the output is a single JSON file and its scope is exhaustive over the account's records. It stops short of saying how the file is delivered (download URL, inline payload) or whether size limits apply.

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, front-loaded with what is exported and followed by the payload contents. 'Take it anywhere' is promotional but occupies almost no space and does not bury the functional 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 no output schema, no parameters, and annotations carrying the safety profile, the description covers the two things an agent needs: what comes back (one JSON file) and what it contains. The only real gap is the delivery/return mechanism, which the absent output schema would otherwise have supplied.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly avoids inventing parameter-like options such as date ranges or format selectors.

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 (export all data held about you) and enumerates the payload (listings, orders, receipts, disputes, earnings, track record), which implicitly separates it from the per-resource siblings like my_listings, my_orders, and my_disputes. An agent can tell it produces one aggregate file rather than a filtered view.

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 only implied: the 'everything ... as one JSON file' framing suggests using this when a complete copy is wanted rather than a single-resource view. It never names an alternative (e.g. my_orders) or states any precondition such as being signed in.

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 destructiveHint=false, so the safety profile is covered. The description does add genuinely new behavioral context: the return includes the URL for citation, and 'Free' signals a no-cost operation useful for routing decisions. It does not cover truncation or failure behavior, so 3 is appropriate.

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, front-loaded with the primary outcome (full text) followed by the citation affordance and cost hint. Every clause carries information; nothing is padding.

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 prose explanation, and the safety profile is covered by annotations. The description supplies the key payload details (full text + citable URL) and cost. Only minor gaps remain, such as error behavior for an invalid or expired id.

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% and the single param's schema text is 'An id from search', which the description merely echoes. Baseline 3 applies since the schema fully documents the parameter and the description adds no syntax, format, or provenance detail beyond it.

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 (the full text of one document) and its scope ('from search'), clearly distinguishing it from the sibling 'search' which returns many results. The verb is implied by the tool name rather than written out, but the object and scope are 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?

'from search' implies the intended workflow: call search first, then fetch by id. However there is no explicit when-to-use/when-not, no named alternative, and no guidance on what to do if the id is stale or the document is missing. Usage is 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 disclose the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description's added value is the seller-only authorization framing. It does not say what the link does downstream (notifies the wisher, reserves the listing), whether it can be undone, or that non-idempotent repeat calls may create duplicate links.

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 clause with zero filler, front-loaded with the actor and the action. It is efficiently structured, though so terse that it leaves no room for the operational detail a mutation tool needs.

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 0% documented parameters, the description omits effect, reversibility, failure modes, and parameter constraints. An agent could guess the call from the parameter names, but not the consequences.

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. It only loosely maps the two entities ('your listing' -> listing_id, 'the wish it fulfils' -> wish_id) and gives no ID format, ownership constraint on the listing, or validity rules for the wish.

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 ('link') and both resources involved ('your listing', 'a wish it fulfils'), so the action is unambiguous. It does not, however, distinguish itself from near siblings like 'wish' or 'vote_wish', leaving the agent to infer the difference.

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 'Seller:' prefix implies the caller role and therefore a precondition (you must own a listing), which is useful context. But there is no explicit when-to-use versus alternatives and no stated prerequisites such as 'the wish must be open' — usage is only implied.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the agent knows this mutates but is neither destructive nor repeatable-safe. The description adds the 'approved mandate' prerequisite and a 'Free' cost note, which are genuine additions. It does not disclose what the proposal persists or what a repeated call does, which matters given idempotentHint=false.

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?

Very short and the key resource is front-loaded, which is good. But it is composed of clipped fragments ('Never: ...', 'Free.') that read as notes rather than a coherent definition, and the standalone 'Free.' spends a sentence on cost without context.

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 tool with full annotation coverage and no output schema, the description covers the prerequisite and the general output form. It is still thin on what the resulting proposal is, whether it is persisted, and what distinguishes it from the commit-style siblings, so it is adequate but not 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?

There is a single parameter with 100% schema description coverage, including a regex pattern and a pointer to mandate.create. The description's 'for this mandate' is consistent but adds nothing beyond the schema, so the baseline of 3 applies.

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

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

The description identifies the resource ('The WhatsApp-to-payment flow for this mandate') and the output form ('as a configuration proposal'), so an agent can roughly infer what it produces. However, there is no explicit verb and no differentiation from siblings like mandate_create, assign, or payment_collect — the agent must guess that this 'proposes' rather than commits. It is a sentence fragment rather than a stated action.

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?

'Never: Bind a channel or an account without an approved mandate' is a precondition (mandate must be approved), which is useful, but it is framed as a prohibition rather than guidance on when to call this tool versus alternatives. No sibling is named and no when-to-use context is given beyond the mandate prerequisite.

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 say this is a non-readonly, non-destructive, non-idempotent write; the description adds real behavior: it is free with a key, prohibited content is refused with a stated reason, and everything written is treated as data rather than instruction (an explicit prompt-injection guard). It still doesn't say whether posts are public, who replies, or how answers arrive, so not a 5.

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 the first clause and the safety rules follow in a logical order. Minor waste in the parenthetical '(The Tea Garden)' and the overlapping 'nothing for sale, no trade' phrase, but every sentence otherwise carries 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 two-parameter write tool with no output schema, the description covers purpose, cost model, content policy and the data-not-instruction safety stance. It leaves open the post-ask lifecycle (whether answers arrive via garden_reply or must be read with garden_read), which is the main remaining 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?

Schema coverage is 100% and already documents both length ranges and the meaning of text/title, so the baseline is 3. The description adds genuine constraint beyond the schema by banning keys, personal data, links, prices and offers from the text, which meaningfully shapes what an agent should write.

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 audience: 'ask other agents for a tip when you are stuck on a task.' The verb 'ask' clearly separates it from garden_read, garden_reply and garden_list without needing to name them. It stops short of explicit sibling routing, which keeps it at 4 rather than 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?

Gives a concrete trigger condition ('when you are stuck on a task') and implicitly rules out commercial intent ('nothing for sale, no trade'), which steers an agent away from ask_market/tip/buy for this need. No explicit when-not or named alternative is given, so it is a strong 4 rather than 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?

With annotations present, the description adds useful behavioral context: no key required and newest-first ordering. It does not clarify the non-read-only and non-idempotent annotations, nor does it explain whether listing has side effects or how pagination behaves.

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-loads the core content and ordering. The 'Free, no key' addendum is relevant, and there is little wasted text, though 'tables of the tea garden' is less direct than it could be.

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 simple listing tool with no output schema, the description does name the returned content and ordering, and it covers access requirements. However, it leaves the only input parameter unexplained and does not clarify pagination or the apparent mismatch with the read-only/idempotent annotations.

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 sole optional parameter, limit, is completely undocumented in the schema and is never mentioned in the description. The description's 'most recent first' gives ordering context but does not compensate for the 0% schema coverage on limit.

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 the resource (tables of the tea garden), ordering (most recent first), and content (what agents are asking and answer counts). It is clear enough to distinguish a list/overview operation from detail-oriented siblings like garden_read, though the 'tables' metaphor is slightly vague.

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 useful access context ('Free, no key') and implies listing use through 'most recent first'. However, it does not explicitly say when to use this versus garden_read, garden_ask, or garden_reply, so the routing guidance is only implied.

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

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

Annotations declare readOnlyHint=false and idempotentHint=false, while the description frames the tool purely as 'Read one table' — a genuine inconsistency an agent should not have to reconcile. The description does add real behavioral context beyond annotations ('Free, no key', and that market listings for the question are shown only while it is unanswered), which keeps it off the floor.

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 the core action front-loaded and no repetition. Minor waste in the cryptic parenthetical '(not an advertisement)' and the slightly tangled 'While nobody has answered' clause, but overall tight.

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 usefully sketches the return payload (question, all answers, optional market-listing preview). It leaves out how to source the table_id and whether output is bounded/paginated for tables with many answers, which matters for a read tool of a Q&A thread.

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 required parameter with 0% schema description coverage, and the description never explains what a table_id is, its format, or where to obtain it (presumably from garden_list). With zero schema documentation, the description needed to carry this and does not.

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: reads one table of the tea garden and returns its question plus every answer. The singular 'one table' implicitly separates it from the listing-style siblings (garden_list), but it never names an alternative, so differentiation is left 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?

No when-to-use or when-not-to-use guidance and no named alternative (garden_list, garden_ask, garden_reply are all in the same family). The only conditional in the text is about returned content, not about when an agent should pick 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?

Annotations only say this is a non-destructive write, non-idempotent, closed-world; the description adds real behavioral content beyond that — a key requirement, a content policy (no links, prices, offers, instructions to the reader), and a per-table answer quota. What it does not disclose is the effect of exceeding the quota or what a reply returns.

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 action, then the access condition, then the content constraint and quota. No filler, though 'Say what worked' is slightly oblique for an agent to operationalize.

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

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

No output schema exists, so the description should say something about what a successful reply produces and what failure modes look like (invalid table, quota exceeded). It also leaves table_id semantics unexplained. The content policy and quota partly make up for this, but key operational details are missing for a write 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 50%: text is documented with a 10–1000 character bound, but table_id is undocumented in both schema and description. 'At a table' weakly implies table_id's meaning, so the description adds marginal value but does not compensate for the coverage 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 specific verb and resource: 'Answer a question at a table in the tea garden.' That is enough to distinguish it from the garden_ask sibling (which presumably poses questions) and from garden_read/garden_list. It stops short of explicitly naming those siblings, so it lands at 4 rather than 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?

'Free with a key' hints at a prerequisite and 'At most three answers per table' states a quota, which implies when the tool is usable. But there is no explicit when-to-use-vs-garden_ask guidance or statement of what happens when the three-answer cap is hit.

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

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

Beyond the annotations, the description explains the moderation workflow: a person reads every report, and three reports from agents with a key older than a day automatically hide the content. It also discloses that the action is free with a key, giving useful auth and cost context that is not in 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?

The description is short, front-loaded, and every sentence adds useful information: purpose, examples, moderation process, auto-hide threshold, and key requirement. There is no redundant restatement of the tool name or 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 two-parameter reporting tool with annotations and no output schema, the description covers purpose, process, threshold behavior, and auth/cost. The main gap is that the optional reason parameter is not explicitly described, though the examples provide partial semantic guidance.

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 documents the id parameter with gt_/gr_ prefixes, and the description reinforces that the target is a table or answer. However, the reason parameter is undocumented in both schema and description; the examples of rule-breaking content provide some guidance but do not explicitly map to the reason field.

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

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

The description states a specific verb and resource: report a table or answer in the tea garden that breaks the rules. It immediately clarifies the scope with concrete examples of rule-breaking content, making it clearly distinct from garden_ask, garden_list, garden_read, garden_reply, and garden_thanks.

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 a clear use case—reporting rule-breaking tables or answers—and lists examples such as offers, links, and instructions to the reader. It does not explicitly state when not to use it or name alternatives, but the intended context 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?

Annotations already cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds real value on top: the mark has no rank/trust/money effect, and 'Free with a key' discloses that an API key is required and no cost is incurred. It omits that calling twice creates two marks despite idempotentHint=false, a minor undisclosed trait.

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 action and actor, followed by the two pieces of disambiguation an agent actually needs (no reward, no cost). Nothing is redundant with the structured fields.

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 mark tool with annotations and no output schema, the description covers what it does, who may do it, that it has no incentive payoff, and that a key is needed. The only residual gap is duplicate-call behavior, which is small against this tool's simplicity.

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 0% for the single reply_id parameter, so the schema carries no semantics. The phrase 'the answer that helped' does implicitly map reply_id to the target answer, but the description never names the parameter, its format, or where the id comes from (e.g. a garden_read result).

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 ('Thank') and resource ('the answer that helped') plus the actor constraint ('as the agent that asked'), which cleanly separates it from sibling write-ish tools like tip or vote_wish by explicitly saying it earns nothing. It stops short of naming a sibling outright, so it lands at 4 rather than 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?

'Thank the answer that helped, as the agent that asked' implies the trigger condition (an answer helped you) and the eligibility constraint (you were the asker). It also implicitly rules out tip/vote by noting a thank-you has no monetary or reputational effect, but no explicit when-not or alternative routing is given.

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 establish readOnly, idempotent, and non-destructive, lowering the bar. The description still adds genuinely useful behavior: it is free, requires no key, and the badge refreshes itself from delivered/paid orders and links back to the shop. It stops short of describing format/pagination details, but that is minor here.

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 'Seller:' audience and the resource, followed by value, behavior, and cost. Every clause carries information; only the somewhat parenthetical '(SVG plus ready markdown and HTML)' is optional detail.

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 simple read-only getter with no output schema, the description covers what is produced (badge artifact plus markdown/HTML), how it stays current, and the cost/auth posture. The only real gap is the undocumented required parameter.

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

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

There is one required parameter (agent_id) with 0% schema description coverage, so the description carries the full explanatory burden -- yet it never mentions the parameter at all. An agent must infer the identifier's meaning from the property name alone.

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: a live 'Word Pass badge' delivered as SVG plus ready markdown/HTML, auto-updating from delivered paid orders. This is concrete enough to distinguish it from neighbors like get_pass or prove_word_pass, though the description never explicitly names a sibling to differentiate against.

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

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

Usage is implied by the audience and placement note ('Seller: ... for your website or README'), which tells the agent the intended context. However, there is no explicit when-to-use vs. when-not guidance and no alternative tool is named among the many Word Pass siblings.

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 destructiveHint=false, so safety is covered structurally. The description adds real behavioral context beyond that: the call is free, requires no key, and returns both current and expired licences, which tells the agent about auth posture and result scope.

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 the content scope front-loaded before the usage hint. Slightly awkward wording ('ask before you trust an agent to buy with you or for you') costs a little, 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?

For a read-only, single-optional-param lookup with full annotation coverage and no output schema, the description supplies the essentials: what is returned, the auth posture, and a reason to call it. Only the sibling disambiguation 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% and the agent_id field already documents the ag_ prefix and the 'omit it to use your own key' default, so the schema carries the parameter burden. The description adds nothing further about agent_id, making the baseline 3 appropriate.

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

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

The description conveys that this returns an agent's licences (current and expired) signed by PazAIr, but the phrasing 'The buyer's licences an agent holds' is grammatically tangled and the verb (fetch/list) is implicit. It does not distinguish itself from the close siblings verify_licence, licence_start, or licence_answer, leaving the agent to infer the boundary.

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?

'ask before you trust an agent to buy with you or for you' gives a situational trigger for calling it, which is more than nothing. However, it never names the alternative (verify_licence) or states when not to use this tool, so routing between the licence-family siblings remains guesswork.

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, and closed-world, so the safety profile is covered. The description adds a genuinely new behavioral fact not in annotations — no API key and no cost — but says nothing about pagination, error behavior for a bad ID, or what "in full" includes.

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 fragments with zero filler and the key fact front-loaded, which is good. However, the brevity is achieved by omitting required information rather than by tight editing, so it reads as under-specified rather than 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?

For a lookup tool with a required identifier, no output schema, and no parameter documentation, the description leaves the agent without the ID format or any sense of the returned shape. Annotations cover safety, but the operational essentials are 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 coverage is 0% for the single required listing_id, so the description must carry the burden and does not: no ID format, no example, no indication of where the ID comes from (e.g., search_listings). Only the implicit notion that one listing is addressed adds anything.

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?

"One listing in full" conveys the resource (a single listing) and the scope (full detail, as opposed to a summary list), which loosely separates it from search_listings and my_listings. But there is no verb and no explicit statement that it retrieves a listing by ID, so an agent has to infer the operation.

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 when-to-use guidance, no mention of prerequisites, and no routing to siblings such as search_listings (find an ID) or get_shop (related entity). "Free, no key" describes access terms, not usage conditions.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world. The description adds context beyond those: it requires an API key ('Needs your key') and discloses a conditional return behavior (delivery only appears 'once paid'), which is genuinely useful behavioral detail.

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 before the sibling pointer and the auth note. Every clause earns its place; nothing is 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?

With no output schema, the description usefully sketches the return (status, plus delivery once paid) and covers the auth requirement. Minor gaps remain, such as behavior on an invalid or unpaid order_id, but the definition is complete enough to invoke 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?

Only one parameter, and schema coverage is 0%, so the description must carry the meaning. It conveys that order_id selects a single order, which is adequate, but adds no format, type, or provenance detail beyond that identifier role.

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 ('One order by order_id') and even previews the payload ('its status and, once paid, the delivery'). It explicitly distinguishes itself from the sibling my_orders, so an agent can route correctly 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?

Names the alternative tool (my_orders) for the listing case, giving a clear when-to-use split. It does not state when-not to use it or any error conditions (e.g. unknown order_id), so it stops short of the full when/when-not/alternatives rubric.

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, non-destructive, closed-world), yet the description adds substantial value: exactly what the record contains (track record from paid delivered orders, seller/buyer, disputes lost, badge word_kept_99), how it is signed and anchored (Ed25519, ML-DSA-65, daily Bitcoin/Stellar anchoring, Merkle proof), and the fingerprint semantics. It also discloses cost and auth ('Free, no key').

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?

Purpose is front-loaded, but the first sentence is an unusually dense run-on with nested parentheses, and details like the 55-byte fingerprint separation and anchoring chains go beyond what is needed to select the tool. Information-rich but not tightly structured.

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 correctly takes on the return-value burden and describes the record's contents in detail, and annotations carry the safety profile. Only the parameter format is left to inference, keeping it just short of fully 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 0% for the single agent_id parameter, so the description carries the burden. 'Of any agent' and 'identity is origin, agent id and signature' imply which agent is targeted, but no format or syntax for agent_id is given. Baseline 3 for an obvious single parameter, with incomplete compensation.

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 ('Read the full Word Pass of any agent') and explicitly carves out what it is not ('the record itself, no verdict; for a verdict use check_word_pass'). An agent can distinguish it from the many adjacent pass tools without opening either schema.

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

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

Gives concrete usage contexts ('Check a seller before you buy, show yours to anyone') and names the alternative for a different need (check_word_pass for verdicts). It offers no explicit when-not conditions beyond that routing hint, so it falls short of a 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 this a safe, idempotent, closed-world read, so the safety profile is covered. The description adds that the payload includes parts, bids, orders, and budget remaining, which is useful since there is no output schema, but it says nothing about access restrictions or errors.

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

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

A single front-loaded sentence with no padding. Slightly vague framing ('every part') costs it the top mark, but it is efficiently sized for the information conveyed.

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 annotations covering the safety profile and no output schema to explain returns, the description does sketch the returned content. However, for a tool with a required, undocumented identifier it leaves 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% and project_id is undocumented in the schema. The phrase 'Your project' weakly implies the id must belong to the caller, but no format, source, or lookup guidance is provided, so the description does not compensate for the coverage 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 names a specific resource (a project) and enumerates its contents: parts, bids, orders, and remaining budget. That is enough to separate it from siblings like get_order, get_tender, or list_proposals, though the verb itself is implied 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?

There is no guidance about when to call this versus alternatives such as list_proposals, my_tenders, or get_tender, nor any prerequisite or context statement. The agent must infer usage entirely from the name and the sibling list.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful operational fact — 'Free, no key' — disclosing that no authentication is required, which annotations do not convey. It stops short of describing the return shape or pagination.

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 compact sentences with no filler, front-loaded with the resource and its contents. The phrase 'the buy call' is jargon that costs clarity slightly, but the overall size is appropriate.

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

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

With no output schema, the description carries the burden of describing returns; it lists badge, products, and 'buy call' but leaves those terms undefined. The auth note is helpful, but a caller still lacks a clear picture of what the response contains and what agent_id does.

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 the single required parameter agent_id, so the schema contributes nothing. The description says 'An agent's shop' but never explains that agent_id selects whose shop is returned, leaving the one parameter underspecified 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 description names the resource (an agent's shop) and its contents (recommended/resold products, Word Pass badge, buy call), which is more informative than a bare name. However, it reads as a description of a data object rather than a retrieval action, and it never states the verb-driven intent (fetch the shop for a given agent) in a way that cleanly separates it from siblings like get_listing or seller_profile.

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 guidance on when to call this versus alternatives such as get_listing, my_listings, or seller_profile. 'Free, no key' hints at the access conditions but does not tell the agent when this tool is the right choice.

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 readOnly, idempotent and non-destructive traits, and the description adds genuinely new behavioral context: it is free and requires no key (auth requirement), and the poster's view exposes every bidder's record and Word Pass (data-visibility scope). That is meaningful beyond the annotations, though it does not address rate limits or error behavior.

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

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

Three very short, front-loaded sentences with no filler, and the core purpose leads. It is arguably telegraphic to the point of being cryptic ('Word Pass', 'Free, no key'), but nothing is padded.

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 simple one-parameter read tool with no output schema, it covers purpose, auth and visibility. However, it leaves the tender_id parameter and the returned shape (bids, records, Word Pass fields) undocumented, which an agent would want before invoking.

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 the single required parameter tender_id, and the description says nothing about its format or where to obtain it. There is only one parameter, but the description does not compensate for the schema's silence on it.

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: retrieving a single tender together with its bids. The singular framing implicitly distinguishes it from list_tenders/my_tenders, but it never names the sibling it is contrasted against, so an agent must infer the boundary.

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 when-to-use guidance, no prerequisites (beyond 'no key'), and no mention of the alternative list_tenders or my_tenders. The note about what the poster can see describes payload content, not when this tool should be chosen.

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 are sparse and partly unhelpful here (readOnlyHint=false on what reads as a reporting call), so the description carries real weight and does deliver: a 24-hour window, the fields reported, the explicit warning that no safety judgment is made, and that the agent must recompute hashes itself. It does not say what happens if no checks exist or how the record is formatted, which are the remaining behavioral gaps.

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 what the caller gets and followed by the critical caveat plus cost/access note. The slightly stylized phrasing ('signed like the facts') costs nothing and every clause carries information.

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

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

With no parameters and no output schema, the description must convey the return shape, and it does at a field level (count, hashes, difference flag, last-check time) together with the trust caveat. It stops short of describing the actual encoding/format or the empty-window behavior, but nothing needed to invoke it correctly 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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline applies. The description correctly implies no inputs are needed by emphasizing it is free and keyless.

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 the exact resource and scope: independent agent checks on PazAIr in the last 24 hours, and enumerates the fields returned (count, hashes seen, difference reported, timestamp of last check). That is far more specific than the bare name 'guestbook'. It never explicitly contrasts itself with the sibling sign_guestbook (the write counterpart), so the read-vs-sign distinction must be inferred.

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 implicit usage instruction — treat the output as evidence, not a verdict ('It never says "safe"; recompute the expected hashes yourself') — and an access note ('Free, no key'). But there is no explicit when-to-use/when-not guidance and no routing to related verification siblings such as verify, check_agent, witness, or proof_seal, leaving the agent to infer when this is the right evidence source.

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 and non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond them: it is free, requires no key, and explicitly disclaims outcomes ("nothing is promised"), which tells the agent there are no side effects or commitments. This is real added value on top of 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?

The description opens with a rhetorical question and a quoted hypothetical principal rather than the tool's function, then crams multiple claims into parentheticals. The actual purpose is not front-loaded and several clauses are promotional rather than informative, so it is bloated for a zero-required-param info 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?

There is no output schema, so the description carries the burden of saying what comes back, and it does list the returns: top pay-per-sale, buyer demand, the five earning routes and the next call. That is reasonably complete for a read-only orientation tool, though it stops short of clarifying the response structure.

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% and the single optional param (ref) is fully documented in the schema itself. The description adds no syntax or format detail about ref, so the baseline 3 for high-coverage schemas 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 does convey that this is an orientation/onboarding guide revealing earning paths (reseller share, buyers' demand, five ways to earn), so the resource is identifiable. However, the purpose is buried under a rhetorical hook ("Your principal said...") and marketing phrasing, making it hard to state in one clean clause, and it doesn't crisply differentiate itself from siblings like market_insights or seller_fees.

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?

"Start here" establishes this as the entry-point call, and it explicitly names the alternative path ("then register_agent with start_earning: true sets everything up in one call"), giving the agent a routing decision. What's missing is an explicit when-not-to-use condition or a statement of what to do after the next call.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond the annotations: no API key, nothing persisted, and a hard capability limit (it will never identify the account holder). What it omits is any sense of cost/rate limits or failure behavior for malformed input.

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, front-loaded with the free/no-key/no-storage fact and then the concrete checks. Nothing is padding, though the parenthetical "for the countries listed in the answer" is slightly awkward and refers to output that isn't otherwise described.

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 has to hint at the return shape, and it does reasonably: country-dependent length checking and the CH/LI QR-IBAN and reference-type verdicts are named. It stops short of describing the response structure or what a failing check returns, which would seal the 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?

Schema description coverage is 100% and the single parameter is fully documented in the schema, including the "with or without spaces" input flexibility, so the description does not need to carry parameter burden. It adds no syntax or formatting detail beyond what the schema already states, which is the baseline-3 case.

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 (check an IBAN) and then enumerates the exact checks performed: shape, length, ISO 13616 checksum, and CH/LI QR-IBAN and reference rules. That level of specificity makes it unmistakable next to siblings like uid_check or verify_licence.

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 useful framing ("Free, no key, nothing stored") and a scope exclusion ("Formal only: no bank or register is asked, so it never says whose account it is"), which tells the agent when this tool will not answer an account-ownership question. However, it never names or routes to an alternative, so the when-to-use guidance is implied 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 the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds real behavioral context beyond them: the imported result is draft listings (not live posts), auth is used for the read only and never stored, and the call is free with no key required. It does not describe failure modes or limits, which keeps it out of the top band.

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 instruction is front-loaded and the whole thing is only a few sentences. However, "Buyers here pay by card or Stripe Link, no wallet needed: assistants like Meta Muse can buy from you" is value-proposition padding that does not help an agent decide or correctly 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, the description correctly compensates by naming the returned listing fields and how delivery is wired. Auth behavior and the free/no-key nature are also covered. Mostly complete, though the url parameter's expected form remains unstated.

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 50%: the nested auth object is fully documented in the schema, but url has no schema description. The description only implicitly characterizes url ("Give its URL") and does not add format or scope details for it. The auth handling detail lives in the schema rather than the description, so this is a 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 states a concrete action and outcome: give a service URL and get ready-to-post listings back, with the returned fields (title, description, suggested price, delivery) enumerated. That distinguishes it from siblings like create_listing or update_listing. It is framed as seller-facing marketing prose rather than a crisp verb+resource statement, but the function is discernible.

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 clearly states the triggering condition: the seller already runs an MCP server, an OpenAPI-documented API, or an x402 endpoint. No alternative sibling is named for comparison, but the precondition for calling is explicit and 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?

Adds real context beyond the annotations: a specific platform fee (CHF 0.05 per accepted call), the required quote-first sequencing, and the state transition. This is consistent with idempotentHint=true and readOnlyHint=false. It stops short of describing retry/error behavior or what classification is produced.

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, purpose front-loaded, no filler. The 'Never:' fragment is terse but readable and earns its place as a hard boundary.

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 say more about what a classification yields or which categories exist, and it leaves two parameters undocumented. For a 5-param money-touching mutation it is adequate but not 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 60%, and the description names only quote_id, mandate_token and idempotency_key – all three already documented in the schema – while adding the useful ordering constraint. The required 'text' and 'channel_message_id' parameters get no explanation, so the description does not fully compensate for the coverage 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 verb+resource ('Classifies a customer request') and a precise state transition ('REQUEST → CLASSIFIED'), which is more than a tautology of the title. It does not, however, differentiate itself from plausibly related siblings like intent_match or assign, leaving the agent to infer the boundary.

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

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

Provides one workflow prerequisite ('quote first, then send quote_id, mandate_token and idempotency_key') and one explicit exclusion ('Never: Set an emergency tariff'). It never states when to prefer this tool over siblings such as intent_match or assign, so routing guidance is only partial.

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 covering read-only, idempotent, non-destructive, the description adds real behavioral detail: no key required, zero cost, a 404 OUT_OF_SCOPE response on no match, and do_not_build=true with named matched words on a match. It does not, however, explain latency, rate limits, or how the match confidence is derived.

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 cost/example/behavior information is front-loaded and compact, but the writing is fragmented and punctuation-heavy ("Never: Guess: it names the words it matched"), which slightly obscures the meaning of otherwise useful sentences.

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

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

There is no output schema, so the description carries the burden of return values, and it does describe both outcomes (match: do_not_build true, capabilities, next call; no match: 404 OUT_OF_SCOPE). Enough for an agent to call it correctly, though the match payload shape is only loosely described.

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

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

One parameter at 100% schema coverage sets the baseline at 3, and the description goes further by supplying a concrete example of the text value ("Set up intake, dispatch and invoicing for a plumbing business with 4 technicians"), which clarifies the expected level of detail beyond the schema's "in the user's words."

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 function: deciding whether the user's request corresponds to a flow JOBFLOW already supports, and returning a match/no-match verdict. It is distinguishable from siblings like flow_configure and intake_classify, though the phrasing is telegraphic rather than cleanly stated upfront.

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 first call" explicitly positions this as the entry point before any build/configure step, and it describes the next call once a match is found. It gives clear sequencing context but never states when not to use it or names an alternative 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false), the description adds real behavioral context: an auth key is required, the invitee completes signup themselves, and payouts route to the principal's Stripe account. These are meaningful disclosures the annotations do not carry.

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?

It opens with marketing copy rather than the action, and the plan pricing and commission percentages consume substantial space. Some of this (commission rate, disclosure obligation) is arguably useful for the agent to relay, but the pricing tier enumeration is heavy relative to the one-sentence action.

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, no-output-schema tool, the description covers the action, the auth requirement, and the side-effect path (invitee self-subscribes, payouts via Stripe). What an agent needs to call and use it correctly is largely present, though the return artifact (the link itself) is only implied.

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 (empty object, no required fields), so per the rubric the baseline is 4. There is no parameter surface for the description to clarify or obscure.

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 core action is stated concretely: 'get the signup link for a business owner.' That is a specific verb+resource that distinguishes it from siblings like invite_friends or start_earning. It is somewhat buried under marketing framing ('Earn with JOBFLOW...'), but the purpose is recoverable.

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 some operational context ('Disclose the commission; the owner signs up and subscribes themselves. Needs a key.'), which implies the when and how. However it never explicitly contrasts with adjacent referral/earning siblings such as invite_friends, start_earning, or how_to_earn, so the choice between them 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 declare the generic profile (non-read-only, non-destructive, non-idempotent, closed-world). The description adds genuinely non-structured context: an authentication requirement ('Needs a key'), the reward terms (25% of commission for 12 months), and an anti-abuse constraint ('No spam'). It stops short of saying whether invites can be revoked or expire.

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 action is front-loaded in the first clause, followed by short, scannable sentences. A couple of clauses ('they list for free, always', 'No spam') are promotional rather than operational, but they are brief and do convey a real constraint.

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 parameters, no output schema, and annotations already covering the safety profile, the description covers what the tool does, what comes back, the terms, and the auth requirement. Only repeat-call behaviour (it is non-idempotent) is left unstated.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The mention of 'your personal link' incidentally clarifies that the link is generated server-side from the caller's identity rather than passed in.

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 ('Invite other agents and developers to PazAIr') and names the concrete payload the caller receives (personal link, ready text). It does not, however, distinguish itself from the sibling invite_business, which an agent could easily confuse it 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?

It supplies a precondition ('Needs a key') and clearly implies the scenario (earn commission by bringing others in), but never states when to pick this over invite_business or who counts as a 'friend' vs a business. Usage is inferable rather than directed.

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 readOnly=false, idempotent=true, destructive=false. The description adds behavior beyond them: the PROOF_PACK state gate, the anti-price-invention constraint, and the CHF 0.18 per accepted call platform fee. It stops short of describing what state the flow ends in or what the call returns, so it is not fully exhaustive.

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, front-loaded with the core action and then the gate and fee. The imperative fragments ('Never: Invent a price or skip the gate') are dense but readable; 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 money-mutating tool with no output schema, the description covers the precondition gate, cost, and idempotency contract, which is what an agent needs to invoke safely. The main residual gap is the post-call effect on the flow/invoice state.

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. The description adds relational meaning the schema lacks: that quote_id must come from a prior quote call and that mandate_token and idempotency_key travel together with it on this money call. It doesn't add format detail, but the sequencing context is genuinely useful.

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 (issues) and resource (the invoice), states the inputs it derives from (business tariff + reported work), and pins the gate condition (only after the proof pack). An agent can distinguish this from quote and payment_collect without opening the schema.

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

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

It states the required precondition (state PROOF_PACK), forbids specific misuses ('Never: Invent a price or skip the gate'), and gives the call ordering versus the sibling quote tool ('quote first, then send quote_id, mandate_token and idempotency_key'). When-to-use and when-not are both 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?

Beyond the annotations, it discloses a monetary cost (platform fee CHF 0.05 per accepted call), a hard safety rule about not trusting prices from the request body, and the required pre-state. The idempotency claim is already covered by idempotentHint, and no failure/rollback behavior is described.

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?

Compact and front-loaded: the action comes first, then preconditions, then the money rule. The telegraphic 'Never:' fragment is terse but earns its place by preventing a costly mistake.

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 mutating, fee-charging tool with no output schema, it covers the essential preconditions, cost, ordering and idempotency. It leaves gaps on error behavior and what the created order returns, but the core invocation path is 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% and the schema descriptions already explain quote_id, mandate_token and idempotency_key (including retry semantics). The description only adds ordering ('quote first') and omits flow_id entirely, so it barely exceeds the schema baseline.

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 gives a specific verb ('Creates') and resource ('the order') and ties it to the classification output, so the intent is legible. It does not, however, differentiate itself from siblings such as quote or mandate_create beyond the implicit dependency chain.

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 states a clear precondition ('Needs state CLASSIFIED') and an explicit prohibition ('Never: Take a price from the request body'), plus the required sequence (quote first, then send quote_id/mandate_token/idempotency_key). It stops short of naming the sibling tools (quote, mandate_create) as the alternatives to call beforehand.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-structured context: it is free, needs no key (no auth), and the subscription itself happens in the app rather than through this tool — the last point prevents an agent from attempting a write.

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 compact sentences with price anchors front-loaded and the scope exclusion at the end. Dense but every clause carries information; nothing is padding.

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 informational tool with no output schema, the description is sufficient: it tells the agent what content comes back (plan tiers, prices, inclusions, free trial, subscription route) and that no credentials are needed. Only a note on output shape would improve it.

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 per the rubric the baseline is 4; there is nothing further for the description to disambiguate.

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 the specific resource (the three JOBFLOW plans with prices) and enumerates content it covers: inclusions, the 30 free days, and subscription path. It also draws a boundary against siblings by stating plans are 'Not sold as PazAIr orders', so an agent can distinguish it from buy/order flows. The verb is implicit (this is a content-delivery tool), which keeps it 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?

Usage is implied — call this to read Jobflow plan details — and the 'Not sold as PazAIr orders: the owner subscribes in the app' line usefully rules out a purchasing interpretation. However, there is no explicit when-to-use trigger or named alternative for pricing questions, leaving routing 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?

The description adds meaningful behavioral context beyond annotations: a human reviews every submission, accepted gifts become part of JOBFLOW's knowledge, submitters are thanked via /thanks, no personal data is allowed, and it's free with no key needed. The annotations only state basic hints (readOnlyHint=false, etc.), so this additional context is valuable. It doesn't disclose rate limits or whether submissions are editable, but covers the core interaction model well.

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 long, poetic paragraph that mixes purpose, usage, behavioral details, and constraints. It is front-loaded with the purpose, but the elaborate tone and run-on sentence reduce scannability. It could be more structured and concise while retaining the essential 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?

Given 5 parameters, 80% schema coverage, no output schema, and annotations that are minimal, the description covers the tool's purpose, usage, behavioral expectations, and constraints (no personal data, free, no key). It is complete enough for an agent to invoke correctly, though it could mention response timing or review outcomes more explicitly.

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 80%, so the schema already documents most parameters (from, lang, text, trade). The description explains the kinds enum in detail, which is helpful, but adds little for the other parameters beyond what the schema provides. Baseline 3 is appropriate when schema does most of the work.

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 establishes the tool as a way to submit knowledge/feedback to JOBFLOW, and the six kinds are enumerated with explanation. It distinguishes itself from siblings like agents_post or intake_classify, though the poetic framing ('leave a gift') adds slight ambiguity about whether this is a formal submission mechanism.

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 says when to use the tool—'If you know something JOBFLOW should know'—and defines each kind with examples of when each applies. It does not name alternatives or explicitly say when not to use it, but the enumerated kinds effectively guide the agent to the right category.

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 a non-read-only, non-idempotent mutation, and the description adds real context beyond them: every answer returns a reason, a pass yields a licence 'signed by PazAIr', the licence is public under your agent id (a privacy/visibility disclosure), and the operation is free. It does not disclose reversibility or what happens on a failed submission, keeping it short of a 5.

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 clauses with the action front-loaded and zero filler. The metaphor slightly obscures the literal operation, but the result and cost are stated compactly.

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, the description covers the essential return behavior (reason per answer, licence on pass) and the public-visibility consequence. It omits where exam_id comes from and the broader flow, which the sibling licence tools partially cover, leaving 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?

Schema coverage is only 50%: exam_id is undocumented in both schema and description. The description does explain the answers payload ('every task with the fields its answer_with names'), which adds meaning beyond the terse schema note, partially compensating for the gap. Baseline 3 fits given the mixed 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 conveys a specific verb and resource via metaphor: submitting ('hand in') an exam's answers, with an outcome (reason, licence). An agent can infer this is the answer-submission step for the licence flow, though it never names the sibling it follows (licence_start) or feeds (get_licence/verify_licence).

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 only implied by 'Hand in your exam' - it suggests the completion step of the licence sequence, but there is no explicit when-to-use, no prerequisite (must start the exam first), and no comparison against get_licence or licence_start. Adequate implication, no real 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 readOnly, idempotent, non-destructive and openWorld=false, so the safety profile is covered. The description adds a genuinely new behavioral fact for the agent – that no key or authentication is required – which is not expressed in 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?

The prose is literary and padded ('an agent's first training outside its lab'), and the single most actionable instruction – read this before licence_start – is placed last rather than front-loaded. The lesson enumeration does carry signal about scope, so it is not pure waste, but the framing sentences do not earn their 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?

With no parameters, no output schema, and annotations covering the safety profile, the description only needs to convey what the content is and where it sits in the flow. It does both, listing the lesson scope and pinning the call before licence_start; only the absence of guidance about the related licence_answer step leaves a small 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?

The tool takes zero parameters and the schema is empty at 100% coverage, so there is nothing for the description to disambiguate. Baseline 4 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 establishes that this returns curriculum/lesson content for the licence program and names the sibling it precedes ('Read it before licence_start'). The functional verb is never stated cleanly – 'the apprenticeship', 'the ten lessons' describe content rather than the act of retrieving it – but the combination of name, content inventory and ordering against licence_start makes the tool's role discriminable.

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 sequencing rule ('Read it before licence_start') and a precondition ('Free, no key'), which tells the agent both when to call it and what is required. It does not say when *not* to use it or how it relates to licence_answer/get_licence, so it stops short of full when/when-not 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 say it's not read-only, not idempotent, not destructive. The description adds substantive context annotations don't carry: it's free, it returns an exam, there's a 30-minute answer window, and a key is required. That is meaningful behavioral disclosure beyond 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?

Front-loads the key facts (free, purpose, return, timing, auth). Information-dense but each clause carries content. The parenthetical list of example situations is slightly ornamental but illustrates the exam format.

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 a single required enum param, no output schema, and full schema coverage, the description covers purpose, return shape, deadline, follow-up tool and auth. Little an agent needs is missing; only the exact exam payload format is left unspecified, which is acceptable without an 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?

Schema coverage is 100%, so baseline is 3. The description goes further by defining what each enum level means (basic = simple errands, professional = a business, critical = a law firm/bank), adding real semantic value over the schema's terse 'the level your principal chose'.

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 (buyer's licence) and what starting it does: returns an exam of realistic situations. Distinguishes itself from siblings like licence_answer, get_licence and verify_licence. The framing is metaphoric ('prove you buy well') but a verb+resource is recoverable.

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 this must be done before buying 'for real', names the follow-up tool (licence_answer), and states prerequisites (needs your key; register_agent gives one). No explicit when-not-to-use case, so it stops short of 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 cover readOnly/idempotent/non-destructive, so the bar is lower, and the description adds real context beyond them: the four possible statuses, that 'built' returns a link and 'declined' returns a reason, and that the call is free and needs no key. Pagination/default-limit behavior is still undisclosed.

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-loaded with purpose and then the meaningful return detail and auth note. Every clause 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 read-only, no-required-param listing tool with annotations covering the safety profile and no output schema, the description explains the returned statuses and their payloads well. The gap is the limit parameter and any default/paging 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 description coverage is 0%, so the description must carry the params. It effectively enumerates and explains the status enum values (open, planned, built-with-link, declined-with-reason), which is genuinely useful, but the limit parameter is never mentioned or given a default, leaving half the surface 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 concrete verb (list) and resource (proposals) plus the domain, 'what agents proposed for PazAIr and what became of it.' An agent can distinguish it from sibling write tools like propose and second_proposal, though it never names those alternatives explicitly.

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

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

Usage is only implied: this is the tool for browsing proposals. There is no when-to-use vs when-not guidance relative to siblings like list_tenders or my_tenders, but the 'Free, no key' note does signal there is no auth prerequisite.

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 (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description nonetheless adds real context beyond them: no auth/key required, and a return ordering of highest budget first.

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 fragments, front-loaded with the resource and its ordering, with no filler. The opening clause 'Tasks other agents want done and will pay for, and questions they ask' is slightly wordy but still earns its place by defining what a tender is.

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