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 covered. The description adds real behavioral context beyond that: it mutates session/actor binding and activates a membership, and it flags the pre-workspace prerequisite. It doesn't cover token expiry, single-use semantics, or failure behavior, which keeps it from a 5.

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

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

Two sentences, front-loaded with the action and effect, with the prerequisite placed after. Every clause carries information; no filler.

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

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

Given a single-parameter activation tool with annotations covering idempotency and safety, no output schema, and a sibling invite_member, the description covers the core intent and the pre-workspace constraint. It is still missing how to obtain the token and what happens on invalid, expired, or already-used tokens, which matters for a token-redemption flow.

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 only 1 parameter, 0% schema description coverage, and no enums, the description should carry the burden of explaining the token. It only implies the parameter is an invite token; it says nothing about where the token comes from, its format, or whether it is single-use, so it does not compensate for the schema gap.

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

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

States a specific verb and resource ('Redeem an invite token') plus the resulting effect (bind session actor to the invited identity, activate membership). It doesn't explicitly distinguish itself from the sibling invite_member, but 'redeem' vs 'invite' is clear enough that an agent won't confuse them.

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

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

Gives a concrete usage condition: it must be used pre-workspace because the accepter is not yet a member. That resolves the natural ambiguity about why a workspace-scoped tool wouldn't apply. It doesn't name alternatives or exclusion cases explicitly, so not 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?

The annotations already disclose that the operation is idempotent and potentially destructive, and the description is consistent with that by mentioning clearing. However, it does not explain what clearing affects, whether an existing default is replaced, or what permissions are required.

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

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

The description is a single efficient sentence with the core operation front-loaded and no filler. Its terseness is not wasted, though the brevity comes at the cost of useful detail rather than through deliberate compression.

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

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

For a destructive account-setting mutation with three undocumented parameters and no output schema, the description is too thin. It omits the clearing semantics, replacement behavior, and any prerequisite or permission context needed to invoke it confidently.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, but it only addresses the tax code implicitly. It does not explain that omitting taxCode clears the default, nor does it describe accountId or workspaceId beyond their names.

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: setting or clearing an account's default tax code. It clearly distinguishes the operation from general account update or tax-code maintenance tools, though it does not explicitly name a sibling 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?

The description gives no guidance on when to use this tool versus update_account or tax-code configuration tools. It also does not state prerequisites, such as whether the tax code must already exist in the workspace.

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 idempotency and a destructive hint. The description adds useful behavior beyond them: the draft is not posted, and the response includes the exact future post lines plus reversal lines dated the day after. It does not explain why destructiveHint is true or what could be overwritten, which is the remaining 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?

The description is dense but front-loaded and every clause adds useful information. It is a single long sentence, so it could be more scannable if split, but there is essentially no filler.

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

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

There is no output schema, so the description appropriately explains what the call returns: the draft with exact post lines and reversal lines dated the next day. It also establishes that nothing is posted. The main missing completeness item is guidance around the required idempotency key and other secondary parameters.

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 0% schema description coverage, the description carries substantial weight and succeeds for the critical fields: it defines the four `kind` values with accounting treatment, explains that `contraAccount` is the P&L account with direction by kind, states `amountMinor` is integer Rappen, and defines `periodEnd` as the balance-sheet date. Several parameters such as `idempotencyKey`, `sourceRef`, `currency`, `costCenterId`, and `workspaceId` remain unaddressed.

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 action: describe an Abgrenzung (OR Art. 958b) and save it as a DRAFT. The explicit 'Nothing is posted' clause distinguishes it from the sibling accrual_post, so an agent can tell exactly what this tool creates.

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

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

The description clearly sets the context that this is draft creation only and that nothing is posted, implying that accrual_post is the separate posting step. It stops short of naming the alternatives or stating exclusions explicitly, so it is strong but not fully routing-aware.

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, but the description adds real substance: the row is retained as `discarded` with its reason, and the failure mode surfaces as `already_posted`. That tells the agent the outcome is a soft state transition, not a delete, and what error to 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?

Two tight sentences with the action and precondition front-loaded, then the outcome and error case. Every clause carries information an agent needs.

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

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

No output schema, so the description correctly explains the resulting state and error code, and it routes the mis-case to the right sibling. The remaining gap is parameter-level detail (notably idempotencyKey behavior) rather than tool behavior.

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

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

Schema description coverage is 0% and the description only implicitly explains one of four parameters (the reason string being persisted on the discarded row). accrualId, workspaceId, and especially idempotencyKey — whose semantics matter for a retryable mutation — are undocumented in both schema and description.

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

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

Specific verb ('Retire') plus specific resource ('a drafted Abgrenzung before it posts'), and it explicitly separates this from accrual_reverse / accrual_post by naming the post-state boundary. An agent can identify the tool from the description alone.

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

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

States the precondition (drafted, not yet posted), the exclusion (a posted accrual cannot be discarded), and names the correct alternative for that case ('reverse it instead'). Nothing is left to inference.

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

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

The readOnlyHint=true annotation already declares the read-only safety profile, and the description aligns with it by opening with 'Read'. The description adds meaningful context beyond the annotation by disclosing what is actually returned (row, lines, reversal lines, journal entries, Storno pair) and notes the provenance consistency ('from the same function the post uses'). This is useful behavioral detail for an agent deciding what it can rely on.

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 one front-loaded sentence with no filler; the verb 'Read' appears immediately and each subsequent clause enumerates a distinct return component. The parentheticals ('from the same function the post uses', 'the accrual, its reversal, the Storno pair') are dense but each earns its place by clarifying provenance or terminology.

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

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

For a simple two-parameter read tool backed by readOnlyHint=true, the return contents are well described and the safety profile is covered by annotations. The notable gaps are that both parameters are under-documented across schema and description, and the German term 'Abgrenzung' is used without being fully defined, so the agent needs context from the sibling accusatory set to fully understand the concept being read.

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

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

Schema description coverage is 0%, so the description carries the full burden of explaining the two parameters, but it never mentions workspaceId or accrualId or clarifies their meaning, format, or relationship. The only oblique connection is that 'Read one Abgrenzung' implies the accrualId selects the record; the workspace dimension is entirely unaddressed.

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 and resource — 'Read one Abgrenzung' — and then enumerates the exact return scope: the row, its lines, reversal lines, and produced journal entries (accrual, reversal, Storno pair). This scope is specific enough to clearly distinguish it from the mutating accrual siblings (accrual_create, accrual_post, accrual_reverse, accrual_discard) and from the collection-focused accrual_list. It does not name a sibling, but the read-target and depth 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?

The phrasing 'Read one Abgrenzung' implies the intended use — fetch the full detail of a single accrual record — and the listed return components imply the data depth an agent should expect. However, there is no explicit guidance about when to prefer this tool over accrual_list or the read-style siblings (e.g., provision_get), and no exclusions or prerequisites are 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?

Beyond the readOnlyHint annotation, the description discloses meaningful behaviors: results are ordered newest period first, totalMinor aggregates drafts and posted accruals, and savedViewId applies a saved view. This provides useful behavioral context without contradicting the read-only annotation.

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

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

Two compact sentences deliver the core action, sorting, filters, status enum, a computed-field behavior, and saved-view semantics. Every phrase earns its place with no redundancy or 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?

The description covers the essential call dimensions: filtering, ordering, and the special totalMinor/savedView behaviors. It does not document output structure or pagination, but given no output schema exists, but the core information needed to invoke the tool correctly is present.

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

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

With 0% schema description coverage, the description compensates by explaining the filter semantics for periodEnd, status (with explicit allowed values), kind, and savedViewId. It does not define periodEnd format or kind value options, but it adds substantial meaning beyond the bare parameter names.

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 ('List'), the resource ('Abgrenzungen'/accruals), and concrete dimensions of the operation: newest period first, with filtering by periodEnd, status, and kind. This clearly distinguishes it from singular operations like accrual_get and from related but different list tools such as provision_list.

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

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

The description gives clear usage context by specifying sort order and available filters, so an agent knows when to call this listing tool rather than a get/create/post operation. It does not explicitly name alternatives or exclusions, but the list-vs-get distinction is strongly implied.

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

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

Goes well past the idempotentHint/destructiveHint annotations: discloses atomic all-or-nothing semantics, that a locked reversal date rolls back the whole pair, the exact outcome codes (replay, already_posted, draft_discarded), and that a mistake is corrected by a mirror pair leaving four visible entries. That is precisely the behavioral context annotations cannot carry.

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

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

Front-loaded with the atomic-pair mechanic, then errors, then consequence. The CONSEQUENCE sentence partially restates the opening pair description, so it is slightly redundant, but every other sentence adds distinct information.

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

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

No output schema, and the description does not say what a successful post returns (entry ids? the pair?), nor whether the draft must be validated first. Otherwise the mutation semantics, failure modes and undo path are covered well enough to call it safely.

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

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

Schema coverage is 0%, so the description must compensate. It thoroughly explains idempotencyKey semantics (replay vs. already_posted vs. draft_discarded) and implies accrualId names the draft being posted, but workspaceId and the key's format/scope are left undocumented.

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

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

States a specific verb and resource ('Post a drafted Abgrenzung') and pins down the scope: it creates an atomic pair, not a single entry. This distinguishes it cleanly from accrual_create (draft), accrual_reverse (mirror pair) and accrual_discard without needing 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?

Implies the precondition clearly ('a drafted Abgrenzung') and describes the revert path ('you revert it with a mirror pair'), which routes an agent away from trying to undo via this tool. It stops short of naming accrual_reverse/accrual_discard explicitly as the alternatives, so selection still takes one inference step.

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 idempotentHint/destructiveHint annotations: it discloses that four entries are produced, that the original pair remains visible, that balances net to zero in both periods, which error codes are returned, and that the operation is not editable/reversible in place. That is exactly the consequence-level detail an agent needs before mutating books.

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 mechanism, then the error contract, then a labelled 'CONSEQUENCE:' block – easy to scan. The consequence sentence partly restates the opening 'net to zero on every account' claim, so there is minor repetition, but every other sentence adds new information.

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

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

