Helvabase — Governed response dossiers

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds one extra behavioral fact — the recorded version is left "unreviewed" (matching the missing_review default) — which is useful context an agent would not get from annotations alone, but it says nothing about permission requirements or the effect on prior versions.

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 core action front-loaded and the exclusion trailing. Nothing is padded, though the second sentence could have been sharper by naming the transport tool.

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

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

For a mutation tool with no output schema and a partially documented nested payload, the description covers the most important trap (no file bytes here) but leaves the shape and constraints of the version metadata to the schema, which only partly documents itself.

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 33%: only idempotencyKey is documented in the schema, while the nested version object's seven fields (fileName, issuer, mimeType, validFrom, validUntil, jurisdiction, status) are undocumented anywhere. The description's note that hashes/storage references are handled elsewhere slightly clarifies the intent of the version object, but it adds no meaning to any individual parameter.

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

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

The description has a verb ("Record") and a resource ("unreviewed evidence version"), which distinguishes it from write-heavy siblings like upload_original. However, the phrase "evidence version description" is ambiguous — it is unclear whether an actual version is being recorded or merely a textual description of one, and the tool is never contrasted with the closely related helvabase_create_evidence.

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

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

It states an exclusion clearly: file uploads, hashes and storage references belong to "the dedicated upload transport", so an agent knows not to use this for binary content. It does not, however, name that alternative tool explicitly or state the prerequisites (existing evidenceId) for calling this one.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them: it discloses that existing answers are overwritten, that omitted/empty valueText clears saved text, that the current review state is replaced and evidence review is reset, and that review scope is required. These are exactly the destructive consequences an agent needs before invoking.

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

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

Three dense sentences, front-loaded with the primary actions and consequences. No filler, though the last clause about review scope sits after the negation stack and could be slightly reordered for scannability.

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, idempotent mutation with no output schema, the description covers the essential preconditions (scope), side effects (overwrite, clear, review reset), and boundary (no approve/promote). It does not describe the response, but with no output schema that is a minor gap.

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

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

With 50% schema coverage, the description compensates for the undocumented fields by explaining valueText semantics ('omitted or empty valueText clears the saved text') and review-state behavior. questionId and reviewStatus remain only schema-defined, but the added meaning for the highest-risk parameter is meaningful.

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: 'Save a draft answer or request changes' against 'the answer for this question'. It also draws functional boundaries by negation ('cannot approve an answer or promote it to the answer library'), which separates it from approval/promotion siblings without naming them. Clear, though it never names a specific alternative 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?

Provides a clear when-to-use (save a draft answer, request changes) and a when-not-to-use (cannot approve or promote, implying sibling tools handle that). 'Requesting changes requires review scope' adds a prerequisite. Alternatives are only implied, not named, 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 establish readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds real value beyond them: it discloses which knowledge is filtered out (expired, retired, superseded, contradicted) and describes the lookup as deterministic, which tells the agent results are stable and quality-gated.

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

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

Two compact sentences, front-loaded with the retrieval scope, no filler. Every clause carries either a filter, a cap, or a workflow instruction.

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 gives the result count and the exclusion rules but never characterizes what a 'reusable answer' contains or how it is adapted. For a lookup tool this is adequate but leaves the caller guessing about result shape and the question input.

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

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

Schema coverage is only 33% (only projectId is documented), so the description must compensate. The phrase 'up to 20' loosely maps to the limit maximum and default behavior, but the 'question' parameter's format and semantics are never explained, leaving half the parameter surface undocumented in both places.

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

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

States a specific verb (find) and resource (reusable answers) with precise qualifiers: 'current, explicitly approved and scope-compatible', capped at 20. That distinguishes it from generic library tools, but it does not name or contrast any sibling such as reuse_library_entry or knowledge_assets, so an agent must infer the boundary.

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

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

The trailing clause 'adapt each result to the current requirement before separate review' implies a downstream workflow (this tool only suggests; it does not commit), which is useful context. However there is no explicit when-to-use vs alternatives guidance and no exclusion criteria pointing to a different sibling tool.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuine behavior beyond that: it verifies the existing actor-bound approval and current evidence, and it cannot be used to bypass confirmation. It still does not say what happens if the claim was already applied, which is the main residual 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?

Three sentences, front-loaded with the recovery scenario, with no filler. The middle sentence packs verification behavior and the non-bypass constraint efficiently. Slightly dense phrasing but nothing extraneous.

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 only 40% schema coverage, the description supplies the recovery context, preconditions, the non-bypass constraint and a check-first instruction. What it lacks is the outcome of a successful call (or the error shape if the application already succeeded), which matters for a retry-sensitive 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 coverage is only 40% (projectId and idempotencyKey documented), so the description must carry more weight. It usefully couples parameters by explaining that the prior challenge ID becomes confirmationId and that revision must be the original exact version, but claimVersionId is never explained and 'version' is only loosely tied to the hashed revision.

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-path and resource: recovering a business claim approval whose application was interrupted after a human confirmation succeeded. It also implicitly separates itself from the confirmation sibling by noting it 'cannot turn an unconfirmed challenge into approval.' It stops short of naming the sibling tools (confirm/request_business_claim_approval) explicitly, so it is clear but not fully differentiated by name.

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

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

It states the triggering condition plainly (confirmation succeeded, application interrupted) and gives a positive precondition (existing actor-bound approval plus current evidence). It also advises inspecting the claim first if application may already have succeeded, which routes the agent to a read tool before retrying. No explicit when-not beyond 'unconfirmed challenge', but the context is actionable.

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 flag destructive, idempotent, and non-readonly behavior, and the description adds concrete destructive consequences: replaces all library grants, omitted libraries lose access, and an empty selection removes all access. It also discloses the authenticated-administrator prerequisite and that no email/upload occurs.

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 tight sentences, front-loaded with the action and replacement semantics. No filler; each sentence carries necessary guidance about exactness, freshness, and exclusions.

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, idempotent mutation with four required params, no output schema, and safety annotations, the description covers the critical behavioral consequences, prerequisites, and common mistaken flows. Return values need not be explained because no output schema exists, and the idempotencyKey schema handles replay 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 coverage is 50%; projectId and idempotencyKey are described in the schema, while selectionId and selectionRevision are not. The description partially compensates by requiring the exact reviewed selection and a revision that must be refreshed if the snapshot changes, though it does not explicitly map these constraints to the parameter names or clarify formats.

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 ('Apply') and resource ('dossier library access') with the exact scope of the selection and revision. It distinguishes itself from prepare/inspect/retry siblings by requiring the reviewed administrator choice and declaring replacement semantics.

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

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

Gives clear context for when to apply: after the authenticated administrator has reviewed and chosen an exact selection/revision. It adds exclusions ('Never apply an inferred selection'; 'changed snapshot requires a fresh selection') and clarifies that no email code or upload is involved, but it does not name the alternative sibling tool for preparing or retrying.

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 meaningful context: no new approval is inferred, the operation must reuse the original exact revision, and prior success should be checked before replaying. This is useful behavioral detail beyond the structured hints.

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, front-loaded with purpose before conditions. Dense but every sentence carries a distinct constraint; no filler.

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

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

For an idempotent recovery mutation with no output schema, the description covers preconditions, ordering, and idempotency well. Missing only explicit return/outcome expectations, which is minor given the recovery framing.

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

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

Schema coverage is only 40%, and the description adds meaning for confirmationId (the challenge ID from the confirmation) and revision (the original exact revision). The remaining params (entryId, projectId, idempotencyKey) rely on the schema. Partial compensation for the coverage gap, so a baseline 3.

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

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

States a specific verb and scenario: recovering after a human library confirmation succeeded but its application was interrupted. An agent can tell it apart from confirm_library_promotion (approval) and request_library_promotion (request), since this is the recovery/apply step. It is clear but does not explicitly name those 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?

Gives explicit when-to-use conditions (confirmation succeeded, application interrupted) and prerequisites (existing actor-bound promotion, current evidence). It also warns to inspect the entry first if application may already have succeeded. It stops short of naming an alternative tool for that inspection, so not a full 5.

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

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

Annotations declare non-readonly, idempotent, non-destructive, closed-world, so the safety profile is partly covered. The description adds real behavioral context beyond them: no server LLM is invoked, internal knowledge/opportunity notes/strategy/audit are excluded from buyer-facing output, and existing source/bid/proof/pack/final-review gates still apply.

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

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

Six compact sentences, each carrying a distinct constraint (assembly scope, answerFormat behavior, coverage requirement, exclusion rules, gate persistence, reassembly timing, sibling redirect). Front-loaded with the core action; slightly dense but 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?

No output schema exists, so the description must carry the workflow context, and it does: prerequisites, revision-currency requirement, gate persistence, and what the tool deliberately does not do. Only the revision/idempotency parameter mechanics are left implicit, which is a minor gap for a mutation tool in a chained workflow.

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

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

Schema description coverage is only 40% across 5 parameters, so the description must compensate. It does explain answerFormat semantics ('questions' retains the exact form question above each answer) and implies projectId/expectedRevision usage via 'dossier revision', but idempotencyKey and the expectedRevision/expectedDraftRevision structures are left entirely to 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+resource ('Assemble all mapped buyer-facing text fields into the existing sourced draft workflow') and adds a distinguishing constraint ('without a server LLM'). It is clearly a distinct contribution-assembly step rather than a generic build/export tool, though the jargon ('sourced draft workflow', 'mapped') assumes prior context.

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

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

