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

With no annotations, the description carries the full burden and does so richly: it discloses the operation is mutating, creates no model version, side effects (judgements queued, charged to the caller), and precise error semantics with codes and required follow-up actions. This is far beyond what structured fields provide.

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

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

Front-loads the core action and mutating/side-effect note, then layers workflow and error handling. The prose is dense but each sentence carries operational value; only the multi-paragraph structure adds mild 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 mutating, error-prone operation, the description covers prerequisites, side effects, all relevant error codes, escalation handling, and a return-value hint ('returns the links ... with declared'). Even though an output schema exists, the behavioral completeness is excellent.

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?

At 67% schema coverage, the description adds meaning to proposals_hash ('the set reviewed' obtained from get_behavioural_links), which is the key semantic link. model_id and server_version get no additional text, leaving a small gap for server_version.

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 (declare/accept) and resource (link proposals) and signals batch scope with 'every ... in one act,' which implicitly distinguishes it from the single-item declare_behavioural_link sibling. It does not explicitly name that sibling, so the differentiation is inferred rather than stated.

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

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

Explicitly prescribes the prerequisite workflow (read with get_behavioural_links and pass its proposals_hash), names when it fails (409 review_stale, 422 no_proposals, 403 escalation), and gives concrete routing on failure ('Do not retry: report the escalation_id and poll list_proposals'). Alternatives and conditions are both covered.

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

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

With no annotations the description carries the full burden and does so well: it discloses version bumping, quality_warning flagging, soft-delete gating with restore-vs-refuse outcomes, response envelopes for both create and restore paths, and 503/502 retry semantics. This is far beyond what any structured field provides.

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

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

Purpose is front-loaded and each contractual block earns its place. It is dense and slightly long, and it spends some words describing return envelopes that the output schema already covers, which is minor 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-param mutation on a complex domain it is essentially complete: authoring rules, linking effect, gating outcomes, error handling, and response shape are all present. The remaining overlap with the output schema slightly dilutes rather than harms completeness.

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 86%, so the baseline is 3, but the description adds real meaning: component_ids 'feeds reachability' with a multi-instance session-token example, security_properties are named, and description is noted to drive the factor-reasoning prompt. This is useful semantics beyond the schema's own hints.

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

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

Opens with a specific verb+resource ('Add a new asset to a threat model') and immediately adds a versioning consequence. It distinguishes itself from the sibling edit_asset by contrasting create time versus later override.

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 authoring contract is explicit about what to name the asset and what not to do (mechanisms vs protections, quality_warning consequences), and it names the alternatives for adjacent cases (create_co_disposition for non-applicable assets, edit_asset for overriding factors). It's strong guidance but stops short of a crisp 'use this instead of X when Y' routing statement across the many sibling 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?

No annotations are present, so the description must carry the disclosure load, and it does well: it declares the mutation's side effect (a new model version is created), describes the deterministic composer matching behavior and its downstream effect ('unreachable / reason: assumption_excludes'), and notes class-1 vs class-3 evidence. It omits reversibility (undo_model_change exists), permission/attestation requirements for the caller, and validation 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?

Front-loaded with purpose and return shape, then domain meaning, then the exclusion-predicate mechanic, then the specific use case. Every paragraph adds new information; there is no filler or repetition, even at roughly 230 words for an 11-parameter tool.

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

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

For an 11-parameter mutation with an output schema and no annotations, the description supplies the domain model, the mutation side effect, predicate semantics, and the primary use case. The return-shape sentence is partly redundant with the output schema, and the attestation workflow (submit_attestation, assumption_type differences) is left to sibling schemas, so it is strong but not exhaustive.

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 91%, so the baseline is 3; the description earns above that by explaining the exclusion_* family as a predicate with wildcard defaults ('unspecified fields default to wildcard'), the precedence of exclusion_co_ids, and the mechanic that makes the params meaningful. It adds little on assumption_type and server_version beyond 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 ('Add an assumption') plus the concrete side effect ('Creates a new model version'), and explains what an assumption means in this domain. It does not explicitly distinguish itself from the sibling edit_assumption or convert_assumption_to_controls, but the add-vs-edit split is inferable from names.

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

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

Gives a concrete when-to-use recipe: invoke this when a CO's composer verdict is 'indeterminate' because no structural primitive backs an operator non-applicability claim, then set exclusion_co_ids=<co_id>. Also states precedence ('exclusion_co_ids takes precedence over the match fields'). It stops short of explaining when to use linked_co_ids/attestation versus the exclusion predicate path, or when a user should prefer an alternative tool.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses version creation, auto-restore and similar-rejection outcomes, 503/502 failure modes, quality-warning behavior for capability phrasing, and attestation/escalation semantics for surface_extent and trust_boundary_ids.

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 response is front-loaded with the core action and version-creation effect, and its length is largely justified by the tool's complexity. It is dense and somewhat verbose in the authoring-contract and attestation sections, but the information generally 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 the 8-parameter schema, high schema coverage, and existing output schema, the description is complete enough for correct invocation. It covers creation behavior, parameter semantics, error conditions, override paths, and attestation/escalation behavior without needing to restate return values.

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

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

Schema description coverage is already 88%, but the description adds substantial meaning beyond the schema, especially for capability authoring expectations, the quality_warning consequence, change_reason being required with surface_extent, and the attestation implications of trust_boundary_ids.

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 specific action and resource: 'Add a new attacker to a threat model. Creates a new version.' It also distinguishes the tool from edit_attacker for later overrides and mentions that outcomes mirror add_asset, but it does not explicitly distinguish this from the similar sibling add_proposed_attacker.

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 concrete usage guidance, including that callers supply identity-bearing fields, that the backend reasons the factors, and that overrides happen later via edit_attacker with a change_reason. It also states when surface_extent can be declared versus when narrowing must happen later, though it does not explicitly compare against add_proposed_attacker.

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

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

No annotations are provided, so the description carries the full burden. It discloses important behavioral traits: the tool's relationship to generation (must be called after generate_threat_model), the meaning of empty repo_url, and the permanent external-dependency marker behavior of component_unbound findings. It doesn't explicitly state side effects like whether it overwrites existing components or requires specific permissions, but the disclosed context is substantial.

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 moderately long but every sentence earns its place. It front-loads the core purpose, then provides essential context about components, generation ordering, and the repo_url/trust boundary semantics. The structure is logical, though the final warning about client code could be seen as slightly tangential.

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

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