For a complex, irreversible-in-practice accounting mutation with no output schema and no annotations covering side effects, the description supplies the accounting semantics, the failure modes, and the undo story. The remaining gap is the return payload and the meaning of the four inputs, which leaves it slightly short of fully self-sufficient.

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

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

Schema description coverage is 0% for four parameters, so the description must carry the burden and largely does not: it never explains accrualId, workspaceId, idempotencyKey, or the optional reason. Worse, the one identifier it does mention, `periodEnd`, is not an input parameter at all, so it cannot help the agent fill the schema.

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

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

States a specific verb and resource ('revert a posted Abgrenzung') and then explains the exact mechanism (posts the mirror pair: Storno on periodEnd, its own reversal the day after). It is clearly distinguishable from siblings like accrual_post, accrual_discard, provision_reverse, and vat_settlement_reverse because it names the object it operates on and what the outcome is.

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 refusal conditions ('already_reversed' a second time, 'not_posted' on a draft) implicitly define the valid precondition: only posted, not-yet-reversed accruals. It also gives a recovery path ('if the reversal was wrong, you create and post the accrual again'). It stops short of naming the alternative tool for drafts (accrual_discard), so it is clear context rather than full 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 declare idempotentHint=true and destructiveHint=true; the description earns credit by explaining exactly what is destroyed (abandon deletes the pointer), that a differing direction resets the checklist, and that completedAt is derived (stamped at five done, cleared on un-done). It also discloses the important caveat that timestamps are a claim, not proof. Auth/permission behavior is not covered.

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

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

Purpose is front-loaded in the first clause, which is good, but the single dense paragraph is padded with 'absolutely', the German 'Umzug abbrechen', and parenthetical asides like 'the trial-balance-mismatch recovery' that cost tokens without adding callable information. The signal is there but interleaved with noise.

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

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

For a 5-parameter mutation tool with no output schema and only two annotations, the description covers the modes, the reset rule, the derived completedAt, and the non-gating caveat — enough to call it correctly. The unexplained workspaceId and unenumerated direction values are the only material omissions.

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

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

Schema description coverage is 0%, so the description carries the burden and largely does: step is bounded 1-5, done defaults true with an un-check use case, abandon deletes the pointer, and direction drives start/reset semantics. Two gaps remain — workspaceId is never explained, and direction's allowed string values are not enumerated.

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 opening clause names a specific verb and resource: persist the move-checklist resume point. It distinguishes itself from the parallel advance_onboarding_step by reference to its 'shape' and from the real journey actions (create_backup, archive_workspace) which it explicitly says it is not. Slightly obscured by dense parentheticals ('absolutely', 'Umzug abbrechen'), but an agent can still identify the tool's job.

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 spells out the invocation modes clearly: direction alone starts/re-asserts, direction+step checks or un-checks, abandon deletes. The 'Never a gate' clause is real guidance — it tells the agent this tool does not perform or validate the actual journey actions, so it must not be used as a substitute. It stops short of explicitly routing to advance_onboarding_step for onboarding, which keeps it from 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?

Goes well beyond the annotation hints by disclosing that this is never a validation gate, that underlying setup verbs keep their own idempotency, and that completed:true is a one-way stamp that 'never un-completes'. The destructiveHint:true annotation is left unexplained, though, so the agent never learns that an existing resume point can be overwritten.

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?

Dense and front-loaded — the persist-point purpose lands in the first clause and the disclaimers follow. The spec citation (US-G03.5) adds traceability rather than bloat, though the sentence structure is somewhat packed.

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

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

For a 4-parameter mutation with no output schema and a destructiveHint annotation, the definition is reasonable but leaves gaps: nothing says what is lost when the resume point is overwritten, nothing scopes workspaceId, and no return value is implied.

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

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

Schema coverage is 0%, so the description carries the full burden: it distinguishes path (fresh|import|demo) and step ('absolutely'), and pins down completed as a one-way finished flag. However, workspaceId is never mentioned and the step value's format is not specified, so compensation is only partial.

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: 'Persist the first-run wizard resume point: path (fresh|import|demo) and the current step'. It explicitly contrasts with the read-side sibling by describing itself as bookkeeping that business verbs ignore, so an agent can tell it apart from get_onboarding_progress without opening a schema.

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

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

Gives a concrete exclusion: 'an agent session skips this bookkeeping entirely', which tells the caller when NOT to use it. It does not name the sibling read tool it complements (get_onboarding_progress), leaving that inference to the caller.

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 idempotent and non-destructive annotations, the description discloses that the runtime only classifies onto read models, that no write is reachable, that the sentence is persisted as a turn, and that the answering call is traced. These are meaningful side-effect disclosures. It does not describe failure modes beyond missing runtime or the shape of the answer.

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

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

The purpose is front-loaded, but the text is dense with internal identifiers (D90 D-1, E05, A26, D-5) that consume space without helping an external agent. It is appropriately short but not maximally clear.

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

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

For a prose-query tool with no output schema, the description adequately covers runtime prerequisites and side effects such as turn persistence and tracing. However, it leaves all non-text parameters unexplained and gives no indication of what the caller receives back.

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

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

Schema description coverage is 0% across five parameters, and the description only indirectly maps 'text' to the prose question. It says nothing about workspaceId, periodStart, periodEnd, or idempotencyKey, leaving most required inputs unexplained.

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

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

The description states a specific verb and resource: ask the books a question in prose. It also clarifies that the executed operation is always a read, which helps distinguish it from mutation-oriented siblings. Internal codes like D90 D-1, E05, and A26 add noise but do not obscure the core 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?

It gives an important precondition (a registered E05 local runtime, otherwise needs_local_runtime) but does not explain when to choose this over other query or search tools. Usage is implied by the prose-query framing rather than explicitly contrasted with alternatives.

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

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

Annotations already declare destructiveHint and idempotentHint, yet the description goes well beyond them: it specifies exactly what is removed (every turn text), what survives (the call trace / trust-view substrate), that the action is permanent and unrestorable, and that it requires owner-level permission. This is precisely the extra context annotations cannot carry.

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

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

The core facts are front-loaded, which is good, but the final CONSEQUENCE sentence substantially restates the opening paragraph (words gone, trace stays, irreversible), and the "D90 D-5" token is dead weight. Two sentences of the roughly five could be cut without loss.

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

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

For a destructive mutation with no output schema, the description covers the essentials an agent needs before acting: the exact blast radius, what is preserved, irreversibility, and the authorization gate. The remaining shortfall is parameter-level detail, which is captured in the parameter score, not here.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning and largely does not. Only "idempotent per key" hints at the role of idempotencyKey; sessionId and workspaceId are never explained, nor is the key's scope. With three required, undocumented parameters this leaves a real 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 and resource ("Delete one agent session's stored prose") and immediately delimits scope: turn text is cleared, the call trace remains. That contrast makes the operation distinguishable from generic session or audit tooling in the sibling list. The cryptic internal reference "(D90 D-5)" adds no value to an agent and slightly muddies the opening.

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 prerequisite ("Owner-gated (manage_agent_dial)") and a strong consequence warning, which implies this is a deliberate, high-friction action rather than routine cleanup. However, it never states when an agent should choose this over alternatives such as archiving, retaining, or simply leaving the session alone, and offers no explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true, and the description goes further by stating the data is 'derived from the trace at read time; never stored, never a score.' This adds meaningful behavioral context beyond the annotation, preventing misconceptions about persistence and semantics.

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 focused sentences convey the resource, the exact contents, the time-window behavior, and the key semantic caveat ('never a score'). No filler or repetition; the most important qualifiers are 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?

Given no output schema, the description enumerates the main return contents and clearly states the computation and persistence model. It lacks exact response structure and date format details, but for a simple read-only evidence tool, it is nearly complete.

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

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

Schema coverage is 0%, so the description must compensate. It adds the concept of a 'stated window (default the last 90 days)', giving some meaning to the from/to parameters, but it does not name them, specify date formats, or clarify the required workspaceId. The compensation is partial but not 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?

The description names the specific deliverable ('trust evidence per dial capability'), enumerates the data it returns (stored/effective levels, who set it, when, counts over window), and explicitly distinguishes it from a score. This differentiates it from sibling tools like get_agent_dial and set_agent_dial.

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

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

The description provides clear context: this is a read-only, trace-derived evidence view over a default 90-day window. It implies when to use it (when historical trust evidence is needed) without explicitly naming alternatives, but the context is sufficient for an agent to route correctly.

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

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

The annotations provide readOnlyHint=true, and the description reinforces this with 'Reads only.' It adds useful behavioral context beyond that: the relationship to baseTotalOpenMinor in multi-currency workspaces conveniently ties to reconciliation flags against account 1100 Debitoren. No contradiction exists between description and 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 dense but efficient: each sentence contributes meaningful information (report nature, aggregation method, currency handling, use case, reconciliation flag, read-only status). It is front-loaded with the core summary, though it could be slightly trimmed without losing value.

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

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

Given there is no output schema, the description does a decent job of explaining the report's output shape: totals per bucket and customer, and the difference between byBucket and baseByBucket. However, it does not mention the asOf parameter or any pagination/limits for large result sets, leaving some operational context missing. For a read-only report, this is a moderate gap.

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

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

The schema has 0% description coverage, providing only parameter names (workspaceId and asOf) without any meaning. The description does not explain these parameters at all; it only mentions output-related fields like byBucket and baseByBucket. The agent must guess what asOf does (likely a date for the aging snapshot), and workspaceId is presumed from the required flag. This is a clear gap in compensating for the schema's lack of detail.

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 what the tool does: it provides a receivables summary totalled per aging bucket and per customer, with the largest debtor first. It explicitly differentiates itself from list_open_items by noting it is the same open items 'totalled' rather than itemised, and gives a concrete use case ('how much is over 90 days overdue and who owes it').

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

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