Gives explicit conditions ('Requires complete section coverage', 'Reassemble after any dossier revision before final review') and an explicit exclusion with a redirect ('does not create or sign original Office/PDF forms; use document-pack tools'). The alternative is named only as a family rather than a specific sibling tool, which keeps it just under 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, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds domain-specific behavioral context: the actual policy chain a dossier must satisfy and the explicit statement that this read cannot mutate policy, which meaningfully informs the agent beyond the structured hints.

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 with the core action front-loaded and no filler. The closing line reaffirms read-only semantics already implied by annotations, which is mildly redundant but very short.

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 inspection tool with full schema coverage and no output schema, the description omits what the inspection returns (policy steps, satisfied vs outstanding requirements, per-step status). That gap is minor given the annotations, but it leaves the agent guessing at the response shape.

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?

Single required projectId at 100% schema description coverage; the schema already explains it is a Helvabase project/mapping ID from list or create dossier and never a local path. The description adds nothing further about the parameter, so the baseline 3 applies.

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

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

Clear verb+resource: 'Inspect this dossier's server-required BID steps' tells an agent it is a read of bid policy for a specific dossier. It does not, however, differentiate itself from close siblings such as helvabase_read_bid_method, helvabase_request_bid_decision, or helvabase_confirm_bid_decision, so the boundary has to be inferred.

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

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

The description implies when the policy matters by naming the gating requirements (qualification, exact human bid decision, current clear control report) before final review or submission. It never states when to call this tool versus reading bid method or requesting/confirming a decision, 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 cover the safety profile (idempotent, not read-only, not destructive), and the description adds real behavioral context beyond them: determinism, binding to the original analysis revision, and the requirement for human review. It still omits what artifact is produced or any permission constraints.

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 tightly written sentences with no filler, and the core action is front-loaded. Every clause contributes, though the second sentence is somewhat dense.

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 adequately establishes intent, determinism, and the human-review guard, but does not describe the resulting artifact or what happens with the idempotency key on retry beyond what the schema states.

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

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

Schema coverage is 67%, with projectId and idempotencyKey already documented in the schema. The description implies the nested pricing object holds "pasted prices and approved claims," giving marginal extra meaning, but adds no detail for the nested fields or clarifications beyond the schema.

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

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

The description states a specific verb ("Prefill") and resource ("a review artifact") plus its inputs (current analysis, pasted prices, approved claims), so the action is unambiguous. It does not, however, name or differentiate itself from the many nearby build/prepare/review 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?

It implies the usage context (a prefill step prior to human review, tied to the original analysis revision), but gives no explicit when-to-use, when-not-to-use, or alternative tool. The agent must infer where this fits in the workflow.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description adds genuinely new behavioral context beyond that: it does not invoke a model and does not approve final delivery, i.e. it is a draft-assembly step with no AI generation or sign-off authority. It stops short of stating what the assembled draft contains or how it relates to downstream review steps.

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 operation front-loaded and the negative scope stated second. No filler, though the second sentence is somewhat terse relative to the complexity of the surrounding workflow.

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

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

No output schema exists, so the description should ideally say what the resulting draft/review artifact is and what the caller does next. It covers the input precondition and the 'no model / no approval' boundary, but leaves the output side and downstream handoff to be inferred from siblings.

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

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

Schema description coverage is 67% (projectId and idempotencyKey documented, title not). The description adds no parameter-level detail, so it neither compensates for the undocumented title field nor adds meaning beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource: 'Assemble a commercial deck review draft from a ready autofill artifact bound to the current analysis.' The source artifact is named, which helps distinguish it from generic produce_document or submit_draft siblings, though no sibling is explicitly named as an 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?

'From a ready autofill artifact bound to the current analysis' implies a precondition (an autofill must already exist and be bound), and 'does not ... approve final delivery' hints at the boundary of its scope. But there is no explicit when-to-use statement, no guidance on required prior steps, and no named alternative among the many deck/document siblings.

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

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

Annotations already declare the safety profile (not read-only, idempotent, non-destructive), so the description's job is to add context. It does: 'Preserves the original analysis revision' and 'never calls a drafting model' are non-obvious traits an agent could not infer from the schema or 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?

Two sentences, no filler, front-loaded with the action and inputs. The behavioral caveat about the drafting model is the only trailing clause and it earns its place.

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

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

For a mutation tool with a nested matrix object and no output schema, the description omits what a successful build returns and how the resulting matrix is subsequently accessed (presumably via read_compliance_matrix). The idempotencyKey schema text covers replay semantics, so the core gaps are output/next-step and matrix sub-field 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 67% (projectId and idempotencyKey documented in-schema). The description adds meaning by mapping 'optional pasted CSV/TSV' to matrixText and 'current dossier analysis' to selectedClaimVersionIds, but says nothing about the nested title or sourceFileName fields. Baseline 3 is appropriate at this coverage level.

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 ('Build a review matrix') plus the two input sources (current dossier analysis, optional pasted CSV/TSV). An agent can distinguish it from the read counterpart helvabase_read_compliance_matrix, but no sibling is named explicitly.

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

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

There is no when-to-use or when-not guidance. 'From the current dossier analysis' weakly implies a prerequisite (an existing analysis), but the description never routes the agent between this, helvabase_read_compliance_matrix, or helvabase_request_matrix_changes, nor states what to do if no analysis exists.

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

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

Annotations already declare the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context beyond that. It does: it discloses what the read returns (current proof, scope, validity, blockers) and that historical versions are immutable, which is meaningful and not restated in the annotations.

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

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

Two short sentences with the core action front-loaded and nothing padded. The second sentence, while terse, is somewhat cryptic rather than wasteful, so it costs only a little.

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, two-parameter tool with full annotation coverage and no output schema, the description usefully enumerates the conceptual return contents. The only shortfall is that it does not compensate for the undocumented claimVersionId 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 coverage is only 50% (claimVersionId has no description at all), and the description supplies no parameter-level meaning for either argument. With the schema carrying half the burden and the prose adding nothing about how to obtain or format claimVersionId, the gap is not compensated.

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) and a precise resource (an exact version of a business claim produced by the controlled claim workflow), which separates it from the generic sibling helvabase_read_business_claim. The follow-up phrase 'Historical versions remain history' is evocative but does not sharpen the purpose 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?

It implies this is the tool for retrieving one specific version rather than the current claim, but it never names an alternative or states an explicit when-not condition. The closing sentence gestures at immutability of past versions without turning that into actionable selection guidance.

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

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

Annotations already declare readOnlyHint/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavior: this read never grants access, never creates a collection, and selection is automatic only with exactly one writable target. That is meaningful context beyond the annotations without 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?

Five short sentences, front-loaded with the verb and resource, and every sentence carries a distinct constraint (scope, authorization, auto-selection, read-only nature, separation from ingestion). No filler, though the closing sentence is somewhat tangential to the call itself.

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

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

With no output schema, the description must convey what comes back, and it does signal a list of writable collections plus the single-collection auto-selection rule. For a one-parameter read tool with full annotation coverage this is close to complete, though it does not describe the shape of each collection entry.

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?

Single projectId parameter with 100% schema description coverage, including pattern, length bounds and a note that it is a project/mapping ID rather than a local path. The schema does the heavy lifting and the description adds nothing further, so the baseline 3 applies.

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

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

States a specific verb and resource with scope: 'List the existing business-library collections this dossier can write to.' This distinguishes it from generic library tools, though it never names a sibling tool (e.g. dossier_library_access, library) to sharpen the boundary, keeping it short of a 5.

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

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

Gives real usage conditions: select a collection authorized by the responsible person, and auto-selection happens only when exactly one is writable. It also excludes adjacent concerns ('Ingestion is separate from reading, analysis and approval'), but names no alternative tool to redirect to, so it falls shy of explicit when/when-not routing.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, and the description adds genuinely useful clarification of what destruction means: it invalidates the code, does not remove contributions, and never revokes or grants an approval. It also adds an ownership constraint ('only your own'). This is real added context beyond the annotations.

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

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

Two tightly packed sentences, front-loaded with the action and scope, and every clause (invalidation, no contribution removal, no approval change) 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 low-complexity mutation tool with rich annotations and no output schema, the behavioral picture is nearly complete. The only gap is that the challengeId parameter is undocumented in both schema and description.

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

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

Schema coverage is 67%: projectId and idempotencyKey are documented in the schema, but challengeId has no description. The description adds no parameter-level meaning (no format, no sourcing, no constraints). With schema doing most of the work, baseline 3 is appropriate.

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

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

States a specific verb (cancel) and resource (your own pending contribution review challenge) with a clear scope restriction ('only your own pending'). This differentiates it from the confirm/resend/request review siblings, though it doesn't name those siblings explicitly.

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

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

'Including after edits' implies the situation in which it is useful, but there is no explicit when-to-use versus alternatives such as helvabase_resend_contribution_review or helvabase_confirm_contribution_review, and no stated prerequisites. Usage is inferable but not spelled out.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the state precondition that cancellation is only valid pre-dispatch, and that dispatched/uncertain imports require reconciliation instead. It omits what happens to already-cancelled or in-flight uploads and any permission requirements.

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

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

Two tight sentences, front-loaded with the action and its precondition, with no filler. The second sentence partially restates the first's constraint, which is the only small redundancy.

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

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

For a destructive, idempotent mutation with no output schema, the precondition and the reconcile-versus-cancel fork are covered, but the description never tells the agent which tool to use for the dispatched case, nor does it say what a successful cancel returns or what happens to the underlying source data. Adequate but with clear routing and outcome gaps.

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

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

