JOBFLOW

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

Annotations already cover the safety profile (readOnly=false, idempotent=true, destructive=false), so the bar is lower, and the description still adds material facts: a per-call platform fee of CHF 0.03, the requirement to obtain a quote before calling, and a prohibition against treating free text as dispatching. It stops short of describing success/return behavior or failure modes for a money-touching mutation.

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

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

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

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

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

For a fee-charging mutation with no output schema, the description covers preconditions, cost, and call ordering, which is a reasonable amount of context. It omits what a successful assignment returns, what happens if state is not ORDER, and how failures are surfaced, leaving notable gaps.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including patterns. The description only reinforces the call ordering (quote_id, mandate_token, idempotency_key) without adding format or constraint meaning beyond the schema, which is the expected baseline.

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

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

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

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

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

Gives a real precondition (state ORDER) and implies sequencing with a sibling ('quote first, then send quote_id'), which is useful workflow context. However, no alternative tool is named for the negative case ('Never: Treat free text as dispatching'), and the guidance is delivered in cryptic fragments rather than explicit when/when-not routing.

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

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

Annotations already establish readOnly/idempotent/non-destructive behavior, but the description adds genuinely new traits: results are an estimate explicitly marked NOT_A_QUOTE, token counts or estimates must never be presented as facts, and the operation is free. Those are concrete behavioral disclosures beyond the structured fields.

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

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

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

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

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

With no output schema, two parameters at 50% description coverage, and an underspecified 'capabilities' array, the description should explain inputs and the shape of the recommendation but does not. The NOT_A_QUOTE rule is the only substantive completion.

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

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

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

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

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

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

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

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

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

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

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

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

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?

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?

Annotations already declare the mutation profile (readOnlyHint=false, idempotent=false, destructive=false, openWorld=false), so the bar is lower. The description does add genuine behavioral value by disclosing the out-of-band approval link sent to the owner and a 'Free' cost note, but it omits reversal, auth requirements, and what happens on failure.

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

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

Very short and front-loaded, which is good, but the clipped fragments 'Never: Activate production. Free.' are cryptic rather than economical — they consume space without conveying actionable meaning to an agent.

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

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

For a mutation tool with nested objects, an enum-constrained scopes list, and no output schema, the description is far too thin. It never explains the mandate lifecycle, required identifiers, or what the returned approval link implies, leaving major gaps an agent must guess at.

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 17% across 6 parameters, so the description carries the burden — and it describes none of them. Required nested objects (delegate, scopes), the whatsapp channel constraint, expires_in_days limits, and the paid_by default are left entirely to the schema, with paid_by being the only field with any schema prose.

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 ('Creates a mandate') and adds a distinguishing side effect ('the out-of-band approval link for the owner'). It does not, however, distinguish itself from siblings like assign or job_create, and the trailing 'Never: Activate production. Free.' fragments muddy rather than sharpen the purpose.

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, prerequisites, or alternative-tool guidance is given. 'Never: Activate production' is an opaque boundary that an agent cannot map to a decision, and no sibling is named as the fallback for other cases.

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?

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?

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.