Given the tool's complexity (6 params, output schema present, many siblings), the description is quite complete. It covers the tool's role, when to use it, key parameter semantics, and common pitfalls. It doesn't describe the return value, but an output schema exists, so that's not required. It could mention prerequisites like needing a valid model_id, but that's likely implied by the schema.

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

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

Schema description coverage is 83%, so the schema already documents most parameters well. The description adds meaning beyond the schema by explaining the semantic distinction between speculative and external components (empty repo_url) and how trust_boundary_ids drive reach decisions. It doesn't add detail for every parameter, but the schema covers them adequately.

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

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

The description clearly states the tool's function: 'Add a component to a threat model.' It goes beyond a simple definition by explaining what components are, how they relate to trust boundaries and repos, and how they drive the reachability composer. This distinguishes it from sibling tools like edit_component and add_trust_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 description provides explicit usage guidance: 'Generation reads no components, so add or edit them after generate_threat_model, not before.' It also explains when a component with empty repo_url is speculative vs external, and explicitly warns against a common mistake ('Binding by "some client code touches it" is wrong'). This is strong, actionable guidance.

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

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

With no annotations, the description carries the full burden and delivers: it declares the operation mutating, discloses a durability trait ('a manually-added test survives regeneration/refresh'), and draws the critical boundary that the recorded status is a claim only and is not run or verified here. That is exactly the kind of non-obvious behavior 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?

Three sentences, each load-bearing: purpose first, then the disambiguation against the two sibling tools, then the verification caveat. No filler and the routing information is front-loaded.

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

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

For a 6-param mutation tool with an output schema already present, nothing an agent needs is missing — required inputs are covered by the schema, and the description supplies the usage, persistence and verification context the schema cannot.

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 83%, so the schema already documents status, functional_objective_ids, component_ids and the rest. The description reinforces the status-is-a-claim semantics and points to get_functional_objectives for ids, but adds little beyond the schema text, so the 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 ('Hand-author a single functional test') plus the mapping side-effect ('map it to one or more objectives') and flags 'Mutating.' An agent can distinguish this from import_functional_tests and generate_functional_objectives without opening any schema.

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

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

Explicitly says generation already specifies the tests, so use this only for an extra test generation did not produce, and names the alternative for bulk-registering existing tests (import_functional_tests). Both the when and the when-not are stated, plus a downstream note about CI verification via submit_assertions.

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

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

With no annotations the description carries the full burden, and it does substantial work: it discloses the operation is a link not a move/copy, that the model stays independently editable and may belong to many tags, and critically that tag-selected frameworks propagate and are removed again when dropped from the tag, while self-selected frameworks persist. Missing only auth/permission or failure-mode information.

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 purpose and mutation flag in the first sentence, then a compact semantics paragraph. Every clause carries information; the framework-inheritance detail could be trimmed slightly but it is substantive rather than 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?

An output schema exists so return values need not be explained. For a three-parameter mutation with no annotations, the description covers the important behavioral question (inheritance/removal semantics) but omits prerequisites and error conditions, leaving a small 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 coverage is 67%; the schema documents group_id and model_id but leaves server_version bare. The description adds useful domain meaning by equating 'tag' with group_id, but never references model_id or server_version syntax, so it only partially 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 and resource ('Add a threat model to a tag') plus a mutation flag. Its sibling remove_model_from_group is the inverse operation, and this description is unambiguous about direction.

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 context is implied rather than stated — nothing tells the agent when to prefer this over remove_model_from_group, list_model_groups, or create_group. The mutation flag gives a weak use signal but there are no explicit when/when-not conditions.

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

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

With no annotations, the description carries the full burden and does: it declares the mutation and model-version creation, the rating side effect ('one call before the write, charged to the caller'), the unrated fallback with rating_source, and permission behavior (403 plus escalation_id, parked for a person). It enumerates the failure taxonomy (409 not_proposed / ambiguous_proposal / closure_not_offered, 422 unknown_class), which is exactly the context an agent 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?

Purpose and mutation flag are correctly front-loaded, but the prose is dense and occasionally unparseable ('no position but the tenant-isolation boundaries a per-tenant holder is placed at'). The closing 'Returns {model_id, ...}' sentence partly duplicates the existing output schema, spending length on data the agent already receives.

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

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

For a mutating, escalation-prone tool this is well covered: proposal selection, zone disambiguation, rating/unrated state, error codes, and escalation polling are all present, and the output schema handles return shape. The gap is minor — server_version is unexplained and the relationship to add_attacker is unstated.

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

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

Schema coverage is 75%, so the schema already defines credential_classes and zone. The description still adds real sourcing semantics — credential_classes 'as get_behavioural_attackers lists it' and zone only needed 'where another proposal holds the same classes' — which tells the agent how to derive values, not just their type. server_version gets no explanation, keeping it short of a 5.

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

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

States a specific verb+resource+scope: 'Add the attacker the attacker closure proposes for a credential set,' plus 'Mutating; creates a model version.' It implicitly separates itself from the sibling add_attacker (proposal-driven) and from dismiss_proposed_attacker, but never names add_attacker as the alternative for manual attackers, leaving one plausible confusion.

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 concrete preconditions (name the proposal as get_behavioural_attackers lists it; a dismissed one may be added; use zone where another proposal holds the same classes) and prescriptive recovery on 403 ('Do not retry: report the escalation_id and poll list_proposals'). Missing an explicit 'use add_attacker instead when...' exclusion, so not a full when-not/alternatives treatment.

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

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

No annotations are provided, so the description carries the burden. It does disclose two non-obvious trait-level facts: the call mutates by creating a new model version, and the return shape. However it says nothing about permission/attestation requirements for the call itself or failure modes; the deeper sealed/attestation semantics live in the schema, not the description.

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 action and versioning side effect. The return-shape sentence is somewhat redundant given an output schema exists, and the RST-style backtick quoting is slightly noisy, but overall tight.

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

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

An output schema exists, so spelling out the return value is unnecessary duplication. For a 6-parameter mutation tool with no annotations, the description is adequate but thin on when-to-use, prerequisites, and the relationship to edit_trust_boundary, leaving gaps an agent must infer.

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 83%, so the schema already documents passes, sealed, crosses, model_id, and description in detail. The description adds no parameter-level meaning beyond the schema, which is acceptable 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+resource ('Add a trust boundary') and adds the important side effect that it creates a new model version. The 'Add' vs sibling 'edit_trust_boundary' distinction is inferable from naming, though the description never names the 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?

