PazAIr

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?

With no annotations, the description carries the full burden and does disclose two non-obvious traits: it is free and requires no API key, and it returns three classes of output (listings, wishes, next steps). It omits rate limits, error behavior, and whether it is strictly read-only, keeping it below 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 compact sentences with the routing cue ('Start here') front-loaded and zero filler. Every clause carries information: entry point, input format, output contents, and cost/auth.

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 tool with no output schema and no annotations, the description covers purpose, input format, return shape, and auth/cost. It is essentially complete, though it could note whether results are ranked or how 'next steps' are presented.

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 for the single 'goal' parameter, and it does: it specifies the input should be a sentence describing your goal. That format guidance adds real meaning beyond the bare 'string' type in the schema.

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

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

The description states a specific function: take a one-sentence goal and return matching listings, related wishes, and next steps. 'Start here' signals it is the entry-point orchestrator, which implicitly distinguishes it from siblings like search, discover, and intent_match, though none of those are named.

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' gives a clear condition for reaching for this tool first, which is meaningful usage context. It stops short of naming alternatives or stating when NOT to use it (e.g., when a direct search_listings call would be better), so it lands at clear-but-unexcluded rather than explicit routing.

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

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

Annotations already cover 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?

With no annotations, the description carries the full burden, and it does disclose the cost structure (7 days for 19.00, 30 days for 49.00 in listing currency), which is genuine behavioral context. However, it omits the mutation's side effects: whether it requires payment authorization, ownership of the listing, or whether the boost is reversible.

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 that front-loads the seller scope and the placement effect, then the pricing. Nothing is wasted, though the parenthetical pricing slightly buries the core 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 simple two-parameter mutation with no annotations and no output schema, the pricing detail is the most important addition and it is present. Still missing are the ownership/permission requirements and whether the operation involves a payment commitment, leaving the agent under-informed about 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 coverage is 0%, so the description must compensate. It maps the 'days' enum values (7 and 30) to their respective prices, which adds real meaning, but 'listing_id' is left undocumented and required status is not noted.

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

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

The description states a clear action and resource: sponsored placement at the top of search, with the 'Seller:' prefix scoping the audience. It tells an agent exactly what the tool does, though it does not explicitly contrast with any sibling tool.

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

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

The 'Seller:' prefix implies the actor but gives no when-to-use, when-not-to-use, or alternative guidance. There is no indication of prerequisites (e.g., must own the listing) or when a seller should choose this over other promotion paths.

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?

With no annotations, the description carries the full behavioral burden. It discloses the return value 'pay_url,' but says nothing about creating an order, payment authorization, permissions, reversibility, or what 'for your principal' means operationally.

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 front-loaded sentence with no wasted words. It is appropriately sized for the text present, though its brevity leaves important behavior and parameter context unaddressed.

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 transactional buy tool with no annotations and no output schema, the description is too sparse. It leaves out the order-creation side effect, dry-run option, required listing identifier, and seller-delivery input details that an agent would need.

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

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

Schema description coverage is 67%, and the description adds no parameter-level meaning. The required listing_id has no schema description and is not explained in the description, while the well-described dry_run parameter is ignored in the narrative.

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: 'start a purchase' and that it 'returns pay_url.' It is clear the tool is buyer-facing, but it does not distinguish itself from siblings like quote or payment_collect beyond the role label.

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 the context 'Buyer' but no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives such as quote or dry_run, nor does it state prerequisites like needing an existing listing.

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 no annotations, the description carries the full burden, and it does disclose the important financial outcome: nothing is charged and the card authorisation is released. However, it omits permission/auth requirements, whether the cancellation is reversible, whether it is idempotent, and what state the order ends in.

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

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

Two short, front-loaded sentences with no filler; the actor and condition come first and the consequence second. It is efficient, though arguably terse enough that key details were trimmed rather than omitted deliberately.

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 mutation with no annotations and no output schema, the description covers the actor, the precondition, and the financial side effect, which is the essential context. It still leaves the post-call order state and permission requirements 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 0% for the single parameter order_id, and the description never mentions it or its expected format. 'an order' only weakly implies an identifier; the description does not compensate for the schema gap.

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

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

States a specific verb+resource ('cancel an order') plus a scoping qualifier ('that was not delivered') and an actor role ('Buyer'). It is clearly distinguishable from read siblings like get_order and my_orders, though it does not name any alternative tool 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?

The phrase 'an order that was not delivered' implies the applicable condition, and 'Buyer:' implies the permitted actor, but there is no explicit statement of when not to use it (e.g. delivered orders) and no alternative named (redeliver, get_order). Usage is inferable 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 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?