The description provides a clear usage context: 'Use it to answer ... in one call.' It also references list_open_items as the underlying itemised view, implying the alternative for detailed line items. However, it does not explicitly state when not to use this tool or mention other alternatives, so it lacks exclusion 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?

Adds real context beyond the idempotent/non-destructive annotations: it explains that no entry is posted, that open items get marked paid, and that the only correction path is reversing the entire payment and re-recording it. That correction note is exactly the kind of irreversibility caveat an agent needs. It does not cover idempotencyKey behavior or what happens on partial/over-allocation.

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

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

The core explanation is front-loaded and useful, but the sentence 'A wrong allocation is corrected by reversing the whole payment and recording it again' appears twice, and the CONSEQUENCE line largely restates the opening. Roughly a third of the text is redundant.

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

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

The behavioral side is well covered for a mutation tool, but the tool's real complexity lives in the undocumented allocations array with eight free-form fields at 0% schema coverage, and the description says nothing about how to construct it or how much of the parked amount must be allocated. An agent could not reliably call this from the description alone.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, yet it only pins the value of 'intent'. The nested allocations object (targetId, documentId, targetKind, amountMinor, skontoMinor, dunningItemId, writeOffMinor, paymentAmountMinor) and the roles of paymentId and idempotencyKey are entirely unexplained.

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

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

States a specific verb and resource: allocate a parked Guthaben (credit) against open items, with the key clarification that no new journal entry is posted. It is distinguishable from pure posting tools, but it never names a sibling (e.g. record_payment, apply_qr_match, suggest_payment_matches) to sharpen 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?

It specifies the precondition 'Requires intent=allocate_payment' and the situation (money already booked on an incoming payment), which implies when to reach for it. However, there is no explicit when-not guidance and no comparison to adjacent tools such as record_payment, reverse_payment, or the match-suggestion tools.

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 the accounting posting path, net-of-credit-note calculation, partial/full mode behavior, surplus parking as Guthaben, write-off refusal behavior, currency mismatch behavior, P8 confirmation requirements, non-automatability, idempotency semantics, and undo consequences. This is unusually complete for a mutation tool.

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

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

The purpose and consequence are front-loaded, and most sentences carry operational information. The description is dense and includes internal references such as A14, A21, P8, and D77, but the length is largely justified by the complexity of the operation.

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

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

For a complex settlement tool with no output schema and minimal annotations, the description covers the important behavioral edges: posting delegation, write-off thresholds, currency refusal, confirmation requirements, idempotency, and reversal consequences. An agent has enough context to invoke it correctly.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It adds substantial semantics for mode, confirmed, and idempotency behavior, but does not explicitly define workspaceId and only implies creditId and invoiceId through surrounding context.

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

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

The description states a specific verb and resource: settle an invoice from a queued credit, with posting delegated to record_payment using source 'qr'. It also distinguishes the posting behavior by saying A21 posts nothing itself, so the agent can identify the operation without opening the schema.

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

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

The description gives clear usage conditions: mode defaults to 'partial', mode 'full' applies only within the A14 write-off threshold, and larger residuals must be handled through record_payment. It also states confirmed=true or the auto-apply dial requirement. It does not explicitly compare this tool with sibling override_qr_match or match_qr_payment.

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 behavior beyond the annotations: RBAC is re-checked, idempotency is enforced on the stored key so double-approval does not double-post, the action is marked executed, and allowFuture creates a standing revocable grant equivalent to set_agent_dial. It also discloses the critical authorization constraint that self-approval is impossible and an independent reviewer is required.

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 action and its main effects, and every sentence carries useful security or side-effect information. It is dense, with internal references like D103 and nested clauses, but not verbose enough to obscure the core operation.

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

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

For a destructive approval tool with no output schema, the description covers the approval flow, authorization, idempotency, and allowFuture side effect well. The main gap is that the two required identifiers are not explicitly explained, though their roles can be inferred from context.

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

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

Schema description coverage is 0%, so the description must compensate. It explains allowFuture in detail, but workspaceId is not described at all and actionId is only implied through phrases like 'drafted agent action' and 'stored key' rather than explicitly defined.

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: approving a drafted agent action from the inbox. It clearly distinguishes approval from listing or rejecting drafted actions through the explicit approve/execute framing.

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 contextual guidance: use this to approve an inbox action, but the agent cannot self-approve and a second independent actor must review, owner-gated by manage_agent_dial. It does not explicitly name reject_drafted_action or list_drafted_actions as alternatives, but the exclusions and prerequisites are strong.

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

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

Annotations only declare idempotentHint and destructiveHint=false; the description goes well beyond by explaining that the change is metadata-only, does not lock or alter the entry, records the sign-off in the actor's name, survives a later flag, and returns alreadyReversed for reversed entries. The permission model and the prohibition on automation firing it are exactly the kind of operational context annotations cannot convey.

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

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

Front-loaded with the verb and effect, and every clause is informative. It loses a point for redundancy: 'CONSEQUENCE: ... the entry itself does not change' restates 'neither locking nor altering the entry,' and 'in your name' repeats the preceding 'human act' sentence.

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

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

With no output schema, the description usefully discloses the alreadyReversed outcome and confirms the entry is unchanged, so the agent understands the effect and result signal. The remaining gap is parameter-level detail for a 4-parameter tool, which is left entirely to the bare 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 0% across four parameters, so the description must carry the burden, and it does not: workspaceId, entryId, idempotencyKey, and note are never mentioned. The idempotencyKey is only obliquely implied by the idempotentHint annotation, and the purpose of the optional note field is undocumented anywhere.

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: sign off one checked entry, setting its review status to approved as metadata only. It immediately delimits scope with 'neither locking nor altering the entry,' which separates it from mutating siblings like post_entry or reverse_entry, and the German term (freigeben) anchors the domain concept.

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?

Explicit preconditions are given: requires the review capability (Treuhänder/owner) and no automation rule may fire it, which tells the agent when this tool is legitimate. It also clarifies the edge case that approving an already-reversed entry is allowed. It stops short of naming an explicit alternative (e.g. flag_entry or review_status) as the channel for the opposite action.

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=true; the description adds genuinely non-obvious context by clarifying the operation is a soft archive that preserves postings, which tempers the destructive hint. It still omits whether the account remains usable in new postings and whether the change is reversible via unarchive_account.

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

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

A single front-loaded sentence plus a parenthetical that earns its place by disambiguating soft vs hard deletion. No filler, though the parenthetical shorthand is terse enough that it verges on under-specification.

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 state-changing tool with no output schema, the description covers the core effect and retention behavior but leaves the agent guessing about parameter meaning, permission requirements, and post-conditions (can the account still be posted to or reported on).

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

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

Schema description coverage is 0%, so the description carries the full burden for the two required parameters, yet it says nothing about accountId or workspaceId — not even tenant scoping or whether the accountId must be active/non-system. The names are largely self-explanatory, which keeps this above a 1.

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 (archive an account), so an agent can distinguish it from delete_account, update_account and unarchive_account without opening a schema. It does not name those siblings explicitly, so differentiation is inferred from the verb rather than stated.

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

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

The parenthetical 'soft; the account keeps its postings' implies the archive-vs-delete distinction and gives a reason to prefer this over delete_account, but the description never states when to use this tool, what prerequisites apply (e.g. open items, active postings), or that unarchive_account is the escape hatch.

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 state-change semantics beyond the annotations: the rule stops matching, drops out of the default list, and becomes non-enable-able, while run history survives because firings are immutable. That is exactly the 'what is and isn't destroyed' context annotations cannot convey. What it does not state is whether archiving can be undone — notable given there is no unarchive_automation_rule sibling.

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 state change in the first clause, then the non-delete/non-destructive guarantees. The trailing rationale about firings staying true is slightly rhetorical but does explain why history is preserved, so it earns most of its length.

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

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

For a two-parameter mutation with no output schema, the description gives an agent enough to predict the outcome and avoid the destructive reading. The remaining gaps — parameter documentation and reversibility — are the only things 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 0%, so the description carries the full burden of explaining workspaceId and ruleId, and it says nothing about either. The parameter names are largely self-explanatory, which prevents a 1, but no format, scoping, or behavioral meaning is added.

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 ('Retire a rule') and immediately defines the resulting state in terms an agent can act on: stops matching, leaves the default list, cannot be enabled. That phrasing implicitly separates it from the sibling enable/disable_automation_rule tools and from any delete-style tool, so no sibling confusion remains.

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 a delete' and 'stops being enable-able' give clear when-to-use context relative to deleting and to merely disabling a rule. It lacks an explicit alternative ('use archive_automation_rule instead of delete when ...'), but the operative distinctions are recoverable from the described effects.

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 real behavior beyond the lone destructiveHint=true annotation: it discloses the visible effect (removed from pickers), the retained behavior (still referenceable by historical statements/entries), and that nothing is deleted. It does not mention that the action is reversible via unarchive_bank_account or how the destructiveHint relates to the 'never deletes' claim, leaving a mild tension for the agent to resolve.

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, zero filler, with the core effect front-loaded after the verb label. Every clause carries information an agent needs.

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

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

There is no output schema and no annotation coverage beyond destructiveHint, so the description should say what the call yields or what happens on an already-archived account. Preconditions (closed account) and effect are covered, but parameter meaning and return/retry behavior are not, so it is only adequate for a 3-parameter mutation.

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 schema description coverage at 0%, the description carries the full burden and names none of the three parameters (workspaceId, bankAccountId, idempotencyKey). In particular the idempotencyKey and its retry semantics are undocumented anywhere.

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 (hide/archive a Bankkonto) and clarifies the exact semantic of the action: hide from pickers while remaining referenceable. An agent can distinguish this from a delete, though the description never names the directly adjacent siblings (delete_account, unarchive_bank_account, archive_account) that make the choice non-obvious.

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 'a closed Bankkonto' implies the precondition that the account should be closed, which is useful guidance. However there is no explicit when-to-use/when-not, no statement about how this differs from delete_account or when to prefer unarchive_bank_account, so usage is only implied.

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

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