Schema description coverage is 67% (projectId and idempotencyKey are documented, importId is not), and the description adds no parameter meaning at all. With one required identifier undocumented in both the schema and the description, and no clarification of where an importId comes from (e.g. source_imports), 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?

Names a specific verb and resource (cancel a source upload) and states the guarding condition, which distinguishes it from the sibling reconcile_source_import that handles the dispatched case. It stops short of naming that sibling, so differentiation is implicit rather than explicit.

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 a clear when-to-use rule ('only if it has not been dispatched to the backend') and a when-not rule ('an uncertain or dispatched import must be reconciled and cannot be released by cancellation'). It does not name the alternative tool (reconcile_source_import) the agent should route to in that case.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false. The description adds non-obvious behavior: adoption freezes prior fields and section targets, locations are zero-based spans of persisted text, checks are bounded (checks_complete does not assess inherited analysis questions or qualification readiness), and no human approval is conferred.

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

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

Front-loads the action and resource, then layers constraints and routing in compact sentences. Dense but every clause carries operational meaning; slightly run-on but not padded.

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

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

For a mutation tool with no output schema, 40% schema coverage and deep nesting, the description covers adoption/idempotency/routing well but says nothing about what is returned or the revision payload's meaning, and several nested fields remain undocumented.

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

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

Schema coverage is only 40% across 5 required, nested parameters. The description usefully explains expectedReportRevision (echo from helvabase_draft_checks, null initially) and the span semantics, but leaves the `revision` object and the fields/key structure to the schema, so it only partly compensates 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 ('persist checks') against a specific resource ('the exact current draft and explicit text spans') and enumerates the three check kinds (support gaps, repeated commercial values, validity dates). It implicitly separates itself from the read-side sibling by pointing to helvabase_draft_checks, though it never says so directly.

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 routing: 'Read the existing report with helvabase_draft_checks; do not rerun this mutation to diagnose a final-review refusal.' It also states the when-not condition for replays after adoption and that a changed draft needs a fresh clear report before final review/export.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds only mild context: the contradictions are 'recorded' (persisted state) and scoped to the 'authorized workspace'. Pagination behavior and result shape remain undisclosed.

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

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

A single front-loaded sentence with no filler; the scope constraint lands immediately.

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

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

With 0% schema coverage, no output schema, and four undocumented parameters, the description is too thin for the agent to call this correctly. It never explains filtering (includeResolved) or paging, which are the only real decisions this tool exposes.

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 carries the full burden and adds nothing: claimId, limit, offset and includeResolved are never mentioned. In particular, the default-false includeResolved filter and the limit/offset pagination bounds are left for the agent to infer from 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?

Specific verb ('Inspect') plus a clear resource ('recorded contradictions for a claim') and scope ('authorized workspace'). It does not distinguish itself from the sibling helvabase_resolve_contradiction, so an agent cannot tell read vs. act apart from the name 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?

No statement of when to use this versus alternatives such as helvabase_resolve_contradiction, nor any prerequisite about how a claim gets contradictions recorded. Usage is only implied by the word 'Inspect'.

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 read-only, non-destructive, idempotent, and closed-world behavior, the description adds useful context by stating the executor preserves the supported original profile, writes a new file, never contacts Helvabase, and requires hash verification before execution. These details go beyond the annotations without 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?

The description is front-loaded with the retrieval purpose and then adds procedural context in compact sentences. It is somewhat cryptic in places, but no sentence appears clearly 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 zero-parameter tool with no output schema, the description identifies what is returned and supplies important operational constraints. It could be more explicit about the returned task format, but it is reasonably complete for invoking the 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?

The tool takes no parameters, so parameter semantics are not applicable. The schema and description are aligned in requiring no inputs, which is the baseline for a zero-parameter tool.

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 retrieval purpose: getting the optional standalone local file executor, its SHA-256, and task format. It is more specific than a terse name but does not explicitly name or distinguish itself from sibling tools such as prepare_client_file or read_client_file_assignment.

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

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

It gives a clear usage context: use it through the customer assistant's file tools after reading the assignment. It also provides sequencing guidance around hash verification and notes that returning bytes and human approval are separate operations, though it does not name alternatives or when not to use it.

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, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds value beyond that: it discloses exactly what is diffed, the 'echo both revisions for subsequent pages' pagination behavior, and the v1/mixed-format handling nuance.

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 core action, then layered with report contents and edge cases; sentences are dense but each carries signal. The v1/mixed-format clause is slightly specialized, but overall there is little 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?

With no output schema, the description does most of the work by naming the reported fields and echo/pagination behavior, and annotations cover the read-only nature. The remaining gap is that the two nested revision parameters are left undescribed, but for a read-only compare tool the definition is largely complete.

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

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

Schema description coverage is only 20% (only projectId is documented) and both nested revision objects have undescribed required fields (outputJobId, payloadHash). The description indirectly implies the two revision inputs ('current draft', 'previous saved revision') and pagination ('subsequent pages'), but gives no syntax or semantics for the revision hash/outputJob objects.

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 (compare) and precise resources (current draft vs. previous saved revision in the same dossier), then enumerates what it reports (added/removed/changed answers, question/constraint, frozen-evidence changes). An agent can tell this diff tool apart from siblings like check_draft or read_draft_review 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?

Provides explicit scope exclusions — 'No decision is transferred; this is not source freshness or approval' — which help route the agent away from adjacent concerns. It does not name specific alternative tools or a positive 'use this when' trigger, so it stops short of full when/when-not/alternatives 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 declare a non-read-only, idempotent, non-destructive mutation, and the description adds substantial context beyond them: the code is one-time, must be taken from the reviewer, and changed context, qualification, other actors, and old codes are all rejected. It also scopes the effect ('preserves gaps and does not approve final contents').

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

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

Three tight sentences, front-loaded with the action and the credential constraint. No wasted text, though the rejection clauses could be grouped more cleanly.

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, nested-schema confirmation mutation with no output schema, the description covers the key call-time facts: the required one-time code, what is rejected, and the limited scope of the action. Remaining gaps (challengeId, permissions, success response) are minor.

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

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

Only 25% schema description coverage, so the description should compensate. It clarifies the 'code' (one-time, reviewer-supplied) and indirectly the decisionRevision target ('exact proposed bid decision'), but says nothing about challengeId or the nested payloadHash/outputJobId fields.

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

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

States a specific verb+resource ('Confirm the exact proposed bid decision') and the required credential ('one-time code supplied by the reviewer'). It is clearly distinct from the request_* siblings, but does not explicitly name which alternative (e.g. helvabase_request_bid_decision) it complements.

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 workflow context (act after a reviewer supplies a one-time code) and gives one hard constraint ('Never retrieve their code'), but offers no explicit when-to-use vs when-not-to-use framing or named alternative tool.

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

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

Annotations already cover read-only, idempotency, and destructive hints, so the description adds domain-specific behavior: proof and current versions are rechecked, and a changed statement or proof invalidates the decision. This is valuable behavioral context beyond the annotations.

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

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

Four tightly written sentences with the action and key constraint front-loaded. Every sentence contributes either scope, behavior, or sibling distinction without 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 core decision and revalidation behavior, and annotations/no output schema reduce the need for return-value detail. However, with low schema coverage on six required parameters, an agent still lacks enough guidance on challengeId, revision, and claimVersionId relationships.

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

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

Only the code parameter gets added semantic meaning — it must come from the reviewer. With six required parameters and only 33% schema description coverage, the description does not clarify claimVersionId, revision, challengeId, or how they relate to the recheck behavior.

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

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

States a specific verb (approve), resource (exact sourced business claim), and scope (only reviewer-supplied code). It explicitly distinguishes itself from library/dossier approval, giving an agent a clear functional target.

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

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

Provides a clear precondition — use only the code explicitly supplied by the reviewer — and an exclusion against library/dossier approval. It does not spell out when to choose this over request_business_claim_approval or apply_business_claim_approval, but the context is otherwise clear.

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

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

Adds real behavioral context beyond annotations: edits invalidate affected approvals and the assembled draft, and the operation is gated on a human-supplied code. Annotations cover the safety profile (idempotent, non-destructive) and the idempotencyKey schema text covers replay semantics, so the remaining gap is only the success/failure outcome behavior, which is minor.

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: purpose and required input first, consequence second, safety guardrail last. Nothing redundant and every sentence carries information the 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 7-param mutation with no output schema and low schema coverage, the description covers the critical code/challenge path and invalidation consequences but leaves several required params and the result behavior unexplained. Adequate but with clear gaps.

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

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

Schema coverage is only 29%; the description meaningfully explains the critical 'code' parameter and its provenance, plus implies the challenge-based flow behind challengeId. But fieldIds, expectedRevision, includeDefinition, and challengeId get no added meaning in either the schema or the description, so it only partially compensates for the low coverage.

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

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

Specific verb (Confirm) plus resource (contribution review) and the key prerequisite (code from the authenticated human reviewer), which clearly separates it from request_/cancel_/resend_contribution_review siblings. It does not name a sibling explicitly, so it stops short of a 5.

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

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

States the condition for use (you must already have the code supplied by the authenticated human reviewer) and adds two explicit exclusions: do not retrieve the human's email and do not invent a code. It implies the request_contribution_review prerequisite but never names that sibling or states the when-not-vs-alternative case, keeping it below 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 annotations, it discloses a security constraint ('never read their mailbox or provide their code') and invalidation semantics ('changes to the report, source context or draft invalidate the request; deterministic blockers remain'). These are meaningful traits not derivable from the idempotent/non-destructive hints, though success/failure behavior is not described.

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

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

