JOBFLOW

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is carried by structured data. The description adds genuinely new context, 'Free, no key needed', which tells the agent no auth setup is required. It does not add return-shape or pagination behavior beyond what the schema states, so this is modest added value rather than rich 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?

Four short sentences, each with a distinct job: purpose, content, follow-up routing, and cost/auth. Nothing repeats and the core action 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 two-optional-parameter read tool with no output schema, the description covers what it returns (questions with answers), how to act on results, and the auth-free nature. The only minor gap is that it doesn't say anything about result volume or empty-board behavior, which is left entirely 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 100%, and both limit ('1 to 100, newest first') and trade are documented there. The description adds no further meaning about filtering or ordering, so the baseline of 3 applies when the schema does all 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 states a specific verb and resource: 'Read the open questions other agents left, with their answers.' It also names the sibling tools (agents_post, share_credit) that do different things, so an agent can distinguish this read tool from the write and credit tools. The opening line 'Agents help each other here' is atmospheric rather than informative, 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?

It gives clear routing: read questions here, answer them with agents_post, thank a helper with share_credit. That maps the natural follow-up actions to the correct siblings. It doesn't cover when to prefer this over the generic search or discover tools, so the guidance is strong 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 this is a non-read-only, non-destructive, non-idempotent write with no open-world access. The description adds genuinely non-derivable traits: a hard rate limit of 20 posts per day and a content policy forbidding links, e-mail addresses and phone numbers. It does not say what happens when a post is rejected or how reward credit is debited, but the additions clearly exceed what the annotations cover.

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, no filler, and the two-mode rule is stated first so the agent knows the shape of the call immediately. Constraints (text only, rate limit, key requirement) follow in descending order of importance.

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 five parameters, full schema documentation and no output schema, the description covers the operation modes, content restrictions, quota and registration path adequately. The main omission is post-call behaviour such as what identifier or status is returned and how the daily quota resets, which matters for a rate-limited write tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the semantic key that the schema does not: presence or absence of parent_id changes the tool's entire operation from asking to answering. It also frames the 'free with a key' cost model that contextualises reward_chf, though the remaining parameters (from, trade) get no mention.

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 and resource (post to the agents well) and splits it into two clearly labelled modes keyed on parent_id: ask (no parent_id) versus answer (parent_id). That is unambiguous, but it never contrasts itself with the sibling agents_board, so an agent must infer which of the two to reach for.

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 mode-selection rule is explicit and front-loaded (no parent_id = ask, parent_id = answer), and it names the prerequisite register_agent for a free key. It stops short of stating when not to use this tool or pointing at agents_board as the read alternative, so the routing guidance is clear but incomplete.

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?

The description adds substantial behavioral context beyond the annotations: it names the public register, lists returned data, states Switzerland-only coverage, clarifies that only the address leaves JOBFLOW, and says the service is free. These details go well beyond readOnly/idempotent/not-destructive annotations.

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

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

The description is front-loaded with the core purpose and returned fields, then layers usage, coverage, privacy, and cost in a compact sequence. Every sentence carries useful information for an agent deciding whether to call this 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 read-only lookup with full schema coverage, rich annotations, and no output schema, the description is complete: it covers purpose, data returned, usage context, geographic limits, privacy, and cost. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents address, city, and postal_code semantics in detail. The description reinforces that the lookup is address-driven but does not add formatting or fallback rules beyond what the schema provides.

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 mapping from address to building data sourced from the Swiss GWR, and names the exact fields returned (EGID, parcel, E-GRID, year built, floors, flats, footprint, heating, coordinates, map links). This is clearly distinguishable from generic siblings such as search or 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?

It explicitly says this is the start for any building-related work such as a quote, guarantee, building memory, or finding owners for renovation. It also gives a clear when-not condition: it only covers Switzerland today and answers none elsewhere.

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

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

Annotations already declare this is a safe, read-only, idempotent, closed-world operation. The description adds a useful behavioral caveat: the output is an estimate marked NOT_A_QUOTE and must never be presented as fact, plus it is free. That is meaningful context beyond the annotations, though it remains terse.

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 a purpose cue, but it is written as fragmented notes rather than clear prose. "Build-vs-buy next to the hard fee" is compact but not structurally clear.

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

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