Annotations already declare idempotentHint=true and destructiveHint=true, so the safety profile is largely covered. The description adds one genuinely useful nuance with '(soft)', clarifying the record is retained rather than purged, but it says nothing about reversibility via unarchive_contact, side effects on linked documents/transactions, or what happens on a repeat call.

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

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

A single short sentence with the action front-loaded and no filler. It is efficient, though its brevity is closer to under-specification than to disciplined concision.

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

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

For a mutating, workspace-scoped tool with no output schema and zero parameter documentation, the description is far too thin. An agent cannot tell from it what 'soft' means operationally, whether the contact disappears from list_contacts, or how to recover it.

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

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

Both parameters (contactId, workspaceId) have 0% schema description coverage, so the description carries the full burden of explaining them — and it mentions neither. The names are largely self-evident, but no scoping or format meaning is added.

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 (archive a contact) and the parenthetical '(soft)' signals the archive is a soft delete rather than a hard purge. It does not distinguish itself from siblings such as unarchive_contact or contacts_anonymise, 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 archive versus anonymise, update, or unarchive a contact, and no stated prerequisites or exclusions. The agent must infer the workflow entirely from the tool name and the presence of a sibling unarchive_contact.

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 annotations already declare destructiveHint=true and idempotentHint=true; '(soft)' usefully tells the agent the record is retained rather than purged, which tempers the destructive hint. However, nothing is said about whether existing entries referencing the cost centre block archiving, who may archive, or how to reverse it (presumably unarchive_cost_center).

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

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

It is a single front-loaded phrase with no wasted words, but the terseness crosses into under-specification rather than efficient concision – the one qualifier '(soft)' is doing nearly all the work.

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, two undocumented required parameters, and only hint-level annotations, the description leaves key questions open: side effects on related records, error conditions, and reversibility path. '(soft)' covers one gap but not the rest.

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

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

Schema description coverage is 0% for both required parameters (workspaceId, costCenterId), and the description says nothing about either. With no compensation from the description, an agent gets no guidance on identifier format or workspace scoping beyond the field names themselves.

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 (archive) and resource (cost centre), and the '(soft)' qualifier signals a distinction from delete_cost_center. It does not name the sibling explicitly, but the implication of a reversible archive is clear enough for an agent to differentiate it.

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

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

There is no statement of when to use this instead of delete_cost_center, unarchive_cost_center, or archive_account. The agent must infer from the '(soft)' hint alone that this is the non-destructive retirement path, and no prerequisites or conditions are given.

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

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

Goes well past destructiveHint=false by explaining exactly what survives (templates frozen onto issued documents keep rendering) and exactly what changes (removed from active list and from new defaults). This is the precise reversal/recoverability information an agent needs before mutating a template.

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 tight sentences, the action and its scope front-loaded, the non-destructive reassurance second. Nothing is padded and no sentence is redundant.

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

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

Behavioral semantics are excellent for a mutation with only destructiveHint available, and no output schema means return values needn't be explained. However, the complete absence of parameter guidance (including the idempotency key, which matters for a retryable archive) leaves a real completeness gap.

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

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

Schema description coverage is 0% across three parameters, yet the description never mentions templateId, workspaceId, or especially idempotencyKey. With the schema carrying no meaning of its own, the description fails to compensate for the 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 ('soft-archive') and resource ('a template'), plus its secondary effect ('clear it as default'), which cleanly separates it from create_document_template, update_document_template and set_default_document_template. It doesn't explicitly name a sibling, so differentiation is implied rather than stated.

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

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

The 'NOT destructive' framing hints at when this is the right choice over a hard delete, but there is no explicit when-to-use, when-not-to-use, or prerequisite (e.g. permissions, whether the template must be inactive first). The agent must infer context from the semantics paragraph.

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 destructiveHint=false it explicitly clarifies the semantics ('Never a delete: every value already stored survives and stays readable through list_field_values'), which is exactly the reassurance an agent needs before mutating a schema object. It also discloses the return payload (count of saved views still naming the field) despite there being no output schema, and frames the caller's follow-up action (warn the user).

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, each carrying distinct information: purpose, non-destructive guarantee, and return value. The most important constraint (it is not a delete) 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 simple 3-parameter mutation with no output schema, the description covers effect, safety, side effects, and the return shape. The only real gap is the undocumented parameters, especially idempotencyKey.

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

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

Schema description coverage is 0% for all three parameters, and the description says nothing about workspaceId, fieldDefId, or the idempotencyKey — notably the idempotencyKey, whose retry semantics are non-obvious. The names are largely self-explanatory, but the description does not compensate for the coverage gap.

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

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

States a specific verb and resource ('Archive a custom field') plus the operational effect ('stops being offered as an input'), which cleanly separates it from define_field, confirm_field, set_field_value and list_field_defs in the sibling list.

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

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

The condition for use is clear — retiring a field from the input surface while keeping its data — and it points to list_field_values as the way to still read stored values. It stops short of explicitly naming when not to archive or which sibling to use instead of archiving, but the context is unambiguous.

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

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

Annotations already declare idempotentHint=true and destructiveHint=true, so the safety profile is covered. The description adds the useful 'soft' nuance (state change rather than physical removal), but omits whether the item disappears from list_items, whether it blocks downstream transactions, or what is required to restore it.

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

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

A single three-word sentence with zero filler and the key qualifier ('soft') front-loaded. It is efficient but borders on under-specification rather than tight writing.

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-required-parameter mutation with no output schema and zero schema descriptions, the definition leaves the agent guessing on identifier semantics, side effects, and reversibility. Annotations cover safety only; the rest of the burden is unfilled.

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

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

Schema description coverage is 0% and both parameters (workspaceId, itemId) are bare strings with no format, scope, or constraint notes. The description adds nothing about which item/workspace identifiers are expected, so the documentation gap is left entirely unfilled.

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

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

Names a specific verb and resource ('archive an item') and the '(soft)' qualifier signals it is not a hard delete, which is meaningful next to siblings like delete_item and unarchive_item. It stops short of naming any sibling to differentiate further.

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

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

No when-to-use or when-not-to-use guidance: nothing says how this differs from delete_item, unarchive_item, or serial_archive/asset_archive, and no prerequisites (permissions, item state) are mentioned. The agent must infer the routing entirely from the tool name.

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

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

Goes well beyond the annotations: explains it is never a delete, that historical attributions still resolve, the exact failure mode with error code (role_in_use) while the role is held, and the reversibility path (you can define a role with the same rights again). That is exactly the extra context annotations cannot carry.

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

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

Front-loaded and readable, but the CONSEQUENCE sentence largely restates the first sentence ('refused while any member still holds it' appears twice), so part of the text does not earn its place against a hard length constraint.

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

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

Behavior is fully covered for a mutation with no output schema, and the refusal/error behavior is spelled out. However, with 0% schema coverage on all three required parameters, the definition leaves an agent unable to determine argument intent or idempotency-key expectations from any source.

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

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

Schema description coverage is 0% and three parameters are required, yet the description never mentions roleId, workspaceId, or idempotencyKey. The agent is told the role_in_use error but not what identifies the role, nor that idempotencyKey must be supplied even though idempotentHint is true.

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 with precise semantics: 'Soft-flag a custom role so it stops being offered.' The word 'custom' plus the role vocabulary separates it cleanly from define_role, set_role, list_roles and revoke_member in the sibling list.

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?

Implies the triggering condition (a custom role should no longer be offered) and adds a hard prerequisite: the call is refused while any member still holds the role, which tells the agent to reassign members first. It stops short of naming the sibling operations that satisfy that precondition.

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: bookkeeping data stays intact and exportable (cited to OR 958f), reads continue to work, and any other write into an archived workspace fails with the specific code workspace_archived. This explains the consequence that makes destructiveHint=true meaningful while clarifying that no data is destroyed. It adds no note on required permissions, but the core behavioral contract is fully 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?

Two dense sentences, front-loaded with the state semantics before the safety caveats; every clause carries information. The leading German label "Archivieren:" is mild redundancy against an English description but does not obscure the content.

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

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

For a state-mutating toggle with no output schema and 0% schema coverage, the description covers the essential contract: reversibility, data preservation, read availability, and the failure mode for other writes. The remaining gap is the role of idempotencyKey and any permission/auth requirement for archiving a workspace.

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

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

Schema description coverage is 0%, and the description fully explains only `archived` (true/false semantics), which is the crux parameter. `workspaceId` and `idempotencyKey` get no mention at all, so two of three required parameters remain undocumented in both schema and description; the idempotentHint annotation only partially compensates for the latter.

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 pair (archive a workspace/mandate) and disambiguates the direction of the operation: archived:true retires, archived:false restores. It also explicitly separates itself from a delete, which is the main confusable sibling operation in this tool family (archive_account, asset_archive, files_delete).

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 conditions for both directions of the flag ("retire a finished mandate" vs "put it back in play"), which resolves the main usage ambiguity for a toggle tool. It does not name an alternative tool or state when not to use it (e.g. when to export or delete instead), so it stops short of explicit routing.

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

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

Annotations only declare idempotentHint and destructiveHint; the description goes far beyond by disclosing the atomic sub-ledger + GL posting, the cost-base lock, the full error-code surface, and exact idempotent replay semantics (returns the original {asset, transaction, journalEntry}, no second entry). The CONSEQUENCE paragraph even explains the reversal path, which is precisely the context an agent needs before committing a locking 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?

Purpose is front-loaded, then mechanics, then error surface, then a clearly labelled CONSEQUENCE block, so the structure is navigable. It is a dense single paragraph with heavy parenthetical error codes and internal references (H02, A02, A03, H01) that an outside agent cannot resolve, which slightly hurts scanability.

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

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