Four tight sentences, front-loaded with the core action, followed by security and invalidation rules. No filler, though the phrase 'deterministic blockers remain' is terse and slightly opaque.

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 a nested object, low schema coverage and no output schema, the description covers workflow behavior but leaves challengeId and the nested revision fields semantically under-specified. Adequate but with clear gaps.

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

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

Schema coverage is only 25% (only idempotencyKey is documented). The description adds meaning for 'code' (must be reviewer-supplied, never fabricated) and implies arbitrationRevision is the exact proposed interpretation whose changes invalidate the request, but 'challengeId' is left to the schema's regex alone with no semantic explanation.

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

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

The description uses a specific verb and resource: 'Record the authenticated reviewer's email confirmation for the exact proposed interpretation.' It is clear that this confirms a previously proposed arbitration, but 'control arbitration' and 'exact proposed interpretation' are jargon that a novice agent must infer, and no sibling (e.g. request_control_arbitration) is named for contrast.

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

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

It states the precondition of use ('use only the code the reviewer supplies after inspecting the questions') and a when-not condition ('changes to the report, source context or draft invalidate the request'). It sets clear context without explicitly naming the alternative sibling, which keeps it at a 4 rather than a 5.

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

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

Adds genuine behavioral context beyond the annotations: 'Changes invalidate the receipt' explains side-effect semantics, and 'No inferred approval, signature or buyer submission' restricts how the code may originate. The safety profile (idempotent, non-destructive, non-open-world) is already covered by annotations, so this is useful but not rich disclosure of authorization or return behavior.

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

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

Three terse sentences, purpose front-loaded, and every clause carries information (verb, input source, prohibition, consequence). No padding or redundancy.

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

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

For a required-everything mutation with a nested revision object, 20% schema coverage and no output schema, the description leaves too much unexplained: the identity/versioning semantics of itemId and revision, the role of challengeId, and what the receipt actually is. The agent cannot confidently construct the call from this definition 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 only 20% – just idempotencyKey is documented in the schema itself. The description loosely gestures at 'code' but says nothing about itemId, challengeId, or the nested revision object (outputJobId, payloadHash), all of which are required. 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: 'Record one file review', with the key input named ('the code explicitly provided by the reviewer'). This is meaningfully more specific than siblings like confirm_review or confirm_contribution_review, but it does not explicitly differentiate itself from 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?

Conveys an important usage constraint ('using the code explicitly provided by the reviewer. No inferred approval, signature or buyer submission'), which tells the agent it may not fabricate a code. However, it never says when to call this versus request_document_review or other confirm_* siblings, leaving the routing to inference.

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

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

Annotations already mark this destructive, non-readonly and idempotent, and the description goes well beyond them: it discloses the invalidation triggers, that permissions/code-consumption/audit commit atomically, that revocation cascades to cached receipts and authenticated downloads, and that direct Snipara workspace memberships are untouched. These are exactly the failure modes and side effects an agent needs before invoking a destructive confirm.

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?

Five short sentences with no padding, and the core action is front-loaded. Phrasing like 'Permissions, code consumption and audit commit together' is terse to the point of being slightly cryptic, but nothing is wasted.

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

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

The behavioral picture is unusually complete for a destructive mutation, and no output schema exists so return values need not be described. Still, the definition leaves the proposalId/challengeId semantics and the post-success outcome unexplained for a five-required-parameter tool with only 20% schema documentation, which is a real 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 only 20% (only idempotencyKey is documented), so the description must compensate. It references the human-supplied 'code' and the fact that 'revisions' invalidate, which adds a little meaning, but proposalId and challengeId are explained in neither place, leaving two of five required parameters wholly opaque.

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

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

The description states a specific action (apply a human-confirmed preview using a human-supplied code) and the resource is inferable from the tool name. It does not name or contrast with the neighboring prepare/request/read dossier-access siblings, so an agent must rely on the name to place it in the workflow.

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 implies the tool is invoked after a preview has been human-confirmed and that the caller must use only the supplied code, and it lists the conditions that invalidate the attempt (changed memberships, permissions, revisions, expired codes). However, it never explicitly says when to use this versus prepare_dossier_access, request_dossier_access_confirmation, or read_dossier_access, leaving usage selection largely to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral detail beyond that: stale answer/proof revisions fail, approval requires the reviewer-supplied code, and no approval can be inferred from conversation context. That is meaningful extra context 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?

Three sentences, front-loaded with the core action ('Approve this exact reusable answer'), each adding a constraint rather than padding. Phrasing is slightly cryptic but nothing is wasted.

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

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

For a 6-required-param mutation with no output schema and thin schema coverage, the description covers the consent constraint and revision staleness but omits the challengeId/confirm handshake and where the code originates. An agent still lacks enough to call it correctly in edge cases.

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

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

Schema coverage is only 33%: just projectId and idempotencyKey are documented in the schema. The description partially compensates by pinning 'code' to the reviewer-supplied value and tying 'revision' to staleness of answer/proof revisions, but it says nothing about entryId, challengeId, or the required challenge/confirm flow, leaving three required params 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 the action (approve a reusable answer) and adds the specific condition of an explicit reviewer code, but 'this exact reusable answer' and 'the complete promotion' are both vague about the resource. It never distinguishes itself from close siblings like helvabase_request_library_promotion, helvabase_apply_library_promotion, or helvabase_confirm_* counterparts, so an agent can't route confidently on name 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?

It implies the confirm step happens only when a reviewer supplies a code after reading the promotion, and states 'No approval is inferred from the conversation,' which is a useful exclusion. However, it never names an alternative (request vs apply vs confirm library promotion) or states when to choose this over those siblings, so usage is left to inference.

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

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

Annotations already declare idempotent=true, destructive=false, openWorld=false, so the safety profile is covered. The description adds real context beyond that: it clarifies this is not the buyer-facing sign/submit step and constrains which code may be used. It omits auth requirements and any rate/limit behavior.

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

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

Three tight sentences, front-loaded with the action, then the boundary, then the warning. Every sentence earns its place, though the code-reuse caveat could be grouped with the main instruction for slightly better flow.

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-complexity mutation with 7 required params, nested objects, and no output schema, the description covers purpose and boundaries but leaves the parameter contract and workflow position largely unexplained. Adequate but with clear gaps given the tool's complexity.

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

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

Schema coverage is only 14% across 7 required params, so the description must carry the load, yet it only adds meaning to the 'code' parameter. The complex nested params (documents, selection, planRevision, planConfirmationId, challengeId) receive no semantic explanation anywhere, leaving the multi-step confirmation inputs opaque.

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

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

States a specific verb ('Confirm') and resource ('the exact complete pack') tied to a pack review. It adds a scoping contrast ('does not sign or submit to the buyer') and warns off sibling codes, so an agent can distinguish it from the sign/submit steps, though it never names the sibling confirm tools directly.

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: use the final reviewer's explicitly supplied code, and never reuse a plan-agreement or individual-file code. That implicitly routes the agent away from confirm_plan_agreement and confirm_document_review, but it does not state the prerequisite flow (e.g. that a request_pack_review challenge must precede it).

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 (which already declare a non-read-only, idempotent, non-destructive, closed-world write), it discloses that codes are one-time, bound to the reviewed plan/selection and actor, expire, and reject replays. It also disambiguates the authorization's semantic scope versus content approval or a signature, adding real behavioral context.

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

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

Two sentences, front-loaded with the verb, with zero waste. The closing clause distinguishing production authorization from content approval or signature earns its place by preempting a common misinterpretation.

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 tool is security-sensitive, fully required (5 params), uses nested objects, and has no output schema; the description covers purpose and behavioral constraints well. However, with 20% schema coverage it leaves important per-parameter structure (challengeId, nested revision/selection) undocumented, so the picture is incomplete for correct 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 low (20%), so the description must compensate. It adds meaning for code (one-time, hand-supplied) and ties revision/selection to the reviewed plan, but leaves challengeId's role and the nested revision (outputJobId/payloadHash) and selection (accepted/rejected ids) structures unexplained, so the 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?

The description names a specific verb (confirm) and resource (production agreement / plan) and sharply bounds its meaning with 'production authorization only, never final content approval or a signature.' That negative scoping distinguishes it from siblings like confirm_review or confirm_document_review, though it does not name a sibling explicitly.

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

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

It establishes the precondition clearly: use only a one-time code a person explicitly supplied after reviewing this exact plan and selection, and it enumerates when the call fails (changed plans, other actors, expired codes, replays). No alternative tool is named, so it falls short of the explicit when-not/alternative routing of a 5.

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

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