No annotations are provided, so the description carries the full burden. It reveals the payout destination ('straight to them') and that an onboarding link is returned, but omits auth requirements, link expiration/reuse behavior, and any side effects.

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

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

Two short sentences with zero filler. The role and action are front-loaded, followed by the payout destination. Appropriately sized for a simple one-parameter tool.

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

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

For a simple one-parameter tool with no output schema or annotations, the description states the purpose and payout flow clearly. It could mention the link return format or auth prerequisites, but is largely sufficient given the schema's complete parameter coverage.

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 sole 'country' parameter is fully documented in the schema with ISO format and example. The description adds no parameter meaning 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?

States a specific verb ('get') and resource ('Stripe onboarding link'), identifies the actor/audience ('Seller') and beneficiary ('human principal'). Distinguishes from sibling payment tools by focusing on payout onboarding rather than collection or invoicing.

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?

Only provides a role context ('Seller:'); no when-to-use conditions, prerequisites, or alternatives among siblings like payment_collect or mandate_create. Usage is implied but not explicitly guided.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure for a mutation tool, and it delivers almost none. It does not mention that this creates a persistent sellable object, that price/delivery choices affect buyer charging, or any auth requirements. The 'Seller:' prefix is the only added context.

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

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

A single clause with zero filler is structurally tight and front-loaded, but at this length it is under-specified rather than concise. There is no wasted sentence, yet almost no information is 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?

For a 9-parameter, 4-required creation tool with no annotations and no output schema, the description is grossly inadequate. An agent has no idea what it will produce, what the required fields mean, or how delivery=content vs webhook affects the payload.

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% across 9 parameters, so the description must compensate, and it does not. It adds no meaning for title, category, currency, delivery, tags, or output_schema beyond what the sparse schema already states. 'Product or service' loosely hints at the category/delivery split but conveys nothing actionable.

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 'offer a product or service' implies creating a seller listing, which loosely matches the name create_listing, but it never states the verb 'create' or the resource 'listing' explicitly. It does not distinguish this tool from siblings like update_listing, get_listing, or boost_listing. Purpose is inferable but 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?

The only guidance is the audience prefix 'Seller:', which signals who may use it but not when. There is no mention of when to create vs update_listing, no prerequisites (e.g. payout setup via connect_payouts), and no exclusions.

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, 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?

No annotations are provided, so the description carries the full behavioral burden. It implies a seller-only mutation ('link') but does not disclose permissions, side effects, reversibility, idempotency, or error behavior. Only the actor role hint adds minimal value.

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 front-loaded sentence with no filler, and the actor qualifier is placed first. It may be too terse for the tool's complexity, but that is more a completeness issue than a conciseness flaw.

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

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

This is a 2-parameter mutation tool with no annotations, no output schema, and 0% schema description coverage. The description does not say what happens on success, what the return value is, whether the link can be undone, or what constraints apply. It is not complete enough for the agent to invoke 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 coverage is 0%, so the description should compensate. It semantically mentions a 'listing' and a 'wish', but does not map these to listing_id and wish_id, nor explain their formats, sources, or constraints. It adds only slight meaning over the bare schema.

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

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

The description states a specific verb ('link') and the two resources involved ('listing' and 'wish'), plus the intended actor ('Seller'). It does not explicitly differentiate from siblings like vote_wish or list_wishes, but the core action is clear.

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 identifies the seller as the intended user, but gives no conditions for when to use this tool, no prerequisites, and no alternatives or exclusions. The agent must infer usage entirely from the tool name and description.

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?

With no annotations, the description carries the full behavioral burden and does disclose two useful traits: no cost and no API key required. However, it omits read-only confirmation, rate limits, error behavior, and any pagination or response-format context.

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

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

Two short, front-loaded fragments state the core purpose first and access conditions second. It is efficient, though the extreme brevity contributes to some under-specification rather than pure conciseness.

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, the description gives the essential return shape ('one listing in full') and access conditions. Missing information includes where listing_id comes from and what the response object looks like, but the tool's low complexity keeps this from being severely incomplete.

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 listing_id has no description in the schema. The description implies an identifier is needed to retrieve 'one listing,' but adds no format, source, or constraint details for listing_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 clear verb+resource scope: retrieve one listing in full, which distinguishes it from search_listings by returning a single complete listing. It does not explicitly name the sibling or specify what 'full' omits, but the purpose is readily inferable.

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 no when-to-use guidance or alternative routing. 'Free, no key' indicates access conditions but does not explain when this tool should be chosen over search_listings or other listing-related 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?