For an 11-parameter, no-output-schema mutation, the description covers side effects, refusals, idempotency and even the return shape, which is unusually complete. The gaps are minor: no mention of required permissions/account roles and no explanation of the 'description' parameter.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for most inputs: creditAccountId type constraints and error codes, residualValueRappen's 0..cost range, costCenterId's effect on both legs, source enum values with sourceDocumentId linkage, and acquisitionCostRappen's >0 rule via invalid_cost. Only workspaceId and the generic 'description' parameter go unexplained.

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

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

States a specific verb and resource ('Record the PRIMARY acquisition of a draft fixed asset'), and the word 'PRIMARY' plus 'the first financial event' cleanly separates it from subsequent-capitalisation siblings such as asset_add_capitalisation and asset_opening_balance. An agent can distinguish it from other asset tools without opening a schema.

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

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

The 'PRIMARY / first financial event' framing implies when this tool applies versus top-up or opening-balance tools, and the refusal conditions (already_acquired, asset_not_acquirable) make the boundary explicit. It never names an alternative tool outright, so the routing is strong but inferred 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 declare readOnlyHint=true and the description aligns with it by stating 'Pure read, §H-TENANT'. Beyond the annotation it adds valuable behavioral context: ISO dates are inclusive, an empty range is an empty success, footer totals are returned, and the source field covers source_document_type or 'manual'.

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

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

A dense single sentence enumerating output fields, followed by two short sentences for totals, empty-range behavior, and read-only status. Front-loaded with the purpose; every element earns its place, though the field enumeration makes it long.

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?

Since there is no output schema, the description carries the full burden of describing the return shape, and it does so thoroughly: all fields, footer totals, filters, and the empty-range success behavior. Missing only minor details such as result ordering and pagination limits.

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 0% schema coverage, the description must compensate. It adds meaning for fromDate/toDate (ISO, inclusive) and filter.categoryIds/locationIds (optional), but the required workspaceId parameter is never mentioned, leaving a gap for a required input.

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

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

The description names a concrete resource and scope: 'What was capitalised in a period (H09, US-H09.5)' covering acquisition and additional-capitalisation events (H02). It lists output fields explicitly and is clearly distinguishable from siblings like asset_acquire (a mutation), asset_transaction_list (all transactions), and asset_depreciation_* (depreciation).

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 clear usage context: it is the H09/H09.5 capitalisation report, a pure read, with date-range and optional category/location filters. It does not explicitly name alternatives or state when-not-to-use, but the scope definition is precise enough to route an agent correctly.

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

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

The description richly discloses behavior beyond the annotations: atomic sub-ledger plus journal posting, Dr asset / Cr creditAccountId pattern, increases to acquisition_cost and net_book_value, unchanged accumulated depreciation/residual/useful life, prerequisites, error conditions, idempotency, and reversal consequences. This is well beyond what idempotentHint and destructiveHint provide.

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

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

The definition is front-loaded with the core purpose and then layers in mechanics, prerequisites, and consequences. It is dense but mostly earns its length; the long second sentence is packed but still relevant to correct invocation.

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

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

For a complex accounting mutation with no output schema, the description supplies enough behavioral, accounting, precondition, and reversal context to call it correctly. The missing output details are not material because no output schema exists.

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 0% schema description coverage, the description must carry parameter meaning. It explains amountRappen, creditAccountId, idempotencyKey, and partially assetId/date/sourceDocumentId through accounting and period-rule context, but leaves workspaceId, source, description, and costCenterId undocumented.

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

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

The description uses a precise verb and resource: capitalising additional cost onto an already-acquired asset, specifically for an improvement or major overhaul. It clearly distinguishes this from initial acquisition by emphasizing ADDITIONAL cost and naming the sub-ledger transaction type.

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 usage context: only for a live asset that already carries a primary acquisition, with explicit error states when not acquired or disposed/archived. It references asset_acquire for shared credit-account, source-document, and period rules, though it does not explicitly say when to choose asset_acquire instead.

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

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

Annotations only declare idempotentHint and destructiveHint=false; the description adds real behavioral context beyond them: the resulting status, that the record remains readable, the specific error code asset_in_use, and the ledger-dependency rationale. It does not contradict the non-destructive annotation. Missing is what a caller gets back or whether unarchive exists.

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

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

The core effect is front-loaded and the size is reasonable, but the parenthetical '(an asset the ledger still depends on cannot be hidden; dispose it via H06 instead)' is dense and the closing sentence partially restates the refusal rule in a way that muddies rather than sharpens it.

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 should carry return-value expectations, and it says nothing about what a successful archive returns. Combined with zero parameter coverage and the eligibility ambiguity, the definition is adequate on semantics but incomplete for a mutating lifecycle operation.

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

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

Schema description coverage is 0% across three required parameters (workspaceId, assetId, idempotencyKey), so the description must compensate, but it mentions none of them. Notably the idempotencyKey — the most non-obvious parameter for a mutating call — gets no explanation of expected format or reuse semantics.

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 plus the resulting state ('Soft-archive an asset (status=archived)') and contrasts it with disposal, so an agent can distinguish it from asset_dispose or asset_transfer. The contrast is weakened by referring to the alternative only as the opaque code 'H06' rather than naming the 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?

It does give a when-not condition ('Refused with asset_in_use while the asset is active or fully_depreciated') and points at disposal instead. However, the final sentence ('Only a draft or already-terminal asset may be archived') sits in tension with the refusal list — fully_depreciated reads as both a terminal state and a refusal — leaving the agent to guess the exact eligibility set.

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

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

Annotations only declare idempotent and non-destructive; the description adds the substantive behavior: this is a soft archive that keeps historical resolvability, it can fail with a named error (category_in_use), and no hard delete exists. That is exactly the extra context annotations cannot convey.

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

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

Three sentences, front-loaded with the operation and its effect, then the failure condition, then the no-delete rationale. No filler and no repetition of the name.

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

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

For a mutation tool with no output schema, the description covers effect, failure mode, and the deliberate absence of a delete path. The remaining gap is parameter-level guidance (idempotencyKey behavior, workspace scoping), which matters but is secondary to the behavioral picture it paints.

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?

All three parameters (workspaceId, categoryId, idempotencyKey) have 0% schema description coverage, so the description must carry the burden. It only implicitly references the category being archived and says nothing about workspaceId scoping or what idempotencyKey does on retry.

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 ("Soft-archive a category") and immediately defines the mechanics: active=false, leaves the default picker, stays resolvable. It is clearly distinguishable from siblings like asset_category_update, asset_category_get, or item_categories_delete.

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

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

Gives a concrete refusal condition (category_in_use when any asset, even disposed, references it) and rules out deletion entirely, which steers the agent away from a wrong path. It stops short of naming sibling tools such as asset_category_update as the alternative for renaming or reactivating.

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

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

Goes well beyond the annotations by disclosing inheritance behavior, required GL account type constraints, uniqueness semantics for code, specific error codes (duplicate_code, invalid_account_type), and the fact that invalid account types are refused before any write. This gives an agent substantial operational detail for a mutation tool.

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

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

The description is front-loaded with purpose and inheritance semantics, then validation details. It is dense and packed into a long first sentence, but every clause carries useful operational information and there is little outright waste.

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 create tool with no output schema and sparse annotations, the description supplies the crucial business behavior, field meanings, and validation failure modes. It is still missing some completeness details such as the response shape, idempotency behavior, and workspace scoping, but the core is strong.

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 schema description coverage at 0%, the description does significant work: it explains code length/uniqueness, depreciation method options, useful life in months, residual value as basis points or Rappen, the three GL account roles and type constraints, and the optional default cost centre. It still omits workspaceId, idempotencyKey, name, and description, and does not explicitly map every business term to its parameter name, so it does not fully compensate for the schema gap.

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

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

States a specific verb and resource ('Create a fixed-asset category') and immediately explains the defining behavior: the category carries defaults inherited by every asset created under it. This distinguishes it clearly from siblings such as asset_category_update, asset_category_get, asset_category_list, and asset_category_resolve_defaults.

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

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

The description makes clear this is the creation path for fixed-asset categories and names validation failure cases, giving strong context for when to call it. It does not explicitly route the agent to update/archive/get alternatives or state prerequisites like existing GL accounts, so it falls short of a full when/when-not/alternative statement.

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 annotation readOnlyHint=true already covers safety. The description adds one useful behavioral detail—'archived or not'—indicating the tool returns categories regardless of archive status. However, it omits error behavior, permission requirements, or response shape, so the added transparency is limited.

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

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

The description is a single concise sentence that front-loads the verb and resource. It contains no filler, repetition, or superfluous details, making it efficient and immediately 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?

For a simple read tool with two required parameters and a read-only annotation, the description is adequate but not complete. It does not mention what the response contains, what happens if the category is not found, or how to locate the ID, which an agent might need given the large sibling tool set.

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 0% schema description coverage, the description must compensate, but it only says 'by id,' which loosely maps to categoryId. It does not explain workspaceId, the relationship between the two parameters, or any format/constraints. This adds minimal meaning beyond the schema field names.

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 ('Read'), a specific resource ('fixed-asset category'), and a scoping constraint ('by id, archived or not'). This clearly distinguishes it from sibling tools like asset_category_list (listing) and asset_category_archive (mutation), making the purpose 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?

The description implies the use case—fetching a single category when you have its ID—but does not explicitly mention alternatives or exclusions. An agent must infer that asset_category_list is for multiple categories and that create/update/archive are for mutations, as no routing is provided.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds behavioral details: ordering by code, case-insensitive search over code and name, and acceptance of savedViewId (G00 saved-view seam). However, it does not disclose default behavior (e.g., whether archived items are included by default) or any pagination/limits, which are typical for list operations. With readOnlyHint covering mutation concerns, a 3 is appropriate—adds some value but not comprehensive.

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

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