Annotations only declare the mutation/idempotency profile; the description adds real behavioral substance — old revisions, changed sources, expired codes and replays are rejected, and the scope is explicitly 'email-confirmed authorization, not a legal electronic signature'. It stops short of describing what a successful call returns or what happens to the revision afterward.

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 core action and followed by constraints and scope. Every sentence carries information; the only mild weakness is that the prohibition about reading the mailbox and the rejection list are packed tightly without prioritization.

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-parameter mutation with a nested revision object, no output schema, and annotations already covering the safety profile, the description supplies the critical prerequisites (one-time code provenance, revision match, rejection conditions). The missing pieces — challengeId meaning and post-call outcome — are secondary.

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 25% (only idempotencyKey is documented in the schema). The description adds genuine semantics for 'code' (one-time, reviewer-supplied, never retrieved from the mailbox) and gestures at 'revision' ('this exact revision'), but 'challengeId' — a required parameter — is never explained, leaving a notable 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 (record) and resource (the reviewer's explicit confirmation), plus the mechanism (one-time code supplied by the reviewer). It does not name any of the many confirm_* siblings (confirm_document_review, confirm_pack_review, etc.) to distinguish which 'review' this covers, so an agent must infer the scope from the resource name 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?

Usage is implied rather than stated: the code must come from the reviewer 'after inspecting this exact revision', and an agent is told never to fetch it from the mailbox. There is no explicit statement of when to call this versus initiating a review via request_review or one of the other confirm_* tools, so routing is left to inference.

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

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

Annotations only declare idempotency and non-destructiveness; the description adds substantial non-annotation behavior: overwrite refusal, no false human authorship/approval claims, approved-source-ID requirement for attachments, dependency resolution gating, and immutable history per mutation. These are exactly the mutation semantics an agent needs and cannot get from structured fields.

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

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

Six compact sentences, purpose front-loaded, and the prefill constraint placed early where it matters most. No filler, though the closing line about immutable history is the least load-bearing of the set.

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, four-required-parameter mutation with no output schema, the description covers refusal semantics, evidence constraints, dependency gating and history preservation. It is nearly complete, missing only revision-conflict/error handling and idempotency-key reuse guidance that the schema only partially supplies.

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

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

Schema coverage is 50%, so the description must carry part of the load. It clarifies prefill vs replace semantics, that comments and source markers accompany changes, and that evidence must reference approved source IDs, but it says nothing about idempotencyKey reuse or expectedRevision/payloadHash conflict behavior, leaving those to the schema text.

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 ('Save field contributions') and enumerates what is carried with them (provenance, source markers, comment, revision protection). It is clearly the write-side contribution tool, distinguishable from read/review siblings like read_contribution_history or request_contribution_review, though it never names those siblings explicitly.

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

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

'Use prefill for empty fields; it refuses overwriting existing work' gives concrete when-to-use guidance tied to the intent enum, and 'Resolve changed dependencies before re-review' states a precondition. No explicit alternative-tool routing is offered, so it stops short of a 5.

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

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

Annotations already declare writable (readOnlyHint=false), idempotent and non-destructive, but the description adds real context beyond them: new dossiers inherit a server-required BID policy requiring qualification, human bid decision and draft controls before submission, and that returned IDs must be reused. These are non-obvious workflow consequences an agent needs.

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

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

Two front-loaded sentences: purpose first, then the policy/ID-reuse behavior. Dense but each clause carries information; only the slightly compressed 'returned IDs must be reused' clause forces some inference.

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 creation tool with a multi-step downstream workflow, the description adequately covers the post-creation obligations and points to helvabase_bid_policy. It leaves the name/slug/description parameters unexplained, which is a gap given 25% schema coverage, but the annotations carry the safety/idempotency profile.

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

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

Schema description coverage is only 25%, with name, slug and description entirely undocumented in both schema and description. The description adds no syntax, format or meaning for those parameters, mentioning only that returned IDs must be reused, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('Create a current RFP/client dossier in this workspace') with the scope qualifier 'in this workspace'. An agent can tell it creates a dossier, though it does not explicitly distinguish itself from near siblings like helvabase_define_dossier_workspace or helvabase_prepare_client_file.

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 context that new dossiers receive a server-required BID policy and routes the agent to helvabase_bid_policy for missing steps, which is useful downstream guidance. It does not, however, state when to choose this tool over sibling creation/definition tools, leaving the primary when-to-use decision 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 already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the agent knows this is a non-destructive, idempotent write. The description reinforces the mutation boundary ('does not upload or certify a file'), which is useful. However, it doesn't explain the 'unreviewed version description' status (missing_review) or why certifying is a separate step, which would be valuable context beyond 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?

Three tight sentences, front-loaded with the core purpose, then the negative scope, then the routing hint. No filler or repetition. Each sentence 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?

Given a 2-parameter, nested-object tool with no output schema, the description covers the core purpose and the two main scope boundaries. But it omits what the tool returns (the created record identifier, which is needed to call helvabase_link_evidence), and doesn't clarify the missing_review status semantics. Adequate but with clear gaps for a registration 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?

Schema description coverage is 50%. The critical idempotencyKey parameter is well documented in the schema itself ('never generate a new key to force a replay'), so the description needn't repeat it. But the nested 'evidence' object — which is the core payload — is undocumented in the description, leaving the agent to infer its structure (title, proofType, version, confidentiality, renewalLeadDays) from the schema 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?

The description clearly states the verb and resource: 'Register an evidence record.' It then adds a precise negative boundary — 'Does not upload or certify a file' — distinguishing it from a file-upload tool. Against siblings like helvabase_upload_original and helvabase_add_evidence_version, the boundary is helpful, but the description doesn't explicitly name those alternatives.

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

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

It gives a clear next-step pointer: 'Use helvabase_link_evidence to propose a link from its exact version to a current requirement and supplier citation.' That is strong routing guidance for the downstream operation. It stops short of saying when to prefer helvabase_add_evidence_version over an embedded 'version' object, which is the main ambiguity given the nested version field.

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 non-read-only, idempotent, non-destructive, and closed-world behavior, lowering the bar. The description adds the 100-question cap and clarifies the non-capabilities, but does not describe side effects, persistence, or reuse of the idempotency key beyond what annotations carry.

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

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

Two tight sentences with the core action front-loaded and no filler. The negative-boundary sentence is somewhat terse, but every clause carries routing 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?

For a create tool with a nested object schema and no output schema, the description covers purpose and boundaries but omits prerequisites (e.g., valid projectId source) and what is returned. It is minimally viable rather than complete.

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

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

Schema description coverage is 67%; projectId and idempotencyKey are documented in the schema while the nested questionnaire object is not. The description's 'up to 100 client-supplied questions' loosely maps to the maxItems constraint but adds no field-level meaning, so baseline 3 is appropriate.

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

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

States a specific verb (Create) and resource (up to 100 client-supplied questions for a dossier), and adds negative boundaries that distinguish it from siblings like answer_questionnaire and import-type tools. An agent can identify the tool's scope 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 second sentence provides explicit when-not guidance ('Does not import a workbook, attest signatures, or approve answers'), which routes the agent away from adjacent tools. It stops short of naming the alternatives that would handle those cases or stating a positive 'use this when' condition, so it is not a full 5.

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

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

Annotations already declare this is a non-destructive, idempotent mutation (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds real behavioral context beyond that: preserve originals and reference source IDs, never infer complete extraction or approval, and that a new definition or context requires review. This is genuinely useful disclosure consistent with the annotations.

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

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

The purpose is front-loaded in the first sentence, and subsequent sentences each encode a distinct rule or constraint. It is dense and somewhat stream-of-consciousness, but little is redundant, 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 complex six-parameter mutation with deep nesting and no output schema, many domain rules are covered (IDs, layers, supersession, roles). The critical gap is the trio of required revision parameters and the idempotency semantics, which the description does not explain at all, leaving an agent without guidance on how to construct a valid revision-gated call.

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

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

Schema description coverage is only 33% (projectId and idempotencyKey), with 6 required params and heavy nesting, so the description is expected to compensate. It partially does by mapping semantics onto nested fields (document kind vs role, scoping supersession to clauses/lots, binding buyer text to responseSectionId, internal fields for knowledge/strategy), but the required revision-gating objects (expectedRevision, contextRevision, analysisRevision) go unmentioned.

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: 'Define this specific dossier from the current analysis,' which distinguishes it from read_dossier_workspace and create_dossier. It is clear what is being produced, though it never explicitly names the sibling it is not, so differentiation relies on inference.

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

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

The phrase 'from the current analysis' implies the precondition for use, and the final sentence points at submit_analysis as the next step. However, there is no explicit when-to-use vs create_dossier/read_dossier_workspace guidance and no exclusions, leaving the agent to infer the operating 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds two domain rules (forms filled on copies, unsupported features stay blockers) that read more like workflow policy than described behavior of this read tool, adding only marginal value.

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

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

Three short, front-loaded sentences with no filler; the prescriptive warning is stated first. It is arguably cryptic rather than padded, so length is not the problem.

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

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

With no parameters and no output schema, the description carries the burden of explaining what the agent learns from the call, yet it never states what 'rollout limits' or 'capabilities' data is actually returned. That gap leaves an agent uncertain about the payload.

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

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

The tool takes zero parameters (additionalProperties false), so the baseline of 4 applies; there are no parameter semantics to explain and the description correctly does not invent any.

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 verb 'Read' plus resource 'multi-document rollout limits' is identifiable, but the phrasing is jargon-heavy ('rollout limits', 'file production') and the tool name 'capabilities' is only loosely echoed. It does not name or distinguish itself against close siblings like export_document_pack or produce_document.

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

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

'before promising file production' gives a timing/context cue for when to call it, which is real but implicit guidance. There is no explicit when-not or named alternative tool, so the agent must infer the routing from context alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds modest value by stating it reads "existing rights only" and identifying the audience (workspace administrator), but adds no detail on output shape, pagination, or failure modes.

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

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

Two short sentences, front-loaded with the core action and followed by the exclusion. No filler or redundancy.

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

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

For a single-parameter, read-only tool with full schema coverage and a complete annotation safety profile, the description covers scope and audience adequately. Only minor gaps remain, such as what the returned library/selection data looks like.

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

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

Schema description coverage is 100% and the single projectId parameter is fully documented in the schema itself, including the warning that it is an ID, never a local path. The description contributes nothing about parameters, so the baseline 3 applies.

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

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

States a specific verb and resource: shows available business libraries plus the dossier's current selection. It is clearly distinguishable from write-oriented siblings, but it never names those siblings or otherwise differentiates itself from tools like inspect_dossier_library_access.

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?

"Reads existing rights only; no grant or upload" serves as a partial exclusion, implying when this is the right call versus a mutating tool. However, it offers no positive when-to-use condition and does not point to the natural alternatives (apply/inspect/prepare/retry dossier library access).

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description still adds real context beyond that: staleness/obsolescence semantics and the note that 'No human approval is conferred' clarifies what the returned report does not represent.

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

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

Three short sentences, front-loaded with the read action and its payload, with no filler. The phrasing is fragmentary and the approval caveat lands abruptly, but each sentence carries a distinct piece of information.

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

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

For a single-parameter read tool with no output schema, the description covers the returned artifacts (report, revision, adopted field mappings), the staleness condition, and the absence of approval implications. Nothing essential to calling it correctly appears to be 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?

There is a single parameter with 100% schema description coverage, and the schema already explains projectId and its origin. The description adds no format or constraint detail for the parameter, so baseline 3 applies.

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

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

The description states a specific verb and resource: read the latest stored business check report, plus its revision and adopted field mappings. It is clear what the tool returns, though it never names the sibling (helvabase_check_draft) that would run a fresh check, leaving differentiation implicit.

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

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

The clause 'An obsolete report requires rechecking' implies the when-not condition and points vaguely at a re-check tool, but no alternative is named and no prerequisites or routing rule is spelled out. Usage is inferable rather than explicit.

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

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

Annotations already cover read-only/idempotent/non-destructive, yet the description adds domain behavior: AND-matching ('matching every required expertise'), normalization ('Legal/juridique/recht are the same expertise'), and ambiguity policy ('Empty, unknown or ambiguous requirements remain unassigned'). It also reinforces that suggestions carry no assignment or access consequences.

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, purpose front-loaded, no filler. The 'never assign work or grant access' clause slightly overlaps the readOnly annotation, keeping it just short of a perfect score.

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 suggestion tool with annotations covering safety, no output schema, and one undocumented parameter, the description covers purpose, matching behavior, and process constraints well. It omits any hint of what the returned candidates look like, which would help since there is no output schema.

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

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

Schema coverage is 50%: projectId is documented in the schema while requiredExpertise is a bare array of strings. The description compensates by defining matching semantics for requiredExpertise (all must match, synonym normalization, ambiguous values dropped), though it adds nothing about projectId beyond 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 ('Suggest') and resource ('current workspace members matching every required expertise'), scoped to an accessible dossier. An agent can tell this apart from mutation siblings like update_member_expertise or workspace_members, though no sibling is named explicitly.

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

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

The closing sentence gives real workflow context: suggestions never assign work or grant access, and a responsible person's decision must be obtained before creating an assignment. This frames how to act on the output, but it never states when this tool should be chosen over 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?

Adds real behavior beyond the annotations: download-time revalidation of 'evidence, revisions, access and expiry', the reproducibility guarantee of 'exact approved versions', and the downstream boundary that no buyer submission is triggered. Annotations already declare non-readonly/idempotent/no-destruct, so this context is a genuine supplement.

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

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

Four short, front-loaded sentences with no filler; purpose comes first, then prerequisites, then behavior. 'Download rechecks evidence, revisions, access and expiry' is slightly telegraphic but 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 six-parameter, nested-object mutation with no output schema and 17% schema coverage, the description covers the preconditions and revalidation flow but leaves the shape and meaning of documents/selection/planRevision largely to the schema. Adequate but with clear gaps for a tool of this complexity.

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

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

Schema coverage is only 17%, so the description must compensate, and it only partially does. It maps loosely to concepts (approved versions -> documents/selection, final pack confirmation -> packConfirmationId, current file reviews -> per-document confirmationId), but the nested revision objects (outputJobId/payloadHash), planRevision, and the accepted/rejected selection arrays remain 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?

Specific verb + resource combination ('Export the exact approved file versions and hash manifest as a ZIP') that an agent can act on. It is distinguishable from pack-adjacent siblings like output_download and export_dossier by the 'exact approved versions + hash manifest' scope, though it never names a sibling explicitly.

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

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

Gives clear preconditions ('Requires current file reviews and final pack confirmation') and an explicit exclusion ('No automatic buyer submission'), which tells the agent this is not a submission step. It stops short of naming alternative export/download tools the agent should consider 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?

Goes well beyond the annotations: annotations only declare this is a non-read-only, non-destructive, idempotent write. The description adds that no review-confirmation email is sent, nothing is approved, review copies are visibly marked unapproved, findings appear as Word comments plus a review appendix, and the submission edition cannot be overridden. All of this is behavior an agent could not infer from the annotations.

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

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

Five dense sentences, purpose front-loaded, with each sentence carrying either edition semantics or behavioral constraints. There is mild redundancy between 'does not send a review-confirmation email or approve anything' and 'Review copies are marked unapproved', but no filler.

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

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

For a mutation tool with a nested input object, no output schema and 50% schema coverage, the description covers editions, permitted draft quality, output artifacts and confirmation requirements well. It does not say what is returned (presumably an output job for helvabase_output_download), which is the remaining gap since 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?

Schema coverage is 50%, and the biggest gap is the 'edition' enum, which has no schema description; the description fully explains what review and submission mean, which is exactly the compensation needed. It also implies that 'revision' pins an exact immutable draft (outputJobId + payloadHash). Remaining minor gap is that the nested revision fields and the output-job return path are not elaborated, but the description carries its share.

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 artifact: build a professional DOCX for the exact immutable draft, and enumerates the two editions (review/submission). An agent can tell it produces a localized DOCX export of a frozen revision. It does not, however, explicitly distinguish itself from close siblings such as helvabase_export_document_pack or helvabase_produce_document, so a 4 rather than a 5.

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

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

Clearly states the conditions that select each edition: review is permissible for working drafts with open questions, unsupported claims or qualification gaps, while submission requires current source validation and reviewer confirmation with no override. That is concrete when-to-use guidance. It stops short of naming alternative tools or explicit when-not-to-use conditions, 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?

Annotations already carry readOnly/idempotent/non-destructive, so the bar is lower; the description adds meaningful context beyond them: the output is a bounded XLSX workbook returned as base64 bytes and it is deliberately not an approval or submission artifact. It does not discuss size limits, auth, or how 'bounded' is enforced.

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 return format and scope. The final 'use the client tools available to you' sentence is somewhat vague but does convey the expected next step, so little is wasted.

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

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

With no output schema, the description correctly supplies the return shape (bounded XLSX base64) and the artifact's non-normative status. Enough for an agent to call it correctly; only the absence of any size/limit detail 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?

Only one parameter, and the schema already documents it at 100% coverage (project/mapping ID, not a local path, with pattern and length bounds). The description adds nothing parameter-specific, so the baseline 3 applies.

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

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

States a specific verb+resource: return the traceability matrix as a bounded XLSX review workbook, with the payload form (base64 bytes) and included content (source extraction issues) named. It doesn't explicitly contrast with the sibling read_requirement_coverage, so an agent must infer the read-vs-export split.

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 scopes the artifact ('review, never an approval or submission export') and tells the agent to save/open it via client tools, which implies downstream usage. It never says when to prefer this over read_requirement_coverage or the other export_* siblings, leaving tool choice to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the preference is optional and defaults off, and the response includes a complete processing disclosure that must be surfaced to 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 sentences, front-loaded with the read action and scope, followed by the default state and the usage caveat. No filler or restatement.

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

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

For a zero-param, read-only tool with full annotation coverage, the description covers everything an agent needs: what is read, its default state, and the obligation to present the disclosure to the user rather than assume consent.

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

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

The tool takes zero parameters, and schema coverage is 100%, so there is nothing for the description to clarify. Baseline 4 applies for a parameterless tool.

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 (Read) and resource (this workspace's external AI review preference and processing disclosure), scoped to the workspace. The read verb separates it from the sibling helvabase_set_external_review_settings, though the description never names that alternative explicitly.

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

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

Gives clear workflow context: present the disclosure before proposing activation, and do not infer agreement from the user's LLM client choice. This tells the agent how to act on the result, but does not spell out alternatives or the precise moment to call it versus set_external_review_settings.

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, idempotentHint=true, and destructiveHint=false, so 'this never writes access' largely restates structured data. The one genuinely additive trait is 'Unknown remains unresolved,' which tells the agent an unresolved state will not be mutated or resolved by inspection. It does not, however, explain what the receipt contains or what errors surface.

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

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

Two short sentences with the core action front-loaded and no filler. The second sentence is slightly cryptic ('Unknown remains unresolved'), but nothing is wasted.

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

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

For a three-required-param, no-output-schema read tool, the description covers the action and one behavioral quirk but omits what a receipt actually returns and how unresolved selections present themselves. Adequate but with clear gaps the agent must discover empirically.

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

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

Schema description coverage is only 33%: projectId is documented, but selectionId and selectionRevision have no descriptions anywhere. The description's phrase 'stored library selection' loosely implies selectionId but says nothing about the 64-hex selectionRevision hash, so it does not compensate for the coverage gap.

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

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

The description names a specific verb (inspect) and resource (the stored library selection's original access receipt), which clearly separates it from write-oriented siblings like apply_dossier_library_access and prepare_dossier_library_access. It stops short of explicitly contrasting itself with the other access-related siblings (read_dossier_access, retry_dossier_library_access), so it is clear but not fully sibling-differentiated.

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 reach for this tool rather than apply/prepare/retry/read_dossier_access, and no prerequisites or exclusions. 'Unknown remains unresolved' hints at semantics but is not usage guidance, leaving the agent to infer the selection condition.

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, idempotentHint=true, destructiveHint=false, and closed-world scope, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it requires exact preservation of returned locations and expectedText, and forbids inventing replacement forms for unsupported or ambiguous features. It does not mention auth or rate limits, but adds useful output-handling discipline.

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

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

Three short sentences, front-loaded with the core action. Every sentence carries a rule, though the phrase about unsupported features is slightly terse. No filler or repetition.

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

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

No output schema exists, so the description carries more return-value burden. It partially addresses this by naming returned locations and expectedText, but does not fully explain their structure or how they relate to editing. Combined with the undocumented fileId parameter, this is minimally adequate but leaves clear gaps.

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

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

Schema description coverage is 50%: projectId is described, but fileId has no description, only a pattern and length constraints. The description adds no parameter meaning for either field, so it fails to compensate for the undocumented fileId.

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 (inspect), resource (stored original), and scope (supported editable targets). It is clear what the tool does, but it does not differentiate itself from sibling read tools like read_original_page or read_source_original, so it falls short of a 5.

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

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

No guidance is given on when to use this tool versus alternatives, nor are any sibling tools named. The constraints about preserving locations and resolving unsupported features are behavioral rules, not usage conditions for selecting this tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds meaningful behavioral context beyond them: 'Failed or interrupted mutations are not automatically replayed,' which tells the agent that job results are durable but retry is not automatic. That is a genuine disclosure not present in the structured fields.

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

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

Two short sentences, no waste, with the core read purpose front-loaded and the durability caveat following. Appropriately sized for a simple read 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?

Annotations cover the safety profile and the description covers retry/durability semantics, but it leaves open whether jobId selects a single job or filters a list, and documents neither parameter. For a 2-param read tool this is adequate but has clear gaps.

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

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

Schema description coverage is 0% for two parameters (jobId, limit), so the description must carry the burden. It says nothing about jobId's role (fetch a specific job vs. list) or the limit/pagination default. The agent gets no semantic help from the description for either parameter.

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

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

States a specific verb (Read) and resource (durable processing/result jobs) scoped to the authorized workspace. It does not differentiate itself from any sibling, but none of the sibling names clearly overlap with 'jobs', so the purpose is identifiable.

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 guidance on when to use this tool versus alternatives, and no explanation of when to pass jobId versus just listing. The workspace scoping is the only contextual cue; usage must be inferred entirely.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The domain note 'A group is not an approved claim' is a real value-add beyond annotations, but the instruction to 'omit knowledgeAssetId to create a group' introduces write-flavored behavior on a tool annotated as read-only and refers to a parameter absent from the schema, creating confusion rather than clarity.

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

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

Three short sentences, front-loaded with the listing purpose, which is reasonable structure. However, the final clause does not earn its place because it is misleading about the tool's read-only nature and about the available parameters.

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

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

For a list tool with no output schema, the description should convey what the returned groups look like (IDs, names) and how pagination behaves; it conveys neither. The presence of annotations lightens the safety burden but not the result-shape burden, and the misleading create clause leaves the agent with an incomplete and partially incorrect picture.

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

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

Schema coverage is only 33% (only projectId is documented), so the description is expected to compensate and does not. limit and offset are self-evident from their bounds/defaults, and the description instead references a nonexistent knowledgeAssetId, adding no meaning to any real parameter.

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

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

The opening clause gives a verb plus a domain resource: 'List existing groups of governed company information.' But the resource term is abstract and the second half muddies what the tool actually is, describing a creation flow rather than listing. No sibling tool is named to disambiguate it from the ~130 other helvabase tools.

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?

'Use its ID for a proposal' implies a downstream workflow, which is genuinely useful orientation, but no alternative tool is named and no when-not condition is given. It also references a 'knowledgeAssetId' parameter that does not exist in this schema, so the guidance cannot be acted on as written.

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

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

Annotations already declare this a safe, idempotent, read-only operation, so the bar is lower, and the description still adds real behavior: validity, owner, scope and contradictions are checked live at query time. It also discloses that includeHistory surfaces non-eligible entries only with explicit blockers and never as approved truth, which is a meaningful semantic distinction an agent would not get from the annotations.

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

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

Four tight sentences, each carrying distinct information: what it finds, live validation behavior, includeHistory semantics, and the reuse caveat. It is front-loaded with the core purpose and has no filler, though the final caveat is advisory rather than actionable for the invocation itself.

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

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

With no output schema, the description should do more to convey what the results look like and how approval status is represented. It covers the query semantics and the history flag but leaves the other three parameters and the return shape unexplained, which is a real gap for a five-parameter discovery tool.

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

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

Schema coverage is 20% – only projectId is documented, and entryId, question and limit carry no meaning in either the schema or the description. The description does add genuine semantics for includeHistory (exposes non-eligible history with blockers, not approved truth), which partially compensates, but four of five parameters remain opaque.

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

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

The description names a specific verb and resource: 'Find current approved reusable answers for this dossier.' That is enough to separate it from write-side siblings like helvabase_propose_library_entry or helvabase_retire_library_entry, though it never explicitly names helvabase_library_source or helvabase_reuse_library_entry as alternatives. Purpose is clear but differentiation from siblings is left to inference.

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

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

The description implies when the tool is appropriate (retrieving approved reusable answers for a dossier) and gives a conditional hint for includeHistory, plus a caveat that reuse requires adaptation and fresh review. It does not state when NOT to use it or point to sibling tools for adjacent needs such as sourcing, proposing, or retiring library entries. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful domain behavior: reading the exact answer and revision is required before reuse, and dossier approval has no bearing on reusable knowledge.

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 tightly written sentences with no waste. The prerequisite and the approval caveat are both front-loaded and easy to act on.

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

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

For a read-only lookup with rich annotations and no output schema, the description gives enough purpose, usage context, and approval caveat to invoke correctly. It omits answerId semantics and return behavior, but those gaps are relatively minor 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?

The schema describes projectId well but leaves answerId undocumented. The description partially compensates by implying that answerId refers to a questionnaire answer with a revision, but it does not explain answerId format, its relationship to projectId, or how revision is handled.

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 ('Read') and resources ('exact questionnaire answer and its revision'), and frames the purpose around reuse or suggestion adaptation. It does not name sibling alternatives explicitly, so it is clear but not maximally differentiated.

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 says when to use the tool: before proposing reusable knowledge or adapting a suggestion. It also adds a scope caveat that dossier approval never approves reusable knowledge, but it does not name alternative tools or state when not to use this one.

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

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

Annotations already declare this is a non-destructive idempotent mutation, so the bar is lower, yet the description adds real behavioral context the annotations cannot: the result is a candidate relation, it does not perform upload/approval/proof-promotion, and the link becomes stale if context, analysis, or evidence changes. The staleness/coupling disclosure is the standout value; return shape is left unspecified.

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 terse sentences, each earning its place: action, precondition, scope boundary, and staleness caveat. The core action is front-loaded and there is no padding or redundancy.

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

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

For a 7-required-param mutation with a nested object, low schema coverage, and no output schema, the description covers action, prerequisite, boundaries, and staleness well. It could say more about what constitutes a successful link or how staleness is resolved, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is only 29% (only projectId and idempotencyKey are documented), so the description must carry the rest. It does map 'evidence version', 'current requirement', 'frozen supplier citation', and 'current analysis' onto evidenceVersionId, requirementId, citationMarker, and analysisRevision, but gives no format or validation detail (e.g., the S-number citation form or the nested analysisRevision fields), leaving a meaningful gap.

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

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

The description names a specific verb ('Link') plus the exact resources: an existing evidence version, a current requirement, and a frozen supplier citation. The action it performs (creating a candidate relation) is distinct from the read counterpart read_evidence_links and from add_evidence_version, so an agent can place it without opening the schema.

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

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

It states a clear precondition ('Read the evidence version and current analysis first') and explicit non-goals ('does not upload, approve or turn a buyer source into supplier proof'). It stops short of naming alternative tools (e.g., read_evidence_links or add_evidence_version) for adjacent cases, so it is clear context rather than 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine extra context: that the returned revisions are immutable (safe to reuse/cache) and that mutations invalidate existing file and pack approvals, which is meaningful behavioral context beyond the structured fields.

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

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

Two tight sentences, front-loaded with the primary action and followed by the usage/impact note. Every clause carries information, though the second sentence is dense and slightly jargony.

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 annotations covering safety and no output schema, the core purpose is conveyed, but the description leaves the required nested planRevision parameter completely undefined and does not characterize the returned revision entries, leaving an agent with gaps to fill.

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

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

Schema description coverage is 0% and the single required nested parameter (planRevision with outputJobId and payloadHash) is never mentioned or explained in the description. For a nested required object, the description should clarify what planRevision identifies, but it provides no parameter meaning at all.

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

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

The description states a clear verb and resource: 'List ... revisions' (the tool's document versions), with scope narrowed to 'current per-item immutable revisions'. It is understandable on its own, but it does not differentiate this tool from nearby read/list siblings such as read_document_plan or read_produced_document.

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 implies downstream usage ('Reuse them as expectedVersion') and warns that changing a file or draft invalidates prior file and pack approvals, which hints at when the versions matter. However, it gives no explicit when-to-call vs. alternatives guidance or prerequisites for invoking the tool itself.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it limits results to active, user-accessible dossiers, explains that data.count equals the returned dossiers, and clarifies that partnerWorkspace is a shared workspace rather than a parent project.

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 three sentences, front-loaded with the core list operation and followed by output-count and domain-model clarifications. Every sentence adds distinct information without repetition or filler.

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

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

For a zero-parameter, read-only list tool with no output schema, the description supplies the key scope, output-count semantics, and a domain caveat about partnerWorkspace. Annotations cover the safety profile, and the remaining gaps such as pagination or ordering are minor for this tool's complexity.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain. The baseline score of 4 applies because the description cannot add parameter detail beyond an empty 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 gives a specific verb and resource: 'List active dossiers accessible to the current user in the authorized workspace.' It distinguishes this list operation from sibling dossier-mutating tools like create_dossier and export_dossier by scope, though it does not explicitly name an alternative 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?

Usage is implied by 'List active dossiers accessible to the current user in the authorized workspace,' which tells an agent when the tool is applicable. However, it offers no explicit when-not-to-use guidance or named alternatives such as the various dossier read or access 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, covering the safety profile. The description adds useful scoping context by clarifying that transfer and approval are out of scope. It does not, however, describe pagination behavior or what "current versions" resolves to, so the added value is modest.

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, no filler, with the primary purpose front-loaded ahead of the scoping note. Every sentence 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, read-only list tool whose annotations already convey safety, the description is minimally adequate. The gaps are pagination behavior and the meaning of "current versions," neither of which is covered elsewhere since there is no output schema.

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

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

Schema description coverage is 0% and both parameters (limit, offset) are undocumented in the schema, so the description carries the burden of explaining them. It says nothing about pagination, defaults, or max values, leaving the agent to infer semantics from parameter 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?

Specific verb (List) plus resource (evidence records and current versions), so the agent knows exactly what it retrieves. It does not distinguish itself from close siblings like list_document_versions or read_evidence_review, but the core purpose is unambiguous.

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

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

"File transfer and evidence approval are separate operations" scopes the tool by excluding adjacent concerns, which implies the agent should look elsewhere for uploads and approvals. However, it never names the alternative tools (e.g., create_evidence, add_evidence_version) or states the condition that selects this one, leaving usage context inferred.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral context beyond them: this is a composite, multi-source inspection (evidence + questionnaire + team work) and that its readiness signal is explicitly NOT final document approval, which prevents misuse.

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 scope of inspection front-loaded and the disambiguating caveat last. Every clause carries information.

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

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

With no output schema, the description does describe what is returned at a high level (readiness, gaps, work) and clarifies the limits of the readiness signal. A single read-only parameter keeps the surface simple, so near-complete coverage is achievable in two sentences.

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

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

Schema description coverage is 100% — the sole projectId parameter is fully documented in the schema, including the 'never a local path' warning. The description adds nothing further about parameters, so the baseline 3 applies.

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

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

The description names a specific verb ('Inspect') and enumerates the three things inspected: evidence readiness, questionnaire gaps, and team work for the dossier. It is concrete enough to separate from generic readers, though it never names a sibling tool it overlaps with (e.g. read_evidence_review, next_actions, read_requirement_coverage).

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

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

Usage is implied rather than stated: an agent can infer this is a pre-submission readiness check, and the caveat 'Readiness is not final document approval' scopes expectations. However, there is no explicit when-to-use, when-not, or named alternative among the many read_* siblings.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds return semantics ("returns who should act and an exact work-item revision") and the bounded-work-queue nature. It omits pagination/ordering behavior, 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?

Three sentences, front-loaded with the core action and closed with the scoping negation; very little waste. The first sentence is slightly garbled ('blockers before open deadlines') but structurally efficient.

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

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

For a read-only, annotation-covered tool with no output schema, the description gives an adequate sketch of results (who should act, work-item revision). However it leaves pagination for limit/offset unexplained and never clarifies ordering or freshness, so it is adequate rather than complete.

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

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

Schema description coverage is 33% — only projectId is documented (and well: 'project/mapping ID ... never a local path'). The description says nothing about the limit/offset pagination parameters, so it does not compensate for the coverage gap even though their intent is largely inferable from defaults and min/max bounds.

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 action and resource: reading "current dossier blockers before open deadlines and assigned work," i.e. a computed work queue. It also distinguishes itself from approval/notification siblings via the "not an approval, notification scheduler" clause, though it does not explicitly contrast with the closest sibling helvabase_work_items.

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 frames when to reach for it (finding current blockers/deadlines/assigned work) and supplies explicit exclusions — it is not for approvals, notification scheduling, or RFP-coverage assertions. It stops short of naming the alternative tool to use for those cases, so it is strong but not fully 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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description goes beyond them by defining what each status value means and explicitly warning that 'uncertain' requires operational review and must not be retried with a new key — actionable behavior an agent cannot infer from 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?

Purpose is front-loaded in the first clause, followed by the status definitions. Two sentences carry real information with little waste, though the semicolon chain of status definitions is dense.

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 explains the status vocabulary, which is the main semantic payload. However it says nothing about the shape of the returned history or the limit parameter, leaving gaps for a read tool with undocumented output.

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 parameter (limit, default 25, max 50) has 0% schema description coverage and is completely unmentioned in the description. No pagination or result-size context is added, so the description does not compensate for the coverage gap.

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

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

States a specific verb and resource: reads 'your own recent notification status'. The 'your own' scoping distinguishes it from the sibling settings tools (helvabase_notification_settings, set_notification_preferences, set_notification_rules), though it does not name an alternative directly. Clear enough to select 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?

No statement of when to use this tool versus the notification settings/rules siblings. The only guidance is a value-level constraint ('uncertain ... must not be retried with a new key'), which is a behavioral rule, not tool-selection guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds behavioral context beyond that: reminders operate without an open LLM session and never approve a dossier or send a bid, clarifying expected side effects.

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

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

The core read intent is front-loaded in the first clause, but the trailing two sentences about reminder behavior read as tangential editorializing about the notification engine rather than about this read operation, diluting focus.

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

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

With no parameters, no output schema, and full annotation coverage, the description only needs to convey what the read returns, which the first sentence does. It could better enumerate the returned fields but is otherwise sufficient for a simple diagnostic 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?

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. The baseline for a no-parameter tool applies.

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

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

States a clear verb ('Read') and enumerates the resource contents: reminder preferences, workspace rules, and engine activation. This lets an agent distinguish it from the sibling write tools helvabase_set_notification_preferences and helvabase_set_notification_rules, though it does not name them explicitly.

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

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

Usage is only implied by the 'Read' verb against sibling setters; the description never states when to call this versus helvabase_set_notification_rules or helvabase_notification_history, nor any prerequisites. Adequate but requires inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and closed-world scope, so safety is covered. The description adds a genuinely useful caveat that returned matches may include legacy test data and unverified imports, but says nothing about ordering, pagination behavior, or result volume.

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

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

Two short sentences, front-loaded with the core action. The second sentence is terse and slightly ambiguous ('not verified live opportunities'), but there is no filler.

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

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

For a read-only listing tool with no output schema and one defaulted parameter, the description covers the essential safety caveat but omits how many records come back and in what order, and never references the limit parameter — enough to call it, but not complete.

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

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

The single 'limit' parameter has 0% schema description coverage and the description never mentions it. The schema's default of 25 and min/max bounds carry the meaning, so the description contributes nothing to parameter understanding.

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

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

States a concrete verb and resource: 'Read stored opportunity matches.' The word 'stored' implies these are previously persisted matches rather than a live search, which faintly separates it from helvabase_search_opportunities, but no sibling is named explicitly.

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

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

There is no guidance on when to call this versus helvabase_search_opportunities or helvabase_opportunity_profiles. The second sentence is a data-quality caveat, not a usage condition, so the agent gets no when/when-not signal.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description usefully adds that the derived proposal is unsaved, deterministic, and involves no model call or persistence — meaningful behavioral context beyond the annotations.

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

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

Two compact sentences, front-loaded with the primary read action and the optional mode, with the no-side-effect clause appended. No wasted text.

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

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

For a two-parameter read tool with annotations covering safety, the description conveys the main mode and the optional preview. With no output schema, it should say a bit more about what is returned (profile fields, pagination/bounded results) to be 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%, so the description must compensate. It effectively explains derivePreview (unsaved, deterministic proposal), but gives no meaning for limit (default 20, max 50), leaving one of two parameters undocumented.

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

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

States a specific verb (Read) and resource (saved watch profiles), plus an optional derived proposal mode. It does not name or distinguish itself from the closely related siblings save_opportunity_profile and search_opportunities, so an agent must infer the boundary.

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

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

Usage is only implied: read saved profiles, with an optional preview. There is no explicit when-to-use or when-not-to-use guidance, and no pointer to save_opportunity_profile as the write-side counterpart or to search_opportunities as the alternative for searching.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety and side-effect profile is fully covered by structured data. The description adds only mild context: that results are dossier-scoped (implying the required projectId) and include buyer feedback. It says nothing about pagination behavior or result shape, which is acceptable given the annotation coverage but not particularly additive.

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

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

A single front-loaded sentence with no filler, which is appropriate for a simple read tool. It is efficient, though its brevity shades into under-specification rather than disciplined conciseness.

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

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

For a tool with three parameters, no output schema, and low schema-description coverage, an agent gets no indication of what an 'outcome' record contains or how pagination works. The safety profile is covered by annotations, but the read contract itself is left to discovery.

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