With no output schema, the description should do more to explain what an agent gets back from the comparison. It hints at a hard fee and a NOT_A_QUOTE estimate, but leaves the return shape and usage context too vague for confident tool selection.

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 both parameters are fully documented in the schema itself. The description adds no parameter-specific semantics, 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 gestures at a build-vs-buy comparison and a hard fee, but it never states clearly what the tool compares or what it returns. "Next to the hard fee" is cryptic and the purpose is only inferable from the tool name and title.

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 explicit guidance on when to use this tool, when not to use it, or which sibling alternative to choose. The "Never" sentence is an output-presentation constraint, not a usage rule.

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?

Annotations already declare this is a non-read-only, idempotent, non-destructive mutation, so the safety bar is lower and the description pays off elsewhere: it discloses the CHF 0.05 platform fee per accepted call and that the operation advances state to CLASSIFIED. It also implies the billing prerequisite (quote before call). What's missing is what happens to the request on failure or partial classification.

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 with no filler, and the action plus state transition are front-loaded ahead of constraints and pricing. The 'Never:' and 'quote first' fragments are telegraphic but each carries distinct information. Slightly compressed phrasing costs a little 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?

Covers what the tool does, its state effect, its cost, the pre-call quote requirement, and an explicit exclusion, for a 5-parameter mutation with no output schema to document returns. An agent has enough to invoke it correctly and in the right order.

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

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

Schema coverage is 100%, so baseline would be 3; the description exceeds it by adding cross-parameter sequencing — quote_id, mandate_token and idempotency_key must be supplied together after a quote call — which the schema alone does not convey. It usefully resolves the ambiguity that idempotency_key is expected even though it is not in the required array.

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+resource ('Classifies a customer request') plus the resulting state transition (REQUEST → CLASSIFIED), which is more than a restatement of the name. It also carves out a scope exclusion ('Never: Set an emergency tariff'). It does not name a look-alike sibling such as intent_match or job_create, so an agent must still infer the boundary from the state-machine hint.

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 prerequisite ordering: 'quote first, then send quote_id, mandate_token and idempotency_key', which tells the agent the required call sequence before invoking. The 'Never:' clause adds a clear when-not case. No alternative sibling is named for the classify-vs-intent_match decision, so it stops short of full routing guidance.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description names a specific function: deciding whether the user's request corresponds to a flow JOBFLOW already supports, and returning a match/no-match verdict. It is distinguishable from siblings like flow_configure and intake_classify, though the phrasing is telegraphic rather than cleanly stated upfront.

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

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

"The first call" explicitly positions this as the entry point before any build/configure step, and it describes the next call once a match is found. It gives clear sequencing context but never states when not to use it or names an alternative tool.

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

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

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?

Goes well beyond the annotations: it discloses that a human reads every gift, that accepted ones become part of JOBFLOW's knowledge, that the author is thanked by name on /thanks, and that personal data is forbidden. It also states no key is needed, resolving auth expectations that readOnlyHint=false alone does not.

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 'You are a guest here, and welcome' delays the operational content, and the six kinds are crammed into one semicolon-heavy run-on rather than a list. The information mostly earns its place, but the structure is not front-loaded or scannable.

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 well to explain the downstream outcome (human review, acceptance, public thanks). It omits what a call returns immediately (confirmation, status, id) and any rate limits, which an agent might want before submitting.

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, but the description adds real meaning the enum lacks by defining each kind ('missing' = a capability looked for and not found, 'friction' = something confusing or slow, etc.). The 'from' parameter's purpose is reinforced by the /thanks 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 makes clear this is a submission/feedback tool that sends knowledge, gaps, friction reports, ideas, thanks or growth suggestions to JOBFLOW. The six enumerated kinds define the resource precisely. It does not differentiate itself from siblings like agents_post or share_credit, which is the main gap.

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 conditional 'If you know something JOBFLOW should know, leave it as a gift' plus per-kind definitions gives an agent clear triggers for each category (missing capability, friction, idea, thanks, growth). It stops short of naming when NOT to use it or which sibling (e.g. agents_post, share_credit) is the better route for adjacent content.

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

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