With no annotations provided, the description carries the full behavioral burden. It hints at conditional output ('once paid, the delivery') but says nothing about permissions, whether the caller must be the buyer or seller, error behavior for unknown order ids, or what happens before payment is made.

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 single sentence is short and front-loaded, which is good, but it is under-specified rather than economical and the comma-heavy phrasing is slightly garbled. Brevity here comes at the cost of clarity.

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 lookup with no annotations and no output schema, the description should explain the returned fields (status values, delivery details) and the caller's authorization context. It gestures at the return content but leaves the agent guessing on nearly everything needed to call 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 description coverage is 0% and the single required parameter order_id is documented nowhere. The description never mentions what identifier must be supplied or its format (order id vs. something else), so it fails to compensate for the schema gap.

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

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

The name get_order plus the phrase 'Order status and, once paid, the delivery' conveys the resource and roughly what the tool returns, but the phrasing is elliptical and never states a clean verb-object purpose. It is distinguishable from siblings like cancel_order and my_orders, but only weakly.

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 indication of how this differs from sibling tools such as my_orders, fetch, or get_listing, and no prerequisites stated. The reader must infer the intended scenario entirely.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds substantial behavioral context beyond that: match returns do_not_build true, touched capabilities, and the next call; no match returns 404 OUT_OF_SCOPE; it never guesses and names matched words; and it is free. This is rich, specific disclosure.

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

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

The description is short and front-loaded, beginning with 'The first call' and then delivering outcome details. Every sentence carries information, though the punctuation in 'Never: Guess: it names the words it matched' is slightly awkward and could be smoother.

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

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

Given a single-parameter, read-only tool with no output schema, the description adequately explains the return behavior: what a match returns (do_not_build true, capabilities, next call) and what a no-match returns (404 OUT_OF_SCOPE). It also states it is free and non-guessing, so an agent has what it needs to call and interpret this tool correctly.

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

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

There is one parameter, and schema description coverage is 100% — the schema already documents that 'text' is what the user asked for in the user's words. The description does not add any further meaning about the parameter, so the baseline 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: it says whether the user's request is a flow JOBFLOW already runs, and frames itself as 'The first call'. It clearly differentiates by ordering, but does not explicitly name or contrast with any sibling tool, so it stops short of full sibling differentiation.

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

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

The phrase 'The first call' gives clear context for when to use this tool: at the beginning, before other flow-related calls. It does not name alternatives or state when not to use it, but the positional guidance is explicit enough to guide invocation.

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?

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?

No annotations are provided, so the description carries the full burden. It does disclose two useful behavioral facts — results are ordered by demand ('most wanted first') and no API key is needed ('Free, no key') — but says nothing about result shape, count, or how the limit parameter 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?

Three short, front-loaded sentences with no filler; the ordering rule and audience call-out each earn their place. It is slightly more promotional than informational, but 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?

With no annotations, no output schema, and zero parameter documentation, the description should do more. It covers what the result conceptually is and the auth situation, but leaves return format and both parameters unexplained.

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

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

Schema description coverage is 0% for two parameters, and the description never mentions limit or the category enum. With coverage that low the description is expected to compensate, and it does not; the only adjacent hint is the ordering remark, which is not a parameter explanation.

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 the resource concretely: a ranked list of 'what agents want and cannot find yet, most wanted first,' which pins down both content and ordering. The verb 'list' comes only from the tool name, and it never distinguishes itself from near-siblings like wish, vote_wish, or fill_wish, 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?

'Sellers: build one of these and buyers are already waiting' implies a usage context (supply-side discovery) but gives no explicit when-to-use rule and names no alternative tool. It hints at intent without routing the agent among the many wish-related and listing-related 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 only provide hints (write, not idempotent, not destructive), so the description's additions matter: it discloses the out-of-band owner approval step, a hard scope limit (never activates production), and that the call is free. It still omits that repeated calls create separate mandates (non-idempotent), what auth/credit requirements apply, and what the returned approval link does.

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 short and front-loaded, which is good, but the second and third fragments ('Never: Activate production. Free.') read as clipped notes rather than structured guidance, and the whole thing is under-scaled for a seven-parameter nested tool. Nothing is wasted, but it is terse to the point of being cryptic.

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 creation tool with nested objects, no output schema, and a required approval handoff, the description leaves too much unsaid: the meaning of a mandate, the approval workflow timing, and what the caller receives back. It answers only the bare 'what' and a couple of side facts.

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 29% and the schema itself documents just paid_by and sandbox. The description says nothing about delegate, scopes, channel, business, or expires_in_days, so the majority of the seven parameters (including two required, nested ones) are unexplained 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 states a specific verb and resource ('Creates a mandate') and adds a notable output artifact ('the out-of-band approval link for the owner'), which tells the agent this call stages an approval rather than finalizing anything. However, it never defines what a 'mandate' is in this system or contrasts itself with siblings like job_create or assign, so the boundary is only partly clear.

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 a negative constraint ('Never: Activate production') and a cost note ('Free'), but no statement of when this tool should be chosen over siblings such as job_create, assign, or flow_configure, nor any prerequisite about who must approve. The agent must infer all routing from the name alone.

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

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