Two sentences with no waste. The main action is front-loaded, and each clause adds a distinct piece of information (ordering, filters, search scope, savedViewId). The description is compact and well-structured.

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

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

For a read-only list tool with no output schema, the description covers the essential behavior: what is listed, ordering, filters, and the savedView seam. It lacks explicit mention of default filter behavior and pagination, but these are common patterns and the readOnlyHint already signals safety. Overall, the description is adequate for an agent to call 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?

Schema description coverage is 0%, so the description carries the full burden. It explicitly explains all three optional parameters: 'active' (true = only live, false = only archived), 'search' (case-insensitive over code and name), and 'savedViewId' (G00 saved-view seam). The required workspaceId is self-evident from the context. This fully compensates for the missing schema descriptions.

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 the tool lists workspace fixed-asset categories, ordered by code. It distinguishes itself from sibling tools like asset_category_create, asset_category_get, and asset_category_archive by specifying a list operation with ordering. The verb 'List' and resource 'fixed-asset categories' are explicit and 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?

The description implies when to use this tool: whenever a list of fixed-asset categories is needed, optionally filtered by active status or search. It does not explicitly name alternatives or when-not conditions, but the optional filters and mention of the savedViewId seam suggest clear use cases. The absence of explicit exclusions is a minor gap, but the context is sufficient for an agent to decide.

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 readOnlyHint=true, the bar is lower. The description discloses what data is returned (depreciation trio, GL accounts, cost centre) and the refusal behavior for archived categories (category_archived). This adds useful context beyond the annotation and is consistent with it.

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

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

Two sentences with no wasted words. The primary purpose is front-loaded, and the error case is appended succinctly. Every sentence adds value.

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

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

Since there is no output schema, the description properly explains the return content (the specific data fields) and the error condition. It asserts completeness ('FULL default set') and the goal of enabling asset creation without further questions, so nothing critical is missing for an agent to use 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?

Schema description coverage is 0%, so the description must compensate. It mentions 'for a category' which implies categoryId, but does not explicitly define workspaceId or provide parameter-level detail. The two parameters are obvious from the tool name and context, but the description does not add much beyond what the schema names convey.

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 action: 'Resolve the FULL default set for a category' and enumerates exactly what is resolved (depreciation trio, GL accounts, cost centre). It also clarifies the purpose ('so an agent can create an asset (H01) with no further questions'), which clearly distinguishes it from asset_category_create/update/archive siblings.

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

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

The description implies when to use: when creating an asset, call this to obtain defaults. It also provides guidance on the archived-category error ('choose another or un-archive first'), which is a useful fallback. However, it does not explicitly mention alternatives or exclusions, though the use case is clear from the context.

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

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

With annotations already declaring idempotentHint and destructiveHint, the description adds real value beyond them: the same validation as create applies (account types, useful life, residual bounds), code is immutable here, and absent fields are left untouched. These are non-obvious constraints an agent could not read off the annotations. It stops short of disclosing what happens on validation failure or what the response contains.

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 operation and mechanism, then constraints. Nothing is repeated from the name or schema; every sentence carries information an agent needs.

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

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

For a nested-payload mutation with no output schema, the description covers the key risks: validation parity with create, immutability of the code field, and partial-update semantics. Missing only edge behavior — an empty patch, whether categoryId accepts code or id, and failure modes — which 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?

Schema description coverage is 0%, so the description must carry the semantic load. It does explain the most consequential part of the payload — patch semantics where only present fields change — and flags that code is not patchable, which is not visible in the schema. But the ten nested properties receive no field-level meaning, and workspaceId, categoryId and idempotencyKey are entirely unaddressed.

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

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

Names a specific verb and resource ('Edit a fixed-asset category') and immediately constrains the mechanism to a patch object. That distinguishes it from asset_category_create (which the description references) at a conceptual level, but siblings like asset_category_archive or asset_category_get are never named, so the differentiation is inferred rather than stated.

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

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

Usage is implied: partial edits go through this verb, and 'code is immutable through this verb' hints that a different route exists for changing a category's code. However, no alternative tool is named and there is no explicit when-not-to-use guidance (e.g. archiving vs editing vs creating a new category).

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

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

Beyond the annotations, it discloses inherited defaults, allowed overrides, unique number generation and duplicate_number failure, category_archived refusal, draft creation status, and immutability after a posted H02 acquisition. This is substantial behavioral context for a create operation.

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-loaded around the core create-from-category behavior, and most sentences carry useful business rules. It is somewhat packed into one paragraph with many semicolon-separated details, but not wasteful.

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 25-parameter creation tool with no output schema and no schema descriptions, the description covers the core financial and inheritance behavior well. It is still incomplete around required workspace/category/idempotency parameters and retry semantics, and the claim that only three fields are required is misleading against 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?

With 0% schema description coverage across 25 parameters, the description adds useful meaning for acquisitionCostRappen, acquisitionDate, name, number generation, and override fields. But it says only name, acquisitionDate, and acquisitionCostRappen are required while the schema also marks workspaceId, categoryId, and idempotencyKey as required, and it leaves idempotencyKey semantics and many optional fields unexplained.

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

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

The description states a specific verb and resource: create a capitalised fixed asset from a category. It also distinguishes the inheritance model from generic asset creation by naming depreciation method, useful life, residual rule, and GL accounts.

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 frames this as creation from a category with inherited defaults and notes the archived-category refusal condition. However, it does not explicitly route agents away from sibling tools such as asset_acquire, asset_opening_balance, or asset_add_capitalisation.

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 readOnlyHint=true annotation, the description adds 'Writes nothing; deterministic for a given snapshot' and details error/warning behaviors (invalid_period_range, invalid_input, not_found, production_data_required). This goes well beyond the annotation's read-only hint and informs an agent of failure and warning conditions.

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

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

The single dense paragraph carries no filler; every clause maps to a schema field, output field, or behavioral constraint. It front-loads the core purpose and consistency guarantee before diving into parameter semantics.

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 supplies a detailed return contract: ordered periods, totalAmountRappen, optional byGroup, totalProjectedRappen, assetsReachingResidual, and includeDetail per-asset detail. All 7 parameters and error modes are addressed, making the description sufficient for accurate 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 description coverage is 0%, so the description must compensate, and it does comprehensively: date format (YYYY-MM), month-window cap, reversed/over-long error code, allowed groupBy values, filter dimensions, includeDetail semantics, and unitsForecast relevance. This gives the agent far more than the schema names alone.

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

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

States a specific verb and resource: 'multi-period depreciation forecast' with identifiers H09, US-H09.2. It also differentiates itself from sibling asset_depreciation_preview and asset_depreciation_schedule by describing the multi-period window and the guarantee of consistency with the live schedule.

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 clear context by explicitly referencing the 'preview/schedule verbs' and positioning this as the multi-period forecast that reuses the same pure calculators. It does not explicitly enumerate when-not-to-use or name the alternative to use instead, so it falls just 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?

Beyond the readOnlyHint annotation, the description discloses meaningful behavior: output descriptor fields (labelKey, descriptionKey, requiresUnits, requiresRate, enabled, labelKey) and the effect of disabled methods on H00/H01 pickers. This meaningfully exceeds what the annotation already provides.

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 sentences, each contributing useful information: the resource, the method values, the descriptor fields, and the behavioral consequence of disabled flags. It is dense but not bloated, and the 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?

With no output schema, the description compensates by naming all returned descriptor fields and the allowed method enum values. It also clarifies the read-only nature and the visibility behavior, which is enough for an agent to understand what it will receive and how to interpret it.

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

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

The single required parameter workspaceId is not explicitly documented; the description only indirectly refers to 'this workspace.' With 0% schema description coverage, some compensation is expected, but workspaceId is a simple required string and the schema property name is mostly self-explanatory. The description does not add much parameter-level detail, so 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 action ('List') and a clear resource: registered depreciation methods, and even enumerates the possible values: straight_line, declining_balance, units_of_production, none. It also identifies the returned descriptor fields, making it easy to distinguish this read-only listing tool from the sibling asset_depreciation_method_set_enabled.

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

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

The description gives useful context: each descriptor carries enabled flags and disabled methods are hidden from pickers, so an agent can infer this is the appropriate tool for inspecting available depreciation methods. It does not explicitly name alternatives like asset_depreciation_method_set_enabled or list when not to use it, but the context is clear enough.

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 two annotations: it explains the default-state rule ('Absence means enabled, so this only records a method switched off'), an invariant that can never be violated (the none method), and the two named error outcomes (method_locked, unknown_method). The stated idempotency on the (workspace, method) row is consistent with idempotentHint=true, and the mutation framing is consistent with destructiveHint=true.

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 with the core action front-loaded and error semantics after it; almost nothing is padding. The 'Absence means enabled, so this only records a method switched off' line is compressed to the point of ambiguity given that enabled is itself a required boolean.

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 four-required-param mutation with no output schema, the description supplies default semantics, invariants, error codes and idempotency, which is most of what an agent needs. The notable omission is downstream impact: it never says what happens to existing assets if a method they use is switched off.

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 0% schema coverage the description must carry all four params, and it only partially does: methodKey is covered (unknown key → unknown_method), enabled is obliquely covered via the absence-means-enabled rule, workspaceId is implied by 'for this workspace'. The required idempotencyKey is never explained beyond the row-level idempotency claim, so a caller gains no format or reuse guidance for the param that most needs 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 verb pair plus resource (enable/disable a depreciation method) scoped to a workspace, and flags it as a setup action, which separates it from the reporting siblings like asset_depreciation_preview or asset_depreciation_schedule. It never names the closest sibling (asset_depreciation_methods) to say explicitly that this one toggles rather than lists.

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?