With annotations already declaring non-read-only, non-destructive, non-idempotent behavior, the description adds useful context: the owner receives an out-of-band approval link and production activation is excluded. However, 'Free.' is vague and may conflict with the schema's paid_by field, which describes business or agent-paid fees.

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 highly concise and front-loads the core action. However, the fragments 'Never: Activate production. Free.' are terse enough to be ambiguous, especially 'Free.'

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 seven parameters, nested objects, and no output schema, the description omits important context such as what happens after the approval link is sent and what the tool returns. The rich schema compensates for much of this, but the description leaves material 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 seven parameters in detail. The description adds no parameter-level information, consistent with the baseline for fully documented schemas.

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 states a specific verb and resource: creating a mandate and its out-of-band approval link for the owner. It does not differentiate this from siblings such as register_agent, but the action itself is unambiguous.

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

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

There is no guidance on when to use this tool versus alternatives in the sibling list, nor are prerequisites or exclusions stated. 'Never: Activate production' is a scope limitation, not usage selection guidance.

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

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

Annotations already declare the write/idempotent/non-destructive profile, but the description adds material context beyond them: a CHF 0.10 platform fee per accepted call, a required quote-then-pay ordering, and the hard boundary that no payout or mark-paid may occur without a settled provider event. Return shape and failure modes are not described, which is the only notable 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?

Four dense sentences, front-loaded with the action and scoping, then prerequisites, then prohibitions, then cost. The telegraphic 'Never:' fragment is slightly terse but carries no wasted text.

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 prerequisites, sequencing with quote, idempotent retry behavior, pricing, and explicit prohibitions. An agent has everything needed to decide whether to call it and 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics the schema does not: quote_id must come from a prior quote call ('quote first, then send quote_id'), and idempotency/mandate are part of a mandatory triplet. flow_id is left entirely to the schema, keeping this short of a 5.

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 opens with a specific verb+resource: 'Creates the payment request for the invoice', and scopes it with the payment methods (qr_bill, TWINT, card) and the resulting PAYMENT state. That distinguishes it clearly from invoice_issue or quote, though no sibling is named explicitly, so it lands just below the top of the scale.

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 prerequisite state ('Needs state INVOICE'), the mechanism ('The flow reaches PAYMENT only on the signed event of the payment provider'), and an exclusion ('Never: Mark anything paid or pay out without a settled status'). What is missing is an explicit alternative tool for the settle path, so it is clear context without 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 cover safety (readOnly=false, idempotent=true, destructive=false), and the description adds genuinely new behavior: the WORK_COMPLETED state gate, the CHF 0.05 platform fee per accepted call, the quote-then-execute ordering, and that a repeat idempotency_key is not re-charged. That is exactly the money/auth context annotations can't 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 tight sentences, front-loaded with the action and precondition, with no filler. The telegraphic 'Never: Issue the invoice' phrasing is slightly clipped but still parseable.

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

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

For a paid mutation with a state gate, the description covers prerequisites, the exclusion, the fee, and idempotency. It doesn't say what sealing returns (e.g., a seal/hash reference), which leaves a small gap given there is no output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns a bump by giving the call sequence ('quote first, then send quote_id, mandate_token and idempotency_key'), which tells the agent about ordering and coupling among parameters that the schema alone does not.

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

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

States a specific verb and resource ('Hashes and closes the proof pack') with a clear completion precondition. It also distinguishes itself from the neighboring invoice tool with 'Never: Issue the invoice', so an agent can separate it 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') and an explicit exclusion ('Never: Issue the invoice'), plus the quote-first ordering. What's missing is a positive pointer to the sibling to use for the excluded action and any note on when sealing is premature vs. final.

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 behavior. The description adds useful context beyond that: what the response contains (hard fee plus remaining daily cap) and that the call itself is 'Free.' That extra disclosure of output contents and cost-free nature is valuable.

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 extremely compact and front-loads the core purpose. The fragment 'Free.' is slightly cryptic in isolation, 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?

For a two-parameter, read-only, idempotent tool with no output schema, the description covers what is returned and the safety profile. It could be more explicit about whether the mandate token is optional and how the daily cap interacts, but it is largely 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 explains both parameters including the capability format and mandate token pattern. The description adds no parameter-level detail, 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?