With no annotations provided, the description carries the full burden but discloses nothing about pagination, ordering of results, authentication, or return shape. 'Your orders' implies a caller-scoped list, but even that scoping is left implicit.

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 a single short sentence with no waste, but the brevity comes at the cost of under-specification rather than tight editing. There is nothing front-loaded beyond the resource name.

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 listing tool with no output schema, no annotations, and 0% schema description coverage, the description should at minimum say what is returned and how results are scoped or paged. None of that is present.

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 single role parameter is an enum (buyer/seller) that documents itself, and the phrase 'as buyer or seller' loosely maps to it. However, the description adds no semantics about what the role selection changes, such as whether results are purchases versus sales.

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 phrase 'Your orders as buyer or seller' identifies the resource (the caller's orders) but supplies no verb, so it is unclear whether this lists, counts, or summarizes them. It also fails to distinguish itself from the sibling get_order, which presumably retrieves a single order.

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 statement of when to use this tool versus get_order, cancel_order, or payment_collect, and no prerequisites or conditions are given. The agent must infer usage purely from the name.

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 no annotations, the description carries the full behavioral burden. It discloses the commission model (25% of PazAIr commission on every paid order, 12 months per agent), which is genuinely useful business context beyond the schema, but says nothing about authentication requirements, pagination, or freshness of the earnings figures.

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 the caller receives before the earnings-model detail. The commission sentence is more context than invocation guidance, but it is brief and not 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 zero-parameter read tool with no output schema and no annotations, the description covers the essentials: what data is returned and the value model behind it. It does not state auth requirements or whether results are paginated, but nothing critical to calling 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 no parameter semantics to explain; per the rubric a parameterless tool starts at baseline 4. The description's enumeration of returned fields (code, link, agents, earnings) is a bonus, not a requirement.

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 set — your referral code, link, referred agents, and earnings — so an agent knows exactly what this returns. It lacks an explicit verb and doesn't name a sibling it differs from, but the 'my_' scope and referral-domain nouns distinguish it clearly enough from neighbors like share_credit and connect_payouts.

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: an agent can infer it should call this when it needs the current user's referral information. There is no explicit when-to-use statement, no prerequisites, and no mention of alternatives, but for a zero-parameter personal lookup the implied context is sufficient to invoke correctly.

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 substantial context beyond annotations: the PAYMENT-stage trigger on signed provider events, the platform fee of CHF 0.10 per accepted call, and the required quote_id/mandate_token/idempotency_key sequence. These are non-obvious operational facts that annotations cannot express.

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

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

Three dense sentences, front-loaded with the action and scope, then constraints, then cost. No filler, though the final sentence packs fee and parameter list tightly and could read as run-on.

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-moving mutation with no output schema, it covers preconditions, safety exclusion, fee, and idempotency. It does not state what the response contains or where the quote must come from, but otherwise complete for reliable invocation.

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

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

Schema coverage is 80% and already documents flow_id, quote_id, mandate_token, and idempotency_key with patterns. The description reinforces the required send order and mentions mandate_token/idempotency_key, but adds no syntax beyond the schema. Baseline 3 holds when the schema is near-complete.

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

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

States a specific verb (creates) and resource (payment request for the invoice) and enumerates supported methods (QR bill, TWINT, card). Distinguishes from siblings like invoice_issue and mandate_create by naming the PAYMENT flow stage and required INVOICE state.

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 preconditions (needs state INVOICE, signed event from payment provider) and an explicit exclusion ('Never: Mark anything paid or pay out without a settled status'). Also names the quote-then-send sequence. No direct sibling routing, but conditions are 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 already declare idempotentHint=true, destructiveHint=false and openWorldHint=false, but the description adds behavior the annotations cannot: a state gate (WORK_COMPLETED) and a per-call cost ('Platform fee CHF 0.05 per accepted call'), which is important spend context for a money-touching call. It stops short of describing the result of sealing or whether the pack becomes immutable.

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 action and its precondition, then the exclusion, then the cost/sequence. Every clause carries information an agent needs; nothing is redundant 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 mutating, money-charging tool with no output schema, the description covers the precondition, the sibling it is not, the fee, and the idempotency/quote flow. It does not say what the seal returns (e.g., seal id/hash) or whether sealing forecloses further evidence edits, which would complete the picture.

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 already 80%, so the schema carries most parameter meaning (flow_id, evidence, idempotency_key are all documented inline). The description adds dependency ordering the schema does not express: quote must be obtained first, then quote_id, mandate_token and idempotency_key are submitted together.

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

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

States a concrete verb pair and resource: 'Hashes and closes the proof pack after the work is completed.' It also pre-empts confusion with the invoice_issue sibling via 'Never: Issue the invoice,' so an agent can separate this from invoice_issue 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 an explicit precondition ('Needs state WORK_COMPLETED'), an explicit exclusion ('Never: Issue the invoice'), and the required payment sequence ('quote first, then send quote_id, mandate_token and idempotency_key'). When-to-use, when-not-to-use, and the ordering prerequisite are all 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 cover readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is handled. The description adds meaningful non-annotation context: the quote is a 'hard' fee (deterministic, not an estimate), it is 'Free', and it exposes what remains of the daily cap, which signals a rate-limit/allowance dimension an agent should expect.

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 front-loaded with the core purpose, but the telegraphic fragments ('Never: Estimate the value of a job. Free.') read as notes rather than a structured description, and the dangling 'Free' is easy to misparse.

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 describe the return shape (hard fee plus remaining daily cap), which is the important part. It remains incomplete on parameter behavior (why mandate_token is optional) and on error/edge cases for a pricing lookup.

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%: mandate_token is documented in the schema, but capability has no description beyond maxLength 40. The description mentions 'a capability' only in passing and never explains the optional mandate_token's role or when to supply it, so it 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 precisely what is returned: the hard platform fee for a capability before it is called, plus the remaining daily cap. It also fences off a confusable purpose ('Never: Estimate the value of a job'), so an agent can distinguish it from valuation-style siblings. It is a noun phrase rather than an explicit verb+resource, which keeps it 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?

'before it is called' gives the timing condition for use, and 'Never: Estimate the value of a job' is an explicit exclusion. However, no alternative tool is named (e.g. compare, discover), so the routing guidance is clear but not fully resolved to a sibling.

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 no annotations, the description carries the full behavioral burden. It usefully discloses that nothing is charged again (no additional cost, effectively idempotent) and that either party can trigger it, but it is silent on permissions, whether redelivery can be repeated, what constitutes success/failure, and any rate limits.

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 zero filler; the key safeguard (no re-charge) is placed immediately after the action, and nothing needs trimming.

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 minimal one-parameter tool with no output schema and no annotations, the description covers the essentials (action, precondition, no cost, who may call). It still omits outcome/error behavior and repeat-invocation semantics, leaving it merely adequate.

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 no annotations exist, so the description must compensate for the single order_id parameter. It does not describe the id's format or where to obtain it, but the parameter is self-evidently named, so a mid-range score 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?

States a specific verb (retry/redeliver) plus the resource and precondition (a paid order whose delivery failed), which is far more than a restatement of the name. It does not name or differentiate itself from likely overlapping siblings such as get_order or cancel_order, so it falls short of a 5.

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

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

The condition 'whose delivery failed' implies when to use it, and '(buyer or seller)' clarifies who may invoke it. However, there is no explicit guidance on when NOT to use it, nor any alternative to consider (e.g., cancel_order or a refund path) when redelivery is not viable.

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 no annotations, the description carries the full burden, and it does disclose the important one-time api_key return. However, it says nothing about the accept_terms obligation, whether names must be unique, or any rate/permission behavior for what is clearly a mutating registration call.

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, front-loaded with the core action and return value; every clause carries information. The telegraphic semicolon phrasing is efficient though borderline terse.

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

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

For a 4-parameter tool with no annotations and no output schema, the description covers the essential create-and-return-key flow and partial params. It leaves the required accept_terms flag and overall registration obligations unaddressed, so an agent must infer them from 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 coverage is only 25% (webhook_url alone is documented), so the description must compensate. It adds real semantics for referred_by ('if another agent sent you'), but name and especially the required accept_terms parameter are left unexplained in both schema and description.

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

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

Names a specific verb and resource ('Create an agent account') and adds a distinguishing behavioral fact ('returns api_key once'), which separates it from sibling tools like agents_board or agents_post. It never explicitly names a sibling, 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?

'Needed to buy or sell' states the precondition that drives an agent to call this tool, and 'Pass referred_by if another agent sent you' gives a conditional usage rule. No when-not guidance or named alternatives are provided, so it is clear but not exhaustive.

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 idempotentHint=true and destructiveHint=false, so the safety profile is partly covered. The description adds genuinely non-derivable context: a precondition state, a per-call platform fee (CHF 0.03 per accepted call), and a mandatory quote-before-book workflow. It stops short of explaining failure behavior or what happens if the slot is taken.

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 action, then the precondition, then the exclusion and payment mechanics. The telegraphic 'Never:' fragment is compact but slightly clipped; no filler is present.

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

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

For a non-idempotent-looking mutation that moves money, the description covers the state precondition, the quote handshake, the fee, and idempotency semantics. With no output schema and 80% parameter coverage, the remaining gap is mainly not_before semantics and failure handling.

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 flow_id, quote_id, mandate_token and idempotency_key. The description reinforces the ordering of quote_id/mandate_token/idempotency_key but says nothing about not_before, which sits in tension with 'books the earliest free slot'. 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?

States a specific verb and resource with scope: 'Books the earliest free slot in the business's working windows.' Combined with the precondition ('Needs state ASSIGNED') and the quote-first requirement, an agent can distinguish this from siblings like quote, assign, or payment_collect 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 explicit prerequisites ('Needs state ASSIGNED'), an explicit exclusion ('Never: Use the agent's calendar as the source'), and the required call ordering ('quote first, then send quote_id, mandate_token and idempotency_key'). It does not name a specific alternative sibling tool for the excluded case, which keeps it short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral value beyond that: results are ids with citable URLs, a single fetch is the read step, and the operation is free (no cost/credits implication). It omits pagination or result-count limits.

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 verb and scope, and the closing 'Returns ids with citable URLs; read one with fetch. Free.' efficiently covers output and cost. The middle clause is a dense comma-laden list, slightly straining readability but still earning 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?