'(a setup action)' signals the configuration context but there is no explicit when/when-not or routing to an alternative such as asset_depreciation_methods for reading current state. Usage is only implied by the workspace-scoped toggle framing.

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 readOnlyHint annotation, the description discloses significant behavioral details: it returns a reason when the amount is zero with enumerated possible reasons, states that projectedNbvAfterRappen never goes below residual, describes the rejection of foreign/unknown assetIds with not_found, and explains the effect of proRata and override parameters. This adds rich context beyond the annotation.

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 well-organized: it starts with the core purpose, then return structure, side-effect guarantee, parameter details, and error handling. Every sentence adds value, and there is no fluff. It is a single paragraph but logically segmented, making it effective despite its length.

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

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

Given the complexity of 7 parameters, nested objects, and no output schema, the description covers return types, parameter semantics, error cases, and side-effect behavior. It provides enough detail for an agent to call the tool correctly without additional documentation, including the reason enums and the guarantee about NBV never going below residual.

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 0% schema description coverage, the description compensates by explaining most parameters: period format (YYYY-MM), assetIds (omission means all active), proRata (full_period or actual_days), unitsByAsset (mapping to units produced), and paramsByAsset (overrides for decliningRateBp and totalEstimatedUnits). However, daysByAsset is not explicitly described, and the exact structure of nested objects could be clearer, so it is not fully 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?

The description clearly states the tool's function: preview depreciation amount for a period, either for specific assetIds or all active assets. It specifies the verb 'preview' and the resource (depreciation amount), and distinguishes itself from posting tools by explicitly noting it writes nothing and creates no journal, which separates it from siblings like asset_depreciation_run_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?

The description implicitly guides usage by stating it is a read-only preview that creates no journal, implying it should be used when the agent wants to estimate depreciation without committing. It also explains the behavior when assetIds is omitted (covers all active assets). However, it does not explicitly name alternative tools for posting or other scenarios, so guidance is not fully 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?

Far beyond the annotations: it discloses exactly what is persisted (run header + one line per positive-amount asset), that nothing is written on refusal or on an empty set, the full skipped[] reason taxonomy and its different semantics for explicit assetIds vs sweeps, and the idempotency signature built from the would-be lines. This is consistent with idempotentHint=true and destructiveHint=false rather than contradicting them.

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 correctly — the create/calculate/persist core is in the first sentence — but the rest is a single ~450-word paragraph dense with parenthetical codes and nested conditionals that is hard to scan. Nearly all content is substantive, yet some asides (the period-close checklist rationale for no empty draft) could be trimmed or split into structure.

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

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

No output schema exists, and the description compensates by specifying the response shape ({ok, run, lines, empty, skipped, alreadyPostedRunId}) and every refusal code (invalid_period, period_locked, run_already_exists, not_found, invalid_input). For an 8-parameter mutation with a nested unitsByAsset object, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 0%, so the description carries the load and mostly does: period format (YYYY-MM), assetIds as an explicit subset, categoryId/costCenterId as narrowing filters, unitsByAsset as assetId→whole units with a 1e12 non-negative safe-integer bound, postingGranularity's two modes, and idempotencyKey's role. Only workspaceId goes unexplained apart from the tenant hint on foreign assetId.

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?

Opens with a specific verb+resource+outcome: 'Create a DRAFT depreciation run for a period (H04): calculate the depreciation for every eligible asset via the H03 engine and persist a run header (status=draft) plus one line per asset'. It also separates itself from siblings by naming the post verb ('Writes NO journal (the post verb does)') and by referencing the preview's shared shape.

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 eligibility predicate (active/fully_depreciated, method != none, NBV above residual, last_depreciation_period null or earlier, not disposed), names the alternative verb for posting, and states when NOT to expect a result (already-posted period returns the empty answer with alreadyPostedRunId). An agent can decide create-vs-post-vs-preview without opening another schema.

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 annotation readOnlyHint=true already marks this as read-only, and the description reinforces this with 'Read'. More importantly, it goes beyond the annotation by detailing the exact data payload (header fields, line fields, ordering) and disclosing a specific error condition (foreign runId returns not_found). This is valuable behavioral transparency that helps the agent set expectations.

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 long but well-structured: it leads with the primary purpose, then itemizes header fields, then line fields, and ends with a tenant-specific note. Every sentence adds information, and the format is easy to scan. It is not overly verbose given the amount of detail needed to enumerate the response.

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?

Without an output schema, the description must stand alone in explaining what the tool returns. It does so exhaustively, listing all header and line attributes including nested items like GL account ids and unitsProduced. It also covers edge cases (reversing link, foreign runId). Given the tool's complexity, the description is remarkably 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?

With 0% schema description coverage, the description carries the burden. It implicitly links runId to the id being read and mentions 'foreign runId' which clarifies scope. The workspaceId is not elaborated, but the tenant note implies it's the tenant context. It does not explicitly map each parameter, but it provides enough to understand their roles in this context.

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

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

The description opens with a specific verb ('Read'), a clear resource ('one depreciation run by id'), and an explicit objective. It enumerates exactly what will be returned (header fields plus every line with all fields), leaving no ambiguity about the tool's function. It is distinct from sibling tools like asset_depreciation_run_list or create because 'Read' implies a singular fetch by id.

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

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

The description clearly implies usage when the agent has a specific runId and needs the full detail of a single run. It does not explicitly name alternatives or state when not to use it, but the verb and resource make the intent unambiguous. Given the large sibling set, an explicit cross-reference to list or create would elevate it, but the current text suffices.

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 readOnlyHint annotation already marks the tool safe, and the description reinforces it with 'Read-only.' Beyond the annotation, it adds behavioral specifics: ordering newest first, exact period format, and allowed status values. It does not mention pagination or response shape, but the added context meaningfully exceeds annotation coverage.

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

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

Two compact sentences with no filler. The primary purpose is front-loaded, followed by the optional filters and a closing read-only note. Every sentence contributes information.

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

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

The description covers the essential selection context: what is listed, ordering, filters, and status vocabulary. Since there is no output schema, the agent still lacks guidance on returned fields, pagination, or response structure, which is a meaningful gap for a list endpoint.

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 0% schema description coverage, the description must carry parameter meaning. It does explain period format, status values, and the from/to window. However, it leaves workspaceId implicit and does not define the exact format or inclusivity of the from/to endpoints, so coverage is useful but incomplete.

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 ('List'), a precise resource ('workspace depreciation runs (H04)'), and an ordering guarantee ('newest period first'). This clearly distinguishes it from sibling tools like asset_depreciation_run_get or asset_depreciation_run_create by establishing that this is the read-only list operation.

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

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

The description communicates clear context: list runs for a workspace, optionally filtered by period, status, and date window. However, it does not explicitly say when to prefer this over closely related siblings such as asset_depreciation_run_get (single run retrieval) or asset_depreciation_preview/schedule (projections), leaving the selection partly implicit.

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

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

Annotations only declare idempotentHint=true and destructiveHint=false; the description goes far beyond by disclosing the atomic transaction scope, the exact writes performed (GL journal, append-only asset_transactions, asset field updates, status transitions), and the full refusal taxonomy with reason codes. It also clarifies that a stale draft is never silently recomputed — a non-obvious, high-consequence behavioral guarantee.

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?

Dense but front-loaded: the primary action and its effects come first, then date rules, then refusals, then idempotency. Minor waste from restating idempotency twice ('NO second journal' and then 'posting it twice never counts twice'), but nearly every sentence carries operational meaning.

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 high-stakes posting operation with no output schema, the description covers side effects, error conditions, idempotency, tenant scoping, and the consequence of an incorrect post. An agent has everything needed to decide whether to call it and what to expect.

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

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

Schema coverage is 0%, so the description must compensate, and it does heavily for postingDate (default of last day of period, may be late but never before period start, must not predate acquisition, with before_period/before_acquisition reasons) and idempotencyKey (re-post returns original result). runId and workspaceId are only implicitly covered (tenant isolation via §H-TENANT), leaving a small 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 and resource ('Post a reviewed DRAFT depreciation run') plus the exact accounting effect (Dr expense / Cr accumulated depreciation via A02). It is unmistakably distinct from sibling read tools like asset_depreciation_run_get or asset_depreciation_preview.

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?

Explicitly targets a reviewed DRAFT run, and names the alternatives for the edge cases: recreate the run rather than re-post a stale draft, and 'reverse the run with a correcting entry' if wrong. It also states when the tool refuses (period_locked, stale_draft, run_reversed), which is usable routing information.

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

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

Annotations only declare idempotentHint=true and destructiveHint=false; the description goes far beyond, detailing the A02 reverseEntry call, compensating asset_transaction creation, per-field restoration of accumulated_depr_rappen/net_book_value_rappen/status/last_depreciation_period, and that originals are never mutated per §H-AUDIT. It also surfaces idempotency behavior, tenant scoping (§H-TENANT), and the full refusal vocabulary.

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 consequence and core operation are front-loaded, and every sentence carries operational content (error codes, ordering rule, nullability of history). It is dense and long-winded in places, but the density is justified for a high-risk reversal tool rather than padded.

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

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

For a mutation tool with no output schema and an undocumented input schema, the description supplies everything an agent needs: side effects, refusal modes, ordering constraints, idempotency, tenant scoping, and the recovery path after an incorrect reversal. Nothing material 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?

With 0% schema description coverage, the description carries the burden well: reverseDate defaults to period end and may not predate the run period's first day (invalid_input names the field), reason is recorded on the reversing entry and compensating transaction, and idempotencyKey drives idempotency. Only workspaceId is left unexplained, keeping this just 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?

States a specific verb (reverse), the exact resource (a POSTED depreciation run, H04) and the triggering condition (material error found), plus the key differentiator that history is not rewritten. An agent can distinguish this from asset_transaction_reverse, reverse_entry, or asset_depreciation_run_post 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?