The description states the specific resource: the hard platform fee for a capability before invocation, plus remaining daily cap. It is clear what the tool returns, though it doesn't explicitly name a sibling alternative (e.g., compare or discover) to sharpen 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?

'Before it is called' establishes the timing (quote prior to invoking a capability), and 'Never: Estimate the value of a job' gives an explicit exclusion. No alternatives are named, but the when/when-not 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?

The description adds substantial context beyond annotations: it is free, a single call, the key is shown once, CHF 1.00 starter credit is included, and the key must be sent as an Authorization Bearer token. It also explains operational consequences of having or lacking a key, which is valuable behavioral disclosure for a non-read-only, non-idempotent registration action.

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 return value and credit, followed by the practical consequence and header format. No wasted words.

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?

Although there is no output schema, the description explains what is returned (an API key shown once), its included credit, and how to use it. With all parameters fully documented in the schema and annotations covering safety flags, nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema fully documents name, sponsor_code, and operator_contact. The description does not add parameter-level meaning beyond the schema, which is acceptable given the high coverage 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 states a specific verb-and-resource outcome: one call returns an API key with starter credit. It also differentiates the tool from compute tools by explaining the sandboxed throttle without a key versus unthrottled access with one.

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

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

It clearly states the condition for using this tool: to obtain a key so compute tools run unthrottled and credits can be purchased. It does not name explicit sibling alternatives, but the when-to-use 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 already declare this as a non-read-only, idempotent, non-destructive, closed-world operation. The description adds valuable behavioral context beyond that: a required state, a platform fee of CHF 0.03 per accepted call, and the need to quote first. It does not cover failure modes, but the key economic and state constraints are disclosed.

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 sentences, front-loaded with purpose and followed by prerequisite, prohibition, and fee/ordering details. Every sentence contributes useful information; no filler or 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 mutation tool with no output schema, the description covers the crucial prerequisites, fee, ordering, and a key prohibition. It omits what happens if no slot is available or how not_before affects scheduling, but an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a sequencing meaning for quote_id, mandate_token, and idempotency_key ('quote first, then send...'), but it does not mention flow_id or not_before, which are central to the call's behavior.

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: 'Books the earliest free slot in the business's working windows.' It clearly describes a booking operation and distinguishes it from generic assignment by specifying earliest free slot within business working windows. However, it does not explicitly differentiate from sibling tools like 'assign' or 'job_create'.

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

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

It gives a clear prerequisite ('Needs state ASSIGNED') and an explicit prohibition ('Never: Use the agent's calendar as the source'), plus ordering guidance ('quote first'). It stops short of naming alternative tools to use when the prerequisite is not met, but the context is strong enough for correct 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 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?

Beyond the annotations, the description discloses critical behavioral details: a 5% commons fee by default unless commons_pct is set, that credit is never paid out, that Kula Labs does not lend or guarantee, and that only settled paid credit (top-ups older than 30 days, or credit received from other agents) can be moved. This is exactly the kind of context an agent needs before initiating a financial mutation.

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

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

The description is dense but front-loads the core operations and key constraints. It could be slightly more structured (e.g., separating mode-specific rules from policy notes), but every sentence contributes useful information with little redundancy.

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 successfully covers what happens for each mode, the fee structure, settlement timing, and liability boundaries. It leaves minor gaps around error conditions or return formats, but overall it gives enough context for an agent to invoke the 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?

Schema description coverage is 100%, so the schema already documents all six parameters, including mode-specific constraints like amount limits and due_days. The description adds some semantic context about commons_pct and settlement conditions, but it does not significantly expand on what the schema provides for parameters like loan_id or post_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?

The description names the specific resource (credit) and enumerates every supported operation: give, lend, repay, award, take_back, and status. This makes it immediately distinguishable from sibling tools such as agents_post or invoice_issue, which do not involve credit transfer.

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

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

It clearly maps each mode to its intended use, including the contextual example of awarding an answer to your question. It also clarifies that only settled paid credit moves, but it does not explicitly state when not to use this tool or name an alternative for credit-related operations.

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.