There is no statement of when to use this versus edit_trust_boundary, no prerequisites (e.g., does a model/asset need to exist first, does this require a specific role), and no exclusions. Usage is only implied by the parameter set.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it states the tool is mutating, creates a model version, derives privileges by rule, places per-tenant holders at isolation boundaries, and explains refusal codes and escalation behavior. It also describes the returned object and how counts can be read elsewhere.

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 purpose and mutation behavior, then proceeds through rules, refusal cases, and return shape. It is dense but appropriately sized for a complex mutating tool with no annotations, though the amount of error-code detail makes it slightly less concise than ideal.

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

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

Given the complex mutation, refusal paths, escalation workflow, and output schema, the description is complete enough for an agent to invoke the tool correctly and handle common failures. The presence of an output schema reduces the need to explain return values, yet the description still summarizes them usefully.

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 75%, but the description adds important meaning beyond the schema for the key parameter, explaining that `credential_classes` is comma-separated, empty means no credential, and that holdings determine privileges and tenant placement. It does not explain `server_version`, which is the remaining schema gap.

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

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

The description gives a specific verb and resource: it says which credential classes an attacker holds, and explicitly labels the tool as mutating and version-creating. It also distinguishes the operation from related siblings by noting that `edit_attacker` refuses privileges changes and that readings come from `get_behavioural_attackers`.

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 provides clear operational guidance: answer from code or owner evidence, use empty for no credential, and expect specific refusal modes such as 422 `unknown_class`, 409 `closure_not_offered`, and 404 `no_attacker`. It also tells the agent not to retry after a 403 escalation and to poll `list_proposals`, though it stops short of an explicit use-this-instead-of-sibling statement for all cases.

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

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

With no annotations, the description carries the full burden and discharges it: mutation semantics (creates a model version, edits the model at once), the extraction trigger conditions, and a complete error map — 409 questions_open, 409 extraction_running, 409 id_in_use, 409 drift_is_defect, 402 when short of credit, 403 with escalation_id for program answers. dry_run's exact side-effect exemption is also stated.

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?

Every sentence carries information, but the layout is a dense run-on: the extraction error codes are crammed into a parenthetical after 'extract_now=True', and the structured-answer grammar sits in one long block. Front-loading is good (mutation and purpose first) but scannability suffers for a definition this long.

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

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

Output schema exists so return values need no explanation, yet the description still pre-announces 'outcome', 'extracts'/'estimate', 'queued', and 'raised', which is exactly what an agent needs to branch on. Permissions (403/escalation), billing (402), idempotency (dry_run), and the required follow-up call are all covered.

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

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

Schema coverage is 80% (baseline 3), but the description adds semantics the schema lacks: the closed set of dispositions (not_needed, not_behaviour, unknown, as_stated), the meaning of text-as-note when a disposition is used, the accepted structured shapes per question kind, and the contradicts.direction vocabulary. This materially reduces misfill risk on the hardest 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 and resource ('Answer open behavioural questions') and adds the key distinguishing scope 'many in one call', plus the mutation disclosure 'Mutating; creates a model version'. It never explicitly contrasts itself with the closely related extract_behavioural_model or get_behavioural_model siblings, so the differentiation is implied rather than spelled out.

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 operating rules: answer only from code/owner evidence, say 'unknown' rather than guess, 'Dry-run, answer what is raised, then submit once', 'Do not retry; poll list_proposals', and 'follow it with get_behavioural_model(view="status", wait_seconds=50)'. It names the alternative tools for the escalation and status paths and gives trigger conditions for each.

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

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

No annotations are provided, so the description carries the full burden and does: it declares mutability, that no model version is created, that the answer is persisted and shown to every later check, that only this entity's check is queued, and the exact refusal codes (409 stale, 409 not_flagged, 404) with recovery guidance. It even covers the lost-response retry case.

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 one-line purpose and the mutation caveat, then organized in layers (where flags come from, how to answer, what the answer does, refusals, return shape). It is dense rather than bloated, though the middle paragraph is long enough that a reader must work to find the 'never guess' rule.

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

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

For a 5-required-param mutation with no annotations, this covers everything an agent needs: provenance of the inputs, the staleness contract, side effects, retry semantics, and failure modes. An output schema exists, so the return description is a bonus rather than a 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 already 80%, so the baseline is 3; the description adds real meaning on top by framing ``input_hash`` as the verdict's hash 'as it was read' (a concurrency guard that explains the 409 stale refusal) and by constraining ``text`` to evidence-backed statements with no guessing and no weakening of true claims. It does not explain ``server_version``, hence not a 5.

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

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

Opens with a specific verb+resource ('Answer, with a fact, the flag the quality check raised about an asset or attacker') and immediately names the two nearby siblings it is not: check_entity_quality (which raises flags) and apply_entity_proposals (which applies corrections). An agent can distinguish it from revalidate_entity_quality and apply_entity_proposals without opening any schema.

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

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