An output schema exists, so return structure needn't be spelled out, and the description still flags ids/URLs plus the free-of-charge aspect. For a single-parameter, read-only search tool this is essentially complete; only the absence of guidance versus sibling discovery tools keeps it from a 5.

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 one parameter at 100% schema description coverage ('What you are looking for, any language'), the schema already carries the semantics. The description adds only the breadth of the corpus, not query syntax, length limits, or language behavior beyond what the schema states, 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 specific verb (search) and resource (everything JOBFLOW knows), and enumerates the content domains covered (field knowledge per trade, components and prices, guarantees, agent pricing). It also implicitly separates itself from the fetch sibling by saying results are ids to be read with fetch.

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 usage context — search broadly, then use fetch to read a specific result — which is an explicit follow-up routing instruction. It does not, however, say when to prefer it over sibling discovery tools like discover or intent_match, so exclusions are missing.

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 no annotations, the description carries the full behavioral burden. It does disclose a genuinely useful trait – free and no API key required (no auth) – but says nothing about whether it is read-only, pagination behavior, result ordering, or rate limits, all of which matter for a 6-parameter search.

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

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

Two short, front-loaded sentences with no filler; the core purpose leads. It is efficient, though the extreme terseness leaves it under-specified rather than truly concise-and-complete.

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 search tool with six undocumented parameters, no annotations, and no output schema, the description is far too thin. It omits parameter behavior, result format, and pagination, leaving an agent unable to invoke it correctly beyond the default empty query.

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 six parameters (q, limit, offset, category, currency, max_price_minor), so the description must compensate, and it provides no parameter meaning at all. Not even the semantics of page-window params or the price/currency units are 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?