Explicitly names when to use it (material error in a posted run) and enumerates the conditions that select against it: run_not_posted for drafts, already_reversed, period_locked, and later_run_exists with the newest-first ordering rule spelled out. It also states the correct follow-up path (create and post a new run).

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 readOnlyHint annotation, the description explicitly says 'Writes nothing' and details edge-case behavior: the final line residual-adjusts to match cost minus residual, units_of_production assets require a unitsForecast or return an incomplete projection with a warning, and a foreign assetId yields a not_found error. This is rich behavioral disclosure that far exceeds the annotation's minimal signal.

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 yet efficient, with every sentence contributing distinct value: purpose, output shape, residual behavior, units_of_production caveat, and safety/error semantics. It is front-loaded with the core action and remains readable without unnecessary jargon.

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

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

Given the absence of an output schema and 0% param coverage, the description provides a complete-enough contract: return row fields, residual adjustment guarantee, unitsForecast requirement, and error code reference. It leaves little ambiguous for an agent deciding whether and how to call this 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?

With 0% schema description coverage, the description compensates well by explaining fromPeriod's format and inclusivity, toPeriod as optional, and unitsForecast's required shape for units_of_production assets. It does not explain proRata or params, but the most critical parameters are semantically defined in plain language, which is a strong addition given the schema is silent.

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 and resource: 'Project the full remaining depreciation schedule for ONE asset', and immediately distinguishes itself from the sibling preview tool by noting it uses 'the same pure engine as the preview so a line never disagrees with a live preview'. This makes the tool's purpose unmistakable and separates it from asset_depreciation_forecast or asset_depreciation_preview.

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

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

The description gives clear context: it projects the full remaining schedule for one asset over a date range, and explicitly ties its behavior to the preview engine for consistency. It does not name alternatives or state when not to use it, but the scoping to 'ONE asset' and the optional toPeriod strongly imply when this tool is appropriate vs. other asset tools.

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 readOnlyHint annotation already covers non-mutation. The description adds meaningful behavior beyond that: not_found on invalid ids, cross-tenant concern (§H-TENANT), and the fact that the returned data includes the posted GL journal entry.

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

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

Two dense sentences with no filler. The purpose is front-loaded, then the error/scope constraint is added precisely. Every clause earns its place.

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

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

For a simple get-by-id with no output schema, the description states the return contains the posted GL journal entry and explains invalid-id behavior. It does not explicitly walk through workspaceId, but the tool is simple enough that the description is nearly 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?

With 0% schema description coverage, the description carries the burden and mostly succeeds: it explains transactionId must name a disposal-type asset_transaction and what happens with foreign or wrong-typed ids. workspaceId is only implied as the workspace scope via 'in this workspace', which is useful but less explicit.

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 ('Read'), a specific resource ('fixed-asset DISPOSAL sub-ledger transaction by id (H06)'), and the key return content ('balanced GL journal entry'). The 'DISPOSAL' qualifier clearly differentiates it from generic asset_transaction_get and from disposal preview/dispose verbs.

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

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

It gives explicit exclusion semantics: transactionId must be a disposal-type asset_transaction, and foreign or acquisition/depreciation ids return not_found rather than leaking the wrong event. This tells an agent when not to use the tool, though it does not name a specific alternative 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 provide readOnlyHint=true, so the description's emphasis on 'WITHOUT posting anything' and 'Pure read' aligns with that. It goes beyond annotations by detailing what the tool does NOT do (does not check period lock) and what it returns (detailed journal lines). This adds context about execution behavior and side-effect absence, which is valuable. However, it could have also disclosed potential performance or rate-limit traits, but that's not critical.

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 well-structured, front-loading the core purpose and key constraints, then detailing the return value and refusal reasons. Each sentence adds critical information with no fluff. It's longer than average, but every clause earns its place given the complexity of the disposal logic.

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

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

Given the complexity of asset disposal (multiple accounts, conditional parameters, validation rules), the description is comprehensive. It explains what the tool returns, how the journal lines are constructed, and all refusal scenarios. The only minor gap is that it doesn't explicitly describe the output schema for the journal_lines structure (e.g., exact field names), but since there is no output schema defined and the description already provides a textual breakdown, it is sufficiently complete for an agent to understand the result.

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

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

Schema description coverage is 0% in structured form, so the description compensates by explaining each key parameter's role, especially the nuanced validation (proceedsRappen >= 0, gainLossAccountId type, proceedsAccountId conditional). It clarifies the purpose of optional fields like notes/reason/counterpartyName implicitly by listing them in the schema, but the description adds meaningful context for the core parameters. It does not detail every parameter but covers the ones essential for correct invocation.

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 explicitly states the tool's purpose: to preview the disposal journal for an asset without posting. It specifies the exact resource (fixed asset H06), the action (preview), and distinguishes it from the posting tool. It names the key output elements (lines, gain/loss calculation) and explains the 'same lines' guarantee, which is clear and non-ambiguous.

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

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

The description clearly states when to use this tool (to see what a disposal would book before posting, especially if period lock is unknown) and contrasts it with asset_dispose. It also provides explicit conditions for required parameters (e.g., proceedsAccountId needed when proceeds > 0) and lists all refusal reasons, giving agents complete routing information.

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 readOnlyHint annotation, the description adds valuable behavioral context: it is a 'pure read over the append-only sub-ledger', and it explicitly states that 'no disposals in range is an empty success, not an error'. It also explains the sign convention of gainLossRappen. This fully discloses behavior beyond the annotation.

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 efficient. It front-loads the purpose, then lists output fields, footer totals, and filters in a logical flow. Every sentence adds necessary information without fluff. It is appropriately sized for the complexity of the tool.

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

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

Given the tool's complexity, zero schema description coverage, no output schema, and a large sibling list, the description covers all essential aspects: input parameters, output fields, footer totals, filtering options, empty result behavior, and read-only nature. An agent can call it correctly and interpret results without additional context.

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 0% schema coverage, the description fully compensates. It specifies date format (ISO YYYY-MM-DD) and inclusivity, explains the filter semantics (categoryIds, locationIds, case-insensitive reason substring), and clarifies the output fields. WorkspaceId is not described but is a common contextual parameter, likely understood from the environment.

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 (implied get), resource (disposal gain/loss pack), and scope (date range). It names the exact record set (H06 disposals) and lists output fields. This clearly distinguishes it from related tools like asset_disposal_get or asset_disposal_preview.

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

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

The description specifies the date range and optional filters, making the tool's use case clear. It does not explicitly name alternative tools or say when not to use it, but the context of a summary report over a range is evident from the wording. It lacks explicit exclusions but provides enough guidance.

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

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

Annotations only declare idempotentHint and destructiveHint=false; the description goes far beyond, disclosing atomicity, the exact append-only records written, which fields are zeroed versus preserved for historical reporting, the gain/loss sign rule, the scrap special case, tenant isolation (§H-TENANT), period locks, and a full enumerated refusal set. Idempotency semantics on idempotencyKey are spelled out concretely (replay returns the original payload, posts no second journal).

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

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

The single dense paragraph is front-loaded with the action and structured with (a)/(b)/(c), which helps, but it also embeds GL debit/credit mechanics that are implementation detail rather than agent-actionable, and the closing CONSEQUENCE paragraph restates the opening ('takes it out of the register' / 'reverse the disposal'). Length is partly justified by 0% schema coverage, but trimming the accounting internals and the duplicate summary would lose nothing.

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 supplies the return shape ({asset, transaction, journalEntry, gainLossRappen}), the full error taxonomy, the post-condition state of the asset, and the reversal-based correction model. An agent has everything needed to call it correctly and to interpret a refusal.

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

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

Schema description coverage is 0% with 10 parameters, so the description must carry the load — and it does for the consequential ones: proceedsRappen (0 means scrap, no proceeds line), proceedsAccountId (not required for scrap), gainLossAccountId (sign driven by proceeds minus NBV), disposalDate (period-lock interaction), idempotencyKey (replay behavior), and assetId (foreign asset yields not_found). The peripheral fields notes, reason, counterpartyName, and workspaceId are never explained, keeping it below 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?

Opens with a specific verb+resource ('Dispose an active or fully_depreciated fixed asset (H06)') and immediately qualifies it as the terminal financial event, enumerating the covered transaction types (sale, scrap, donation, write-off, retirement). This is unmistakably distinct from siblings such as asset_transfer, asset_archive, or asset_update, which the description explicitly says will refuse the asset afterwards.

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?

States the preconditions and exclusions clearly: only active/fully_depreciated assets, drafts rejected with asset_not_acquired, archived assets rejected, second dispose refused with asset_already_disposed, and hard-locked periods refused. It also prescribes the correction path (reverse the journal plus compensating transaction, never un-dispose). It stops short of routing the agent to asset_disposal_preview for a dry run, which would have made it 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?

Beyond the readOnlyHint annotation, it explains that the tool projects active depreciable assets forward from the current period, filters by remaining life within a capped window, orders results soonest first, and writes nothing. This gives the agent a clear safety and behavior profile.

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 and dense with useful facts, with no filler. It is a long single sentence with some domain shorthand (H09, §H-TENANT) that adds context but could be slightly tightened for 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?

For a list/report tool with no output schema, it tells the caller exactly what comes back: current NBV, residual, remainingMonths, and next forecasted depreciation, plus ordering. The required parameter, status modes, and withinMonths cap are all covered, so no critical usage information 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?

With 0% schema description coverage, the description carries the parameter explanation: it defines status values and withinMonths default/cap. It does not explicitly describe workspaceId semantics, but that parameter is self-evident and named as required in the schema.

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

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

The description names a specific resource (assets at or approaching end of life), states the supporting report codes H09/US-H09.8, and contrasts the approaching vs fully-depreciated views. This is enough to set it apart from generic asset listing tools such as asset_list or asset_depreciation_schedule.

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 explains the default mode, when to use status='fully_depreciated', and how withinMonths affects results. It gives clear context for using this tool, though it does not explicitly name sibling alternatives or exclusions, which keeps it from 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 readOnlyHint=true, so the description's 'Read' matches. It adds value by disclosing the specific return contents (resolved financial baseline, GL accounts, convenience columns), which is more than a generic read. It does not mention auth or rate limits, but for a read-only tool with the annotation, the bar is met.

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