Explicitly enumerates when the tool applies — every flag kind (``question``, ``defect``, ``invalid``) and where the quality data is read from (``get_entity``, the build proposal's flagged entities, the review queue). It also states the exclusions and limits (it decides nothing, the verdict stands until the check runs) and the diagnostic paths for failure, which is more than most definitions offer.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so thoroughly. It explains atomic all-or-nothing commit, mapping-only semantics, preservation of status/evidence/assertions, and the orphan guard evaluated on the final state. This is exemplary transparency for a mutation tool.

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

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

The description is detailed but every sentence earns its place. It front-loads the core purpose, then adds necessary transaction and constraint details without repetition or fluff. The structure is well organized for a complex 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?

The description fully addresses the tool's complexity: atomicity, operation types, orphan guard behavior, and mapping-only effects. An output schema exists, so return values are covered elsewhere. The only minor gap is server_version, which is neither described in the schema nor the 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 75%, so most parameter meaning is already provided by the schema. The description adds valuable context about operation behaviors but does not significantly elaborate on individual parameter semantics beyond what the schema already includes. server_version remains undocumented, but the high schema coverage keeps this at baseline.

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

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

The description opens with a specific verb and resource: 'Apply a batch of control operations atomically as ONE transaction.' It clearly distinguishes this batch tool from single-operation siblings like remap_control and delete_control by emphasizing atomic, multi-operation changes.

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 explicitly states when to use it: to reorganize controls in one step, such as deduplication, 'instead of many separate calls.' It does not explicitly name alternative tools or exclude single-operation cases, but the context is clear enough for an agent to choose correctly.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses that applying is normally the owner's judgment, program refusal and escalation behavior, delegation conditions, partial application across entities, stale/conflict handling, and the fact that positions, credentials, and components are never moved. It also explains rating behavior and the pending settlement path.

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

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

The purpose is front-loaded, but the body is dense and jargon-heavy, with long clauses such as the rewording-versus-narrowing policy that take effort to parse. The outcome list is complete but buried in prose rather than structured, so the definition is longer and harder to scan than necessary.

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 complex mutation tool with no annotations and an output schema, the description is complete enough to invoke correctly: it covers refusal, stale, conflict, partial success, and the return keys `{results, version?, conflict?}`. The remaining gap around `server_version` is 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?

Schema coverage is 67%, and the description compensates for the most important parameter by explaining how `proposal_hash` names corrected words, `input_hash` names the verdict, and `drops` lists removed claims. It does not explain `server_version`, and `model_id` is left to the schema, but the core proposal semantics are substantially enriched.

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 states a specific verb and resource: 'Accept the quality check's corrections of assets and attackers, in one new model version.' It distinguishes this action from related tools by naming `answer_entity_question`, `get_entity`, and `settle_entity_rating`. An agent can identify the operation without opening the schema.

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

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

It explicitly routes doubted claims to `answer_entity_question` instead, explains that refused corrections are parked for a person with an `escalation_id` and should not be retried unless delegation exists, and tells the agent to re-read on `stale` and retry on `unavailable`. These are concrete when/when-not rules and 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?

No annotations are provided, so the description carries the full burden, and it does: read-only, no LLM calls, no mutation, and a detailed disclosure of snapshot paging behavior including the 10-minute retention, the 5-newest-per-model eviction, and the exact 410 snapshot_not_found recovery path. This is behavior an agent cannot infer from the schema.

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

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

Front-loaded with purpose and the sibling distinction, then output shape, then paging. The snapshot paragraph is long and uses dense inline code formatting, but every clause (expiry, eviction, error code, recovery instruction) is operationally necessary for correct paging.

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 an output schema present, the description only needs to orient the agent, and it does so fully: read-only guarantees, the shape of the returned counts and metrics, the summary_only shortcut, and the complete stateful paging protocol including failure recovery.

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 86%, so the baseline is 3; the description adds real meaning on top by explaining how limit interacts with snapshot creation, how snapshot is threaded across pages, and what summary_only changes about the response. The status filter's allowed values live only in the schema and are not reinforced, which keeps this just below a 5.

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

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

States a specific verb and resource ('Run the deterministic assurance assessment over a threat model') and immediately characterizes the inputs and outputs (control implementation status → mitigated/at_risk/unassessed counts plus defined/implemented/verified metrics). It also explicitly separates itself from the nearest sibling, check_control_gaps.

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

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

Gives an explicit routing rule: use this for deterministic assessment, use check_control_gaps when the agent wants LLM reasoning about which COs are under-covered. It also names a usage variant (summary_only=True for counts only) so the agent knows when to narrow the call.

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

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

With no annotations, the description carries the burden well: it declares the operation mutating, explains that it replaces scope wholesale, notes both variants are 'mechanical / non-AI-gated' and validate only that components exist, and spells out the empty-string unscoped consequence. It stops short of stating permission requirements or reversibility beyond the mention of version history in the schema.

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

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

The mutation and replace semantics are front-loaded, and the per-variant bullets are well organized. It is on the long side and some of the empty-string/unscoped detail duplicates the schema's component_ids description, but nearly every sentence carries scope semantics an agent would otherwise have to infer.

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-parameter mutation tool with no annotations, this covers the important ground: replacement semantics, validation limits, unscoped behavior, and target_type branching. An output schema exists, so the brief return-value note is optional rather than required. Preconditions (e.g., target must exist on the model) are only implied.

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

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

Schema coverage is 83%, so the schema already documents most parameters. The description adds real value beyond it: target_id examples ('CTRL-03', 'A1'), the meaning of target_type per branch, and the visibility consequences of component scoping. It does not restate component_ids syntax, but it doesn't need to.

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 ('Replace an asset's or a control's component scope') and flags it as mutating up front. The target_type enumeration makes the two operating modes explicit, so an agent can distinguish this from add_component/edit_component without reading 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?

Gives concrete when-to-use conditions per variant: wiring a previously unscoped control, adding a second component to a cross-cutting control, correcting a wrong assignment, and multi-instance assets. It also states the replacement (not additive) semantics, which is the key usage trap.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses that the platform verifies each association before accepting it and returns declined mappings under 'rejected_mappings'. This is useful behavioral context, though it does not cover side effects or idempotency.

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 concise sentences, each earning its place: what it does, when to use it, and what behavior to expect. No redundancy 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 tool with four required parameters and an output schema, the description provides essential operational context, usage timing, and behavior. It does not explain 'server_version', but the output schema and remaining context make the tool sufficiently usable.

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 75%, so the schema already documents most parameters. The description adds some context about the association intent and the rejection behavior, but it does not compensate for the undocumented 'server_version' parameter or add deeper meaning to the parameter values.

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 operation: associating a functional test with one or more functional objectives. It names the related sibling tool suggest_functional_test_mappings, which helps distinguish this tool from other mapping-related 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?

Gives explicit usage timing: 'Use this after suggest_functional_test_mappings, or to hand-map a test to the objectives it covers.' This clearly explains when the tool is appropriate, though it does not enumerate exclusions or 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?

With no annotations, the description carries the full burden and discharges it well: it discloses that the no-selections path is read-only and creates/credits nothing, that the selections path is mutating, that edges start as 'delegated' drafts, that LLM validation runs, that no credit attaches until confirmation, and that the return is {created, failed}. This is unusually rich behavioral disclosure for a mutation tool.

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

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

The dual-mode behavior is front-loaded and clearly partitioned by the 'Without selections' / 'With selections' structure, so every sentence earns its place. It runs a bit long, but the length is driven by necessary mutation and credit semantics rather than 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?

For a 4-parameter tool with a nested-ish selections payload and an output schema, the description covers the read-only vs mutating split, the credit/validation lifecycle, and the confirmation path, and it does not need to restate return values since an output schema exists. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 75% and the schema already labels model_id, foundation_model_id, and selections. The description adds real meaning beyond the schema for 'selections' by giving the exact pair shape ({source_objective_id, provider_control_id}) and describing the typical value (the confirmed subset of candidates). server_version remains unexplained in both places, keeping this short of a 5.

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

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

The description names a specific verb and resource ('delegate this model's objectives to a foundation's controls, in bulk') and immediately distinguishes the tool from siblings like declare_foundation and manage_reliance by framing it as a bulk attachment operation. An agent can tell what it does 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 gives explicit when-to-use guidance for both modes: omit 'selections' to get read-only candidate pairs, pass 'selections' to create delegated edges. It also names the follow-up tool ('manage_reliance(action="confirm")') needed to carry credit, which is exactly the routing an agent needs.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the operation is mutating, runs as a background job, waits for completion, returns results, requires PRO tier, and only maps existing controls. This is strong transparency for a complex asynchronous write operation.

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

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

The description is front-loaded with the core action and constraint, followed by concise behavioral details and then sibling differentiation. Every sentence contributes useful information with minimal jargon 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?

Despite the tool's complexity — async, mutating, tier-gated, with multiple sibling tools — the description covers what it does, how it behaves, its scope limitations, and its relationship to alternatives. The presence of an output schema means return-value detail is not required here. This is a complete and actionable 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 75%, so the schema already documents model_id, control_id, and framework_id. The description adds context about 'existing controls' and 'never adds or excludes entities,' which indirectly clarifies scope, but it does not add meaningful per-parameter semantics beyond the schema, especially for server_version.

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: 'LLM-map a model's existing controls to a framework's requirements.' It clearly distinguishes itself from siblings by naming map_control_to_requirement and auto_remediate_compliance and explaining how auto_map_controls differs from both.

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 usage placement is provided: it 'sits between' the manual single-mapping tool and the full auto-remediation loop. It also states exactly what it does not do — it never adds or excludes entities — so an agent can decide when to prefer it 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?

With no annotations, the description carries the full burden and delivers exceptionally. It discloses the restore-candidate LLM gate shared with add_asset, the side effect of reinstating stable IDs along with CO tombstones and tied controls, fail-closed behavior when the gate is unavailable, per-entry skip reasons, response field distinctions (restored vs newly added), and automatic convergence.

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

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

The description is long but information-dense, with purpose and prerequisite front-loaded before the phase breakdown. The phase-3 paragraph is the most verbose section, yet nearly every clause carries operational significance for a tool with this side-effect complexity. Minor tightening of the restore-candidate explanation would be possible without losing value.

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

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

For a complex mutation tool with zero annotations, the description covers prerequisites, the full operational loop, side effects on soft-deleted entities, failure modes, concurrency behavior, and trigger conditions. The output schema covers return values, so the response-field explanation is bonus. The one real gap is server_version, a required parameter whose meaning appears nowhere in the schema or 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%: model_id and framework_id are documented in the schema, and the description adds contextual meaning by tying framework to the remediation target and noting that model changes justify re-triggering. However, server_version is a required parameter with no schema description and no description-side compensation, leaving its semantics entirely unknown.

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 sentence states a specific verb and scope: "Automatically close compliance gaps for a framework." The three-phase loop then concretely defines what 'close' means (map controls, exclude non-applicable requirements, apply new assets/attackers), which clearly differentiates it from mapping-only siblings like auto_map_controls and check_control_gaps.

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

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

The description gives clear invocation context: it runs automatically when a framework is selected, can be manually re-triggered when the model changes, and requires PRO tier. However, it never explicitly names alternatives or states when not to use this tool (e.g., when only control mapping is needed versus full remediation with asset/attacker creation), leaving some routing inference to the agent.

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

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

With no annotations provided, the description carries the full burden, and it does so well: it explicitly states the tool is read-only, does not mutate the model, runs as a polled background job, and uses LLM reasoning. These are meaningful behavioral traits beyond what the schema alone reveals.

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 compact and front-loaded: the first sentence states the core purpose, the second covers behavior, and the final paragraph distinguishes the tool from its sibling. No sentence 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 description covers purpose, behavior, async execution, and the key alternative, and an output schema exists to cover return values. The main gap is the unexplained server_version parameter, and the description does not mention how to obtain or poll the background job's result.

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

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

Schema coverage is only 50%: model_id has a description but server_version does not. The description adds no parameter-level guidance at all, leaving server_version's meaning and format unexplained. It does not compensate for the low schema 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?

The description uses specific verbs ('Analyze', 'surface') tied to a clear resource: control coverage and control objectives lacking sufficient controls. It also explicitly differentiates itself from assess_model, making its purpose unmistakable.

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 explicit guidance: used to decide what controls to add, while assess_model is used to score the current state. It also contrasts its LLM-based reasoning with assess_model's deterministic computation, so an agent can choose correctly between the two.

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 zero annotations, the description carries the full burden and does so: it discloses that checking may be paid, that confirmed checks queue and run in the background, that it creates no model version, which statuses are free or charged, and the exact failure modes (402 with nothing queued, 400 unknown_entity). This is precisely the cost, async, and side-effect context annotations would normally supply.

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 and the no-confirm-without-consent rule are front-loaded, and every section adds decision-relevant content. It is dense and backtick-heavy, and the closing sentence plus status glossary partially restate return values the output schema already carries, which costs a little economy.

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

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

For a paid, asynchronous, mutating-in-effect tool with no annotations, the description covers cost, consent sequence, async behavior, status semantics, error codes, and next steps. An agent has everything needed to invoke it correctly and safely without opening other resources.

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 75%, and the prose adds real meaning beyond it: empty entity_ids means every entity, confirm_estimate flips from estimate-only to queued billing, and an id naming no entity returns 400. server_version and model_id get no narrative treatment, but they are self-evident from the schema.

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

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

States a specific verb and resource ('ask for the quality check of the assets and attackers you name') plus the exact scope condition ('that have no current verdict', 'every one when you name none'). It also explicitly distinguishes itself from two siblings: 'answer_entity_question' for disputing a verdict and 'revalidate_entity_quality' for re-asking everything regardless of stored state.

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

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

Gives an explicit call protocol: 'Call it first without confirm_estimate, RELAY THE ESTIMATE TO THE PERSON, and confirm only when they agree; never confirm on your own.' It also names when to use the alternative revalidate_entity_quality and steers to get_entity to read results, leaving nothing 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?

With no annotations, the description carries the full burden, and it delivers: grounding constraints, re-validation before persistence, skip-if-already-tagged behavior, force semantics, the summary shape, and a 404 failure condition.

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 compact and front-loaded with the core purpose, and each subsequent clause adds distinct behavioral information without 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?

The description covers return summary, idempotence, and errors, and an output schema exists, so the main gap is the unexplained required 'server_version' parameter. It is otherwise sufficiently complete 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 67% and the missing description is for the required 'server_version' parameter. The description reinforces 'force' and 'model_id' but adds no meaning for 'server_version', so the agent still cannot tell what value to supply.

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 first sentence names a specific verb ('Classify'), a concrete resource (a model's control objectives), and the target catalog, which makes the tool's job unmistakable and distinguishes it from sibling reads like get_cwe_catalog and get_model_cwe_tags.

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

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

The description makes clear this is the tool to use when classifying against the CWE catalog, and the skip/force behavior implies idempotent reclassification. However, it never explicitly states when not to use it or names an alternative for retrieving catalog IDs or existing tags.

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

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

With no annotations, the description carries the full burden. It discloses that the operation is mutating, updates the checklist, and rejects unrecognized step_id values without changing state. This is strong behavioral disclosure, though it stops short of discussing permissions, idempotency on already-completed steps, or side effects beyond the checklist.

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 compact and front-loaded, with the core purpose stated in the first sentence. The subsequent sentences provide actionable usage guidance and an important failure behavior without wasted words.

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

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

The description covers purpose, mutation semantics, call timing, and invalid-input behavior, and an output schema exists to document return values. However, the required server_version parameter is left entirely unexplained, which is a meaningful gap for an agent trying to invoke the tool correctly.

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

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

The schema describes step_id and its allowed values, but server_version has no schema description and the tool description does not explain it either. With only 50% schema coverage, the description should compensate for the undocumented required parameter, but it never mentions server_version 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 clearly states the specific action ('Mark one onboarding setup step as done') and the resource it affects (workspace onboarding checklist). It also explicitly identifies the operation as mutating, which distinguishes it from read-only sibling tools like get_setup_status.

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 explicit when-to-use guidance: call after performing the actual setup action. It also instructs the agent to check get_setup_status first to avoid re-marking completed steps, providing a clear workflow and an alternative tool reference.

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

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

No annotations are provided, so the description carries the full burden and does so: it discloses the 409 refusal codes (review_stale, stale, needs_answers), that an edit voids a confirmation, and that a program's confirmation may be refused with 403 plus an escalation_id and parked for a human, with explicit 'do not retry' guidance.

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 purpose and side effect in the first line, then constraints and failure modes in descending priority. Slightly heavy with inline code markup and some repetition of the ir_hash constraint, but every sentence carries operational 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?

An output schema exists, so return values need not be explained; the description instead covers the mutation, its gating conditions, and the escalation path. For a state-changing tool with no annotations, this is complete enough for an agent to invoke it correctly.

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

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

Schema coverage is 75% (server_version undocumented), and the description adds real meaning for ir_hash by tying it to the value returned by get_behavioural_model. It does not explain server_version or the note field's effect beyond what the schema states.

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 a model's behavioural model as reviewed) and immediately declares the mutating side effect (creates a model version). It distinguishes itself from read siblings by tying confirmation to the reviewed ir_hash that get_behavioural_model returns.

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

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

Gives a clear precondition ('Confirm only the model whose ir_hash was reviewed') and enumerates the refusal conditions that tell the agent when this call will not apply. It does not explicitly contrast with alternatives such as edit_behavioural_element or answer_behavioural_questions, so it falls short of the when-not/alternatives bar.

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

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

With no annotations, the description carries the full burden and delivers extensively: it states nothing is authored here, describes the CO-linkage retirement, the proposal behavior (null when nothing owed), and detailed side effects on assumption_groups, including that empty groups are dropped, status is unchanged, and underlying assumptions are not deleted.

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 and mutability flag before the detail. The body is comparatively long but each sentence conveys a distinct behavioral fact (proposal handling, group side effects, non-deletion), so little is 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 complex mutating tool, it covers the operation, the deferred build workflow, and all linkage side effects thoroughly. An output schema exists, yet the description helpfully explains the key 'proposal' result field, leaving no material gap 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 67%; model_id and assumption_id are documented in the schema while server_version is not. The description adds no parameter-level syntax or format detail, so it does not fully compensate for the coverage gap, though the remaining params are largely self-explanatory.

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 ('Convert a violated or retired assumption to controls') and immediately flags its nature ('Mutating.'). It is clearly distinguishable from sibling tools like add_assumption, edit_assumption, and delete_assertion.

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 when-to-use guidance ('Use when an assumption is no longer valid and the system owner needs to implement controls instead') and directs the agent to the follow-up tool (start_control_build after review). It does not name when-not to use it or a direct alternative, but the context is clear.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It does this thoroughly: the objective remains in the matrix, no controls are generated, no coverage gap is raised, and the claim expires at review_by. This goes far beyond what the schema alone communicates.

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

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

The description is front-loaded with the core claim and then structured into clear behavioral, temporal, and alternative-usage sections. It is longer than strictly necessary, but the length is justified by the nuance of the tool and the need to prevent confusion with create_risk_acceptance.

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 6 required parameters, no annotations, and an existing output schema, the description covers the tool's semantics, side effects, timing constraints, and sibling distinctions thoroughly. An agent has enough information to decide when to call it and what the call will do.

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 high at 83%, so the baseline is already solid. The description adds meaningful semantics beyond the schema, especially for review_by: it is 'not a formality,' the claim stops applying on that date, and the date should be realistic for re-checking. It also reinforces that owner is the accountable party.

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: 'Record that a control objective DOES NOT APPLY to this system.' It also explicitly distinguishes this from create_risk_acceptance by defining the type of claim being made, so an agent can tell the tools apart without needing to compare schemas.

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 explicit routing guidance: use create_risk_acceptance when the objective DOES apply and the risk is carried deliberately, and use neither tool when an objective is merely unaddressed rather than inapplicable. It also explains the operational consequences of using this tool, giving clear context for when it is appropriate.

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

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

No annotations are provided, yet the description carries the full burden well: declares 'Mutating', warns uniqueness is per-workspace with 409 on a clash, and adds an access precondition ('every model named in model_ids must be one the caller can access'). That is rich behavioral detail beyond what the schema encodes.

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 action and the core distinguishing property, then the necessary operational facts (uniqueness, 409, access check). Every sentence earns its place; no 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?

For a 4-param mutating tool with no annotations, the description covers mutation semantics, uniqueness/conflict behavior, and preconditions, and an output schema exists so return values need not be explained. It omits any mention of the server_version parameter or required-permission specifics, leaving a small 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 coverage is 75% and already documents name/model_ids/description. The description reinforces semantics — uniqueness scope for name and the access precondition for model_ids — adding value the schema does not convey, though it says nothing about model_ids being nullable or server_version.

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 (a tag/group) and immediately disambiguates the concept: 'A tag groups models for viewing and reporting without asserting any relationship.' This distinguishes create_group from relationship-asserting siblings like attach_foundation or add_model_to_group.

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?

Clarifies intent — grouping for viewing/reporting, not relationship assertion — which implicitly tells an agent when this is the right tool versus modeling relationships. It does not explicitly name an alternative or when-not-to-use sibling, so it falls 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?

No annotations are supplied, yet the description carries the full burden well: it declares the write nature ('Mutating: persists a proposal record'), states that raising is not deciding and that a person or delegated agent decides, and asserts 'Design changes are never applied automatically'. It also tells the agent how to observe the outcome (poll list_proposals), which is exactly the behavioral context missing 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?

Front-loaded with the imperative and the when-to-use constraint before the longer conceptual explanation of proposal/decision separation. Every sentence contributes, though the second paragraph is somewhat expansive for what it adds beyond the first.

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-parameter mutating tool with an output schema present, the description supplies what the schema cannot: the decision workflow, the non-automatic application guarantee, and the polling path. Return-value explanation is correctly omitted since an 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 description coverage is 83%, so the schema already documents the kind/payload coupling, evidence shape, and rationale. The description body itself adds little param-level detail beyond reinforcing the kind semantics (assumption preconditions, description_revision billing). Baseline 3 is appropriate when the schema does the heavy lifting.

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: 'Raise a proposal to change a model's scope or design', followed by a definition ('A proposal is a change of scope or design'). It explicitly distinguishes itself from direct mutation tools ('do not edit the model directly for those changes') and names the paired siblings decide_proposal and list_proposals.

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

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

Gives an explicit trigger ('when the code or your analysis says the model should gain or lose a component, or that an attacker position or asset should be removed by design'), an explicit exclusion ('do not edit the model directly'), and routes to alternatives for the next steps (decide_proposal to decide, list_proposals to poll). Nothing is left to inference.

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

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

With no annotations provided, the description carries the full burden and discharges it well: it discloses the lifecycle ('reads as active until it expires or is revoked'), the record contents (owner, justification, review deadline), and the triage effect (surfaced as accepted, not unaddressed). This adds real behavioral context beyond the bare mutation implied by 'create'. It stops short of covering permissions or revocation mechanics, which keeps it at a 4.

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 paragraphs, front-loaded with the core purpose in the first sentence. Each subsequent sentence contributes a distinct fact — usage condition, lifecycle, triage effect — rather than restating schema fields. It is longer than a minimal definition but 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 mutation tool with six required parameters and zero annotations, the description covers purpose, when to use it, record contents, lifecycle, and downstream visibility; the output schema relieves it of explaining return values. The remaining gaps — who is authorized to accept and what server_version should contain — are minor against the strong selection and invocation guidance.

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 83%, which is high, so the baseline is 3; the description adds collective framing by naming owner, justification, and review deadline as the components of an acceptance and linking review_by to expiry. It does not add per-parameter detail beyond the schema and leaves server_version unexplained, so it does not fully close that 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 that an operator explicitly ACCEPTS the residual risk on a control objective instead of mitigating it' — and self-identifies as 'the write counterpart to list_risk_acceptances', which separates it from the read sibling. The behavior is unambiguous and goes well beyond a paraphrase of the title.

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

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

Gives an explicit trigger condition ('Use when a control objective's residual risk is a deliberate, documented decision rather than an unaddressed gap') and tells the agent to prefer this over leaving accepted risk implicit, citing auditability and the forced review deadline. It names the read counterpart but does not name an alternative tool for the unaddressed-gap case, so the when-not is implied rather than fully explicit.

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

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

With no annotations provided, the description carries the full behavioral burden and does so: it declares the tool mutating, defines the closing condition (an assertion passing verification at a commit not earlier than the decision), and discloses two distinct failure modes (409 drift_is_defect while the finding stands, 403 escalation without the required policy grant). This is well beyond what the schema conveys.

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

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

The description is dense but front-loaded: purpose first, then the two outcome branches, then closing/refusal mechanics, then the authorization caveat. Every sentence carries information, though the backtick-heavy jargon and nested parentheticals make it denser than ideal.

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

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

An output schema exists, so return values need not be described. For a mutating, policy-gated decision tool with no annotations, the description covers preconditions, the meaning of each branch, the failure codes, and the escalation fallback — nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is already 86%, so the baseline is 3, but the description adds real meaning: it explains the semantics of the two 'intent' values, clarifies that control_id must name the control whose assertions check the behaviour as designed, and implies head_commit is the commit the code was read at. This lifts it above the schema baseline.

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

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

The first sentence names a specific verb (decide) and a specific resource (a description-drift finding), and immediately defines the two possible outcomes ('intended' vs 'defect'). This is a semantically unique action that cannot be confused with siblings like decide_proposal or judge_objective, and it even flags the operation as mutating.

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

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

It explicitly states when each outcome applies and what to supply for each: 'intended' means revise the description via create_proposal, 'defect' means name the control in control_id. It also spells out the refusal path (403 with escalation_id unless the delegation policy names drift_intent_decided), tells the agent not to retry, and offers the fallback of raising a drift_intent proposal for a person.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses that the decision is bound to both entries' texts and is voided by an edit, that 'same' merges nothing, and it enumerates specific failure modes (422 two_elements, 422 same_entity, 404 unknown_entity) plus a 403 escalation path with a 'do not retry, poll list_proposals' instruction. This is exactly the behavioral context an agent needs before invoking a mutation.

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

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

The opening line front-loads the core meaning (verb, resource, and 'mutating; creates no model version; a judgment'), which is strong. The remainder is dense with useful error/auth detail, though the parenthetical aside about 'two elements are two things' and heavy backtick formatting add minor noise.

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

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

An output schema exists, yet the description still summarizes the return shape ({pair, entity_kind, verdict, decided_at, objectives}), and it covers mutation semantics, persistence rules, and error codes. Given the tool's complexity, nothing essential for a correct invocation is missing.

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

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

Schema coverage is high (86%), so the schema documents most parameters and the baseline would be 3. The description nevertheless adds real meaning beyond the enum by explaining the downstream consequence of the 'same' verdict (pair stays shown until remove_entity; nothing merged), which the schema's '``same`` or ``different``' text does not convey.

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

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

States a specific verb (decide) plus the exact resource (two entries of a model's inventory) and the judgment being made (same/different entity). It readily distinguishes itself from siblings like remove_entity and get_inventory_judgements by clarifying that this records a judgment rather than performing a deletion or a read.

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 conveys context—this is a mutating judgment that creates no model version, and it points to remove_entity as the way to actually drop an entry when the verdict is 'same'. It does not, however, explicitly compare against sibling judgment tools (e.g., judge_objective, decide_reconciliation_candidate) or state exclusions beyond the 422 element-of-behavioural-model 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?

No annotations exist, so the description carries the full burden and does so: it declares the operation mutating, describes the 403 refusal with escalation_id, distinguishes the self-decision for accepting an assumption proposal, explains expires_at binding and re-judging, and states the persistence effect of rejection. This is unusually rich behavioral disclosure.

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

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

Three dense paragraphs, front-loaded with purpose and the gating condition, then refusal handling, then per-proposal-type semantics. Long but every sentence carries actionable information; only mild 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?

An output schema exists, so return values need not be explained, and the description still covers the mutation effect, failure mode, and decision-type-specific consequences. Nothing an agent needs to call this complex judgment tool correctly is missing.

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

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

Schema coverage is 86%, so the schema already documents decision (accept/reject), expires_at, record_only, and note. The description reinforces the accept/reject semantics and the assumption-specific effect of expires_at, but adds little for model_id, proposal_id, server_version, or note. 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 (accept/reject) and resource (proposal), and immediately scopes it against siblings by naming get_control_work_order for the delegation policy and list_proposals for outcome polling. An agent can identify the operation and its gate without opening any schema.

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

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

Gives an explicit precondition (delegation policy must name this decision for this agent at the proposal's tier), explicit when-not behavior (refusal returns 403 and parks a decision_request), and explicit alternative actions (do not retry; poll list_proposals). This is a genuine when/when-not/alternative guide.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses version bumping on apply, no new version on reject, idempotency on the pair, org-scoped visibility of rejections, the heuristic-tier refusal gate requiring confirm_heuristic, server re-validation with 400 on stale models, and 503 when composition is unavailable. It even names what record gets dropped when the pair stops matching.

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 mutating and input-tool facts are front-loaded, and the three decisions are cleanly bulleted so an agent can scan to its branch. It is dense and somewhat long, but almost every clause adds operational detail (refusal gate, error codes, return shape) rather than 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 8-parameter mutating tool with no annotations and no schema descriptions, this is close to complete: preconditions, decision semantics, error codes, heuristic confirmation, version effects, and return payloads are all covered. An output schema exists, yet the description still names the key response fields, so an agent knows what it gets back.

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

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

Schema coverage is 0% across 8 parameters, and the description compensates for most of them: kind enumerates assets/attackers/components, own_qid/inherited_qid are documented with concrete example formats ('child:A1'), decision values are explained semantically, and confirm_heuristic and rejection_id are given meaning and provenance. model_id and server_version are required but their roles are only implied by the 400 re-validation note, not stated explicitly.

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

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

Opens with a specific verb+resource ('Decide a reconciliation candidate') and immediately ties it to the sibling that produces its input, list_reconciliation_candidates. The 'Mutating.' flag plus the per-decision breakdown make it unmistakable against read-only siblings like list_reconciliation_candidates.

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?

Each decision value is given a clear condition: 'apply' when the descendant's own entity IS the inherited one, 'reject' for 'these are NOT duplicates' at org scope, 'unreject' to pull a rejection_id from list_reconciliation_candidates(disposition="rejected"). It also flags recovering from a 400 by refreshing the list. It does not compare against adjacent decision tools such as decide_inventory_pair or reconcile_model, 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?

With no annotations, the description carries the full burden and does so well: it discloses that the operation mutates, creates no model version, is checked on every read, re-keys judgements that are queued and charged to the caller, and can be refused with a 403 plus escalation_id under delegation policy. That is unusually rich disclosure of side effects and authorization behavior.

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

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

The purpose is front-loaded, but the body is dense, jargon-heavy and awkwardly line-broken, with at least one convoluted sentence ('one whose asset lacks the property the element carries is kept and asked about'). Information density is high, but readability suffers.

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

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

An output schema exists, so return values needn't be detailed, and the description covers mutation semantics, authorization failure and the escalation route. What is missing is what happens to an existing/conflicting link and any reversal path, which would matter for a declare operation. Mostly complete.

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

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

Schema coverage is 80%, so the schema already documents node_id, model_id, entity_id and component_id. The description adds only marginal meaning beyond that ('the asset or trust boundary it is' partially restates the entity_id field), 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 ('Declare') and resource ('the asset or trust boundary a behavioural element or zone is'), and ties the input to get_behavioural_links. It does not explicitly distinguish itself from accept_behavioural_link_proposals or the other link-related siblings, so an agent must infer the boundary. Clear but not 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?

Gives strong procedural guidance for the failure path (403 refusal, do not retry, report the escalation_id, poll list_proposals) but never states when to prefer this tool over accept_behavioural_link_proposals or get_behavioural_links. Usage is implied rather than framed as a decision.

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

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

With no annotations, the description carries the full burden and does so thoroughly: preview writes nothing, confirm from a program is always refused with 403 plus an escalation_id, the declaration is parked for a person, and it is withdrawn if the underlying delta changes. These are exactly the non-obvious traits an agent needs before calling.

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 two-phase structure is front-loaded and the confirm behavior is easy to find. However, the description is verbose and repeats the 'person's act' point, and it enumerates the preview payload at length even though an output schema exists, so not every sentence is maximally efficient.

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