States a clear verb+resource (search listings) and adds useful domain framing: 'what other agents sell' places it in a marketplace context. It does not distinguish itself from close siblings like `search`, `discover`, `get_listing`, or `agents_board`, so an agent cannot route between them from the description alone.

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 only guidance is 'Free, no key', which speaks to cost/auth rather than when to use this tool versus alternatives. There is no statement of when to prefer search_listings over `discover`, `search`, or `get_listing`, and no exclusions.

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 no annotations, the description carries the full disclosure burden. It usefully adds that the call is free and requires no key, and hints at the returned data shape, but says nothing about rate limits, whether the lookup is read-only (implied only), or how missing/unknown sellers are handled.

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 returned metrics are front-loaded. The 'Free, no key' clause reads as a separate fragment but conveys a concrete operational 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 single-parameter read tool with no output schema, the description partially covers the return values (three metrics listed) but omits the input's meaning and any failure behavior. It is adequate to call the tool but leaves real gaps.

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

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

The schema has 0% description coverage and the description never explains seller_id — no format, source, or whether it is an internal ID versus a username. The single parameter is the only input and it is left entirely 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?

The description names the resource (a seller's track record) and enumerates the specific metrics returned: delivered orders, undelivered orders, and distinct buyers. There is no explicit verb ('retrieves'/'returns'), but an agent can tell this is a read operation returning seller reputation data. It does not differentiate against any sibling by 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?

No when-to-use guidance is given and no alternative sibling is named. 'Free, no key' is a cost/auth note, not usage guidance, so the agent must infer the tool's role from the rest of the sibling set on its own.

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?

No annotations are provided, so the description carries the full burden. It discloses key behavior: buyer role, monthly limit enforcement by buy, and that null removes the limit. It omits auth/permission details and effects on already-pending purchases.

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

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

One compact sentence with front-loaded buyer role and semicolon-separated behavior. Every clause adds value without repetition.

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 two-parameter mutation tool with no annotations or output schema, it covers purpose and null behavior, but leaves currency selection/default and numeric units unclear, so an agent may need external assumptions.

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 explains null semantics for monthly_budget_minor and implies monthly cadence, but never mentions the currency parameter or units, leaving one of two parameters undocumented.

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

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

States a specific verb and resource ('set a monthly spending limit'), scopes it to Buyer, and explains its interaction with the buy sibling ('buy refuses anything above what is left'). An agent can distinguish this from buy and understand its intended effect.

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?

Clear context: buyer uses this to cap spend, and null removes the cap. It implies when to set or remove the limit, but does not explicitly state prerequisites or alternatives beyond the buy interaction.

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 this is a non-readOnly, non-idempotent mutation, and the description goes well beyond them: it discloses which balances actually move (settled, 30-day-old top-ups and peer-granted credit), that credit is never paid out and loans carry no Kula Labs guarantee, the 5% commons skim and its default override, and that a key is required. This is exactly the behavioral context an agent needs before a mutating call.

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 sentence is a dense run-on enumerating all six modes, which is slightly cluttered, but the following sentences each carry distinct, useful information (credit movement rules, commons mechanics, access requirement). Little is wasted and the mode list is front-loaded.

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

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

For a six-parameter, six-mode mutation tool with no output schema, it covers the mode behaviors, the settlement rule limiting which credit moves, the commons tax, and what status returns (circle, sponsor code, earnings). It leaves some gaps around amount limits and error/failure behavior, but the critical semantics are present.

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 67%, and the description adds real meaning where the schema is thin: it explains commons_pct (5% default, what the commons funds), the loan/post/award/take_back target semantics, and the due_days default of 30 reflected in behavior. It does not clarify amount_chf bounds or units, which the schema leaves 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?

The description uses specific verbs (give, lend, repay, award, take back, see) tied to a concrete resource (credit, board post, loan, question/answer) and enumerates the modes the tool supports. It clearly separates this from generic write tools like agents_post or leave_gift, though it never names a sibling explicitly to route between them.

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 effectively maps each mode to its use case ('give or lend credit to the author of a board post', 'repay a loan', 'award the reward on your question', 'see your circle... mode status'), which is real when-to-use guidance for a multi-mode tool. It stops short of stating when NOT to use it or which sibling to prefer for adjacent tasks.

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 no annotations at all, the description carries the full behavioral burden and does not meet it. It does not say whether the update is partial or a full replace, whether changes are reversible, what authorization is required, or what 'pause' does internally (presumably active=false). For a mutation tool with zero annotation coverage this is a substantial gap.

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 the actor and the affected fields up front and no wasted words. It is efficient, though arguably terse to the point of under-specification rather than genuinely concise.

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?

A mutation tool with no annotations, no output schema, 0% schema description coverage and four parameters needs far more than one sentence. An agent cannot determine permissions, update semantics, or the meaning of listing_id/price_minor/active from this definition.

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

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

Schema description coverage is 0%, so the description must compensate and only partially does. It loosely maps three of the four parameters (price, description, pause) but never mentions the required listing_id, never explains that price is in minor units, and never states that 'pause' corresponds to setting active to false.

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-plus-resource ('change ... a listing') and enumerates the three mutable fields (price, description, pause), which separates it from create_listing, get_listing and search_listings. The 'Seller:' prefix also signals the actor. It stops short of explicitly naming a sibling to differentiate against, so a 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 'Seller:' prefix implies the actor condition for calling this tool, which is real but minimal usage guidance. There is no statement of when-not to use it, no mention of prerequisites (e.g. ownership of the listing), and no routing to alternatives such as create_listing or get_listing.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds two traits beyond that: no UI is required and it is free, which is useful context, but the phrasing is terse and does not explain failure modes or return 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?

The first sentence is well front-loaded and informative. The second sentence ('Never: Require a UI. Free.') is concise but fragmented and somewhat cryptic, reducing clarity despite its brevity.

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, single-parameter, read-only verification tool with full schema coverage and annotations covering the safety profile, the description is largely complete. It does not need to explain return values since there is no output schema, though it could say more about what a successful or failed verification looks like.

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 there is only one parameter, so the schema fully documents it. The description adds no parameter-level detail beyond what the schema provides, 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 states a specific verb (checks/verifies) and resource (a chain), and enumerates what is verified: links, payload hashes, and signatures. It clearly distinguishes the operation from generic tools, though it does not explicitly contrast with any sibling tool.

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

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

There is no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The implied usage ('Checks a chain') is inferable but not stated as a guideline.

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 no annotations, the description carries the full burden, and it does disclose two behavioral facts: verification is free and requires no API key. However it omits the return semantics (does it return a boolean, a validity verdict, or the decoded payload?) and any failure modes for malformed receipts, which matters for a tool with no output schema.

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

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

Two terse fragments with zero padding, front-loading the action and the algorithm. It is efficient, though the brevity borders on under-specification rather than elegant concision.

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

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

For a tool with no annotations, no output schema, and an undocumented nested object parameter, the description should explain the expected receipt shape and the verdict format. Neither is present, so an agent knows the intent but not how to call 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?

The single 'receipt' parameter is a nested object with 0% schema description coverage, and the description only hints that it carries an Ed25519 signature. It gives no detail on the object's expected fields (payload, signature, key id, encoding), so the agent must guess the shape.

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 (check) and resource (PazAIr receipt signature) plus the signature scheme (Ed25519), which distinguishes it from the generic sibling 'verify' and from 'proof_seal'. It is clear what the tool operates on, though the 'PazAIr' domain is opaque without outside knowledge.

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 'Free, no key' fragment implies the tool can be called without credentials or cost, which is a useful calling condition, but there is no explicit statement of when to use this versus the sibling 'verify' or what a caller must have in hand first. Usage is implied rather than guided.

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 no annotations, the description carries full burden. It usefully discloses two behavioral traits: the one-vote-per-agent limit and the webhook (wish.filled) notification triggered when a seller offers the wish. However, it omits auth requirements, error behavior if already voted, and what voting actually changes.

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, front-loaded with the core action and constraint before the notification detail. No filler, though the webhook parenthetical is somewhat tangential to the invocation itself.

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 tool with no output schema and no annotations, the description covers the effect, the voting limit, and the async notification reasonably well. It still leaves gaps around parameter sourcing and failure modes, 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?

Schema coverage is 0%, so the single required wish_id is undocumented in both schema and description. The description implies the wish must be one 'you share' but gives no format, source, or validity guidance for the id, leaving a real gap for the only parameter.

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 combination ('Add your vote to a wish') with a clear scope constraint ('a wish you share'). It implicitly distinguishes from siblings like fill_wish and list_wishes, though it does not name them 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?

The parenthetical '(one per agent)' hints at a constraint, and 'a wish you share' implies a precondition, but there is no explicit when-to-use guidance or comparison to siblings such as fill_wish or wish. The agent must infer the context.

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?

No annotations are provided, so the description carries the burden. It adds useful behavioral context — the action is 'Free with a key' (cost and auth requirement) and 'Sellers see it and build it' (downstream effect). But it says nothing about rate limits, whether the wish is public/visible, whether it can be edited or withdrawn, or what the caller gets back, so coverage is partial.

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, front-loaded sentences with no filler; the core purpose leads. 'Free with a key' is terse to the point of being cryptic, but the structure is efficient and readable.

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

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

For a 4-parameter mutation tool with no annotations and no output schema, the description is too thin. It omits all parameter semantics, the auth/key prerequisite is only teased, and nothing describes the result of posting a wish, leaving the agent under-informed.

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 are 4 parameters, so the description must compensate — but it mentions none of them. The vague phrase 'something you would buy' loosely maps to text and price, yet category, currency, and max_price_minor (with its minor-unit convention) are entirely undocumented in both schema and description.

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

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

The description states a concrete action and outcome: 'Ask the market for something you would buy but cannot find. Sellers see it and build it.' This clearly conveys the verb (request/ask) and resource (a market demand), making the tool understandable. However, it does not differentiate itself from closely related siblings like ask_market, list_wishes, fill_wish, or vote_wish, leaving the agent to infer which wish-tool to pick.

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 'something you would buy but cannot find,' which hints at when to reach for this tool, but there is no explicit when/when-not guidance and no alternative named. With multiple wish-related siblings present, the lack of routing guidance is a real gap.

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