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 versioning side effect, quality_warning flagging for mechanism-phrased assets, the soft-deleted-asset gating behavior (auto_restored, restored_asset_id, discarded_fields, or a {accepted: false, classification: "similar"} refusal), and 503/502 retry semantics. 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?

The purpose is front-loaded and the contract/error details are organized under clear paragraphs. It is dense and fairly long, with a couple of asides (e.g., the factor-decomposition rationale) that could be trimmed, but nearly every sentence carries actionable information.

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

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

For a 7-parameter mutation tool with an output schema, the description covers the mutation contract, the authoring requirement, edge cases (soft-deleted matches), and error/retry behavior. An output schema exists, so its decision to also sketch return shapes 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 coverage is 86%, so the schema already documents most parameters and the baseline is 3. The description adds meaning beyond the schema by explaining that component_ids 'feeds reachability' for multi-instance assets, and by giving the authoring contract that shapes what 'name' should contain. That is genuine added value, though it doesn't cover every parameter.

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

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

The first sentence gives a specific verb+resource ('Add a new asset to a threat model') and immediately notes the side effect ('Creates a new version'). It also routes the agent to the sibling edit_asset for post-hoc changes, so the tool is distinguishable from its nearest neighbor without opening a schema.

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

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

The description gives clear context on when to use this tool (creating a new asset, and using create_co_disposition / non-applicability assumptions when an asset doesn't apply) and explicitly names edit_asset for overrides. It stops short of an explicit 'use add_asset when X, not when Y' clause, so a 4 rather than a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses the mutation side effect, the attestation/mitigation lifecycle, deterministic class-3 evidence behavior, wildcard defaults, and precedence rules. This is strong behavioral context, though it does not cover operational concerns like permissions or reversibility.

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 side effect, then organizes the advanced exclusion predicate behavior into a focused section. It is fairly long, but the content earns its place given the tool's complexity and 11 parameters.

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

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

For a complex tool with no annotations, an output schema, and high schema coverage, the description covers the essential operational context: side effects, matching behavior, defaults, precedence, and a concrete use case. It does not spell out every assumption lifecycle step, but the schema and output schema cover the structured details.

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 91%, setting a high baseline. The description adds meaningful semantics beyond the schema: it explains that any subset of exclusion_* fields can be passed, unspecified fields default to wildcard, exclusion_co_ids takes precedence, and the predicate feeds deterministic composer evidence. This exceeds the 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: "Add an assumption." and clearly states the side effect "Creates a new model version." This distinguishes add_assumption from related operations like edit_assumption without relying on the title alone.

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

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

The description gives a concrete, decision-relevant scenario: use this to resolve a CO with an "indeterminate" composer verdict by setting exclusion_co_ids. It provides clear context for when the exclusion_* predicate mechanism is appropriate, though it does not explicitly name alternatives or state when not to use the 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 present, the description carries the full transparency burden and does so thoroughly. It discloses that the call creates a new version, that the backend LLM-reasons the factor decomposition, that three outcomes mirror add_asset, that 503/502 errors can occur, and that surface_extent is recorded as an attested operator statement.

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 important constraints front-loaded and clearly separated. It loses a point for some redundancy, such as mentioning the add_asset mirror twice, and for an extended rationale about for-all obligations that could be tighter.

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

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

For a create operation with backend reasoning, side effects, error conditions, and an attestation parameter, the description covers all the non-obvious context an agent needs. It explains versioning, alternative routing, failure modes, the capability contract, and the special surface_extent workflow, while output format is covered by the output schema.

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

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

Schema coverage is high at 88%, but the description still adds significant meaning beyond the schema. It defines the capability authoring contract with a concrete pattern and quality_warning consequence, and it explains surface_extent's create-time restriction and attestation semantics in ways the schema does not.

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

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

Opens with a specific verb and resource: "Add a new attacker to a threat model." It also distinguishes itself from the sibling edit_attacker by noting that post-create factor overrides and surface narrowing happen there, and it names add_asset as its semantic mirror.

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: use this tool to create an attacker, and use edit_attacker afterward to override factors or narrow surface_extent. It also tells the caller that only "whole" is declarable at create time and that narrowing belongs on a later edit, which prevents a common misuse.

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 provided, the description must carry the full burden of behavioral disclosure. It only states 'Creates a new model version,' which is vague and does not explain side effects such as versioning implications, reversibility, permission requirements, or what happens to existing boundaries. The description fails to disclose any meaningful behavioral traits.

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

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

The description is extremely concise, consisting of two short sentences. It is front-loaded with the primary action and avoids redundancy. While it is arguably under-specified, it is efficiently structured with no wasted words.

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

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

For a tool with 6 parameters, an output schema, and a complex domain (trust boundaries in threat models), the description is insufficient. It does not clearly explain the model versioning behavior, any prerequisites, or the effect on the overall model. It also fails to reference the rich parameter semantics that the schema provides, leaving the agent without a clear operational picture.

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

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

The schema provides detailed descriptions for 5 of 6 parameters (83% coverage), so the description is not required to explain parameters. The description adds no additional meaning beyond what the schema already offers, earning the baseline score for high 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 clearly states the verb 'Add' and resource 'trust boundary', making the primary purpose obvious. However, it does not differentiate from the sibling edit_trust_boundary beyond the verb difference, and the added 'Creates a new model version' is ambiguous about whether that is a side effect or a separate action. Purpose is clear but not fully distinct.

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

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

There is no guidance on when to use this tool versus edit_trust_boundary or other model-modifying tools. The description does not mention prerequisites, the distinction between adding vs editing boundaries, or any context that would help an agent decide between 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 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 provided, the description carries full responsibility for behavioral disclosure. It explicitly states the tool is read-only, makes no LLM calls, performs no mutation, and is deterministic. It also describes what the assessment computes and returns, including summary counts and progressive metrics. This goes well beyond the structured schema and gives the agent a confident mental model of the tool's 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 description is well-structured and front-loaded: purpose first, behavioral safety second, output summary third, alternative routing fourth, and a practical usage tip last. Every sentence adds value and there is no redundant text repeating schema fields.

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 is largely complete given the output schema exists and covers return values. It explains purpose, safety, result semantics, and the alternative tool. The only notable gap is that server_version is a required parameter with no schema description and no explanatory mention in the description, which is a small but real completeness gap for a required input.

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

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

Schema description coverage is 83%, so the schema already documents five of six parameters well. The description adds useful context for summary_only and reinforces the allowed status values. However, it does not help with server_version, the one parameter lacking schema documentation, and it adds no deeper semantics for limit, offset, or model_id beyond what the schema already provides.

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

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

The description states a specific verb and resource: 'Run the deterministic assurance assessment over a threat model.' It clearly explains what the tool evaluates and returns, and distinguishes itself from check_control_gaps by naming that sibling explicitly. An agent can tell exactly what assess_model does and what it does not do.

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: for LLM-based reasoning about which control objectives are under-covered and what controls to add, use check_control_gaps instead. It also explains when to use summary_only=True. This is clear when-to-use and when-not-to-use guidance, not just implied context.

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

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

With no annotations, the description carries the full burden and does so well: it flags the operation as 'Mutating,' states both variants are 'mechanical / non-AI-gated,' and discloses the only validation rule. It also explains downstream effects like visibility to coding agents and boundary context flowing into reachability derivation.

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

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

The core action and mutation flag are front-loaded, and the two variants are organized in clean bullets. Every sentence earns its place, with concrete examples and domain rationale that support correct invocation 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?

Since an output schema exists, return-value documentation is not required. The description covers both target types, appropriate use cases, replacement semantics, unscoping via empty string, and validation rules, making it complete enough for an agent to call the tool correctly.

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

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

Schema coverage is already high at 83%, and the description still adds meaningful value for target_type, target_id, and component_ids with examples, empty-string behavior, and multi-instance asset guidance. It leaves server_version undocumented in both schema and description, which prevents a 5.

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

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

The description opens with a specific verb and resource: 'Replace an asset's or a control's component scope.' The two target_type variants are fully spelled out with examples, so an agent can distinguish this from siblings like add_component or edit_component.

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 'Use when' scenarios for the control variant: wiring an unscoped control, adding a second component to a cross-cutting control, and correcting a wrong assignment. It explains the asset variant's purpose for reachability, but it does not name when-not-to-use conditions or alternative 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 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 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?

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?

With no annotations, the description carries the disclosure burden and does so well: it states this is mutating ('persists a proposal record'), that raising is not deciding, that design changes are never applied automatically, and that a person or delegated agent decides via decide_proposal. It stops short of stating explicit auth/permission requirements or any limits, so it is strong but not exhaustive.

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

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

Two compact paragraphs, front-loaded with the action and the trigger condition, then the lifecycle note. Every sentence earns its place; the only minor cost is slight repetition between 'Raise a proposal...' and 'A proposal is a change of scope or design.'

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 covers the workflow end-to-end: what the tool does, when to call it, that it is not the decision step, that changes are not auto-applied, and how to poll for the outcome. 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 description coverage is 83%, so the schema already documents kind, payload, evidence, model_id, rationale and their formats (including the per-kind payload shapes). The description adds conceptual framing for what a proposal is but no syntax or constraint detail beyond the schema, 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 ('Raise a proposal to change a model's scope or design') and explicitly scopes the kinds of changes covered (gain/lose a component, remove an attacker position or asset). It also distinguishes itself from direct model editing and from the decision step, so an agent can place it among siblings like 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 explicit when-to-use triggers ('when the code or your analysis says the model should gain or lose a component...'), an explicit when-not ('do not edit the model directly for those changes'), and names the alternatives for the follow-up step (decide_proposal, list_proposals). This is the full when/when-not/alternative triad.

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?

No annotations, so the description carries the full burden and does so: it declares the operation mutating ("closes the proposal and applies an accepted change"), describes the 403 + escalation_id refusal path, notes the decision is parked for a person as a decision_request, warns against retrying, and explains that accepting an assumption is itself a separate decision (assumption_accepted) not covered by a rule delegating proposal acceptance.

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 the delegation gate, and every paragraph adds distinct information. It is dense and slightly long, but the length is justified by the authorization and refusal semantics.

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

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

An output schema exists, so return values need not be described. Combined with the delegation precondition, refusal handling, and per-kind acceptance semantics, an agent has everything needed to invoke this correctly and recover from a refusal.

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

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

Schema coverage is 83%, so the schema already documents most fields. The description still adds real semantics beyond it: expires_at applies specifically to accepting an assumption proposal with a one-year default, and decision acceptance has downstream effects (attestation until expires_at, binding into the waiting group; rejection records the precondition as rejected so it is not re-proposed).

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 concrete verb pair and resource ("Accept or reject a proposal") and distinguishes itself from the sibling tools that create proposals (create_proposal) and read them back (list_proposals). The scope is unambiguous.

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

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

States explicitly when this may be called (only when the delegation policy names the decision at the proposal's tier, per get_control_work_order), what to do on refusal (report escalation_id, do not retry, poll list_proposals), and how acceptance differs by proposal kind. When/when-not and the follow-up path are all named.

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 must carry the full burden, and it does: model version bumps, record dropping on edit/re-parent, idempotency of reject, server re-validation with a 400, and a 503 when composition is unavailable. These are exactly the side effects and failure modes an agent needs before calling a mutating 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?

Front-loaded with purpose and the mutating flag, then organized as per-decision bullets. Dense but every bullet carries operative information; minor redundancy in restating return payloads that the output schema already covers.

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 3-way branching mutating tool with 8 undocumented parameters, the description supplies preconditions, side effects, error codes, and return shapes, more than enough for correct invocation. Nothing an agent needs is missing.

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

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

With 0% schema coverage the description must document all 8 params; it explains kind, own_qid/inherited_qid with concrete qualified-id format examples, the decision enum, confirm_heuristic's role, and rejection_id's source. server_version and model_id are used but never explained, leaving a small gap.

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

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

States a specific verb ('Decide') and resource ('reconciliation candidate'), explicitly ties it to the sibling tool list_reconciliation_candidates, and flags the mutating nature. An agent can immediately tell what this tool does and where its inputs come from.

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?

Breaks out all three decision values with when-to-use semantics (apply = descendant IS inherited, reject = not duplicates at org scope, unreject = restore from rejected queue), names the alternative list call with the disposition filter for unreject, and states the confirm_heuristic precondition for heuristic-tier candidates.

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 usefully discloses that the tool is mutating ('records this model as a foundation and stores its advertised controls') and defines what a foundation is, but says nothing about permissions, reversibility, idempotency, or whether re-declaring overwrites existing controls.

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 status are front-loaded, followed by supporting definition and the provides example. Every sentence is relevant, though the grammar and layering are slightly dense.

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

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

An output schema exists so return values need not be described, and the description covers the mutation and the core provides semantics. For a mutating, no-annotation tool it is nearly complete, but missing any note on permissions, side effects on other models, or overwrite behavior.

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

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

Schema coverage is 75%, and the description adds real meaning beyond the schema: it gives the exact shape of a provides entry and a key semantic constraint ('a capability always advertises a control (a proven mechanism), never an objective') that is not expressed in the schema. It does not elaborate on visibility or server_version, so 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?

States a specific verb+resource ('mark a model as a shared foundation that advertises providable controls') and clearly distinguishes this from the sibling attach_foundation, which is the consumer side of the relationship. An agent can tell what this tool 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?

Explains the delegation workflow and points to attach_foundation as the counterpart, giving clear context for when this tool applies. It lacks an explicit when-not to use it or any prerequisite/ordering guidance, so it falls short of the 5 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 provided, the description carries the full burden and does so richly: it discloses that deletion is permanent and not a soft-delete, that the assertion's contribution to sufficiency/verification is dropped, that it does NOT itself re-run verification, and that a background re-evaluation is queued and later surfaced via get_sufficiency. This is exactly the behavioral context an agent needs before a destructive call.

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

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

Front-loaded with the destructive nature and scope, then the background-re-evaluation caveat, then routing/alternatives. Every sentence earns its place and no filler is present.

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

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

An output schema exists so return values need not be described, yet the description still routes the agent to get_sufficiency for the queued re-evaluation result. For a destructive, ownership-constrained mutation tool, 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 description coverage is 80%, so control_id/assumption_id/model_id are already documented in the schema, and the description's 'from a control or assumption' largely restates that. It adds the ownership constraint (own vs inherited) which is behavioral rather than parameter-syntactic, so baseline 3 is appropriate.

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

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

States a specific verb ('Permanently delete') and a precisely scoped resource ('a single assertion from a control or assumption'), and immediately distinguishes itself from the sibling write tool submit_assertions and the read tool list_assertions. An agent can tell exactly what this does and what it is not.

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

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

Gives explicit when-to-use triggers ('retract a claim that was submitted in error or that get_verification_report flagged as misaligned'), names alternatives with their conditions (submit_assertions to add, list_assertions to inspect first), and adds a hard exclusion: only 'own' assertions can be removed, inherited ones must be managed at the source model.

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 explicitly states that the operation is destructive/mutating, that it is a soft delete rather than a permanent erase, and that it can block with HTTP 409 under a specific coverage condition. This is substantial and goes well beyond a generic description, though it stops short of covering permissions or reversibility details.

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 action, the second clarifies destructiveness, and the third explains the blocking condition and required remedy. Every sentence contributes necessary operational information with no filler.

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

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

Given the tool's moderate complexity and the presence of an output schema, the description covers the essential operational context: what the operation does, its side effects, and the key failure mode. It does not explain server_version semantics or mention any other restrictions, but the core invocation context is sufficiently complete for an agent to use the tool correctly.

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

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

Schema description coverage is 75%, so the schema already documents most parameters. The description adds context about the justification being optional and about the 409 condition, but it does not add meaningful detail for model_id, control_id, or server_version beyond what the schema provides. This is adequate given the high 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 opens with a specific verb and resource: 'Soft-delete a security control,' which immediately distinguishes this from other control-related tools. It also clarifies the semantic nuance ('retired, not permanently erased'), removing ambiguity about the lifecycle impact. This clearly separates it from hard-delete or update operations.

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

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

The description provides clear context for when the tool will succeed or fail, including the HTTP 409 blocking condition and the prerequisite to add a replacement control or refine the threat model. It does not explicitly name alternative sibling tools or state when not to use the tool, but the practical guidance is strong enough to guide invocation 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 largely does so: it declares the operation mutating, enumerates the collateral destruction (framework selections, requirement exclusions, relevance data), and explicitly bounds the blast radius (member models unaffected; propagated frameworks stay selected). It stops short of stating irreversibility or required permissions.

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 with the mutation status front-loaded and the destructive/who-is-affected split handled economically. No filler, though the opening 'tag' framing costs clarity.

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

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

An output schema exists so return values need no explanation, and the description usefully covers side effects for a no-annotation mutation. But it omits any handling of the undocumented server_version parameter and any irreversibility/permission note that a destructive tool warrants.

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%, so the description should compensate but adds nothing about parameters. It never mentions group_id, and server_version is undocumented in both schema and description, leaving the agent without a value format or source for a required parameter.

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

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

The verb+resource pair is muddled: the tool is delete_group and its siblings all use 'group' (get_group, create_group, add_model_to_group), yet the description says 'Delete a tag.' An agent must infer that 'tag' and 'group' are the same entity, which weakens confident selection.

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

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

No when-to-use guidance, no prerequisites, and no routing to or away from siblings such as delete_threat_model, delete_control, or delete_assertion. The agent gets no signal about when deletion is appropriate versus other cleanup paths.

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 full responsibility for behavioral disclosure. It clearly states the operation is destructive, permanent, and mutating; enumerates exactly what is removed; explains downstream effects on reliance edges and consumer posture; and documents the return value. This is exemplary transparency.

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 most critical fact ('Destructive and permanent'), then gives a concise but complete list of side effects, followed by usable guidance and the return shape. Every sentence earns its place; no filler or redundant restating of the name.

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

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

The description is highly complete for a destructive operation: it covers permanence, affected data, indirect effects on other models, a backup path, and the response. The only notable gap is the unexplained required server_version parameter, which weakens end-to-end invocability.

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

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

Schema description coverage is 50%: model_id is described, but the required server_version parameter has no description and no enum or format guidance. The tool description adds nothing about either parameter, so an agent cannot confidently determine what server_version should be.

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: 'Delete a threat model and all associated data.' It sharply distinguishes this from sibling deletion tools by emphasizing the permanent, cascade-deleting scope, so an agent can tell it apart from delete_control, delete_assertion, delete_group, or remove_entity.

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 operational guidance: confirm intent before calling and export an archive if a copy is needed. It does not explicitly enumerate when not to use this tool versus nearby siblings, but the destructive scope and backup advice effectively frame 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?

With no annotations, the description carries the full burden and does so richly: it discloses what is destroyed (staged items), what is preserved (published controls untouched), side effects (model released, build re-proposed), cost (credits not returned), and a hard precondition (pause a running build first).

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

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

Front-loaded with the verb+resource and the mutating flag, then behavior, then return shapes. Every sentence is informative, though the enumerated return block is somewhat verbose given an output schema already exists.

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 tool with zero annotations, the description covers destruction semantics, side effects, credit cost, and preconditions, plus concrete success/error return codes. An agent has everything needed to call it correctly without opening 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 coverage is 50%: model_id is documented in the schema, server_version is not. The description adds no parameter-level meaning beyond the schema (it only refers to 'a model'), so it neither compensates for the coverage gap nor adds value. Baseline 3 for a two-param tool where the schema does the documented half.

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 ('discard') and resource ('a model's held control build') and immediately qualifies the operation as mutating. It clearly separates itself from siblings like delete_control and start_control_build by scoping to a held (non-running) build.

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 the applicable states (queued, deferred, paused, blocked) and the exclusion condition: a running build must be paused first, naming the alternative tool (pause_control_generation) and the wait condition. This is explicit when/when-not guidance with a named alternative.

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 full behavioral burden and satisfies it: it discloses LLM gating on identity-bearing fields, the rejected-edit response shape, that nothing is saved on rejection, server derivation of impact, audit-trail capture, and specific 503/502/400 error conditions. This is far beyond a generic 'edit' statement.

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 earns its length for a 16-parameter mutation tool: it is front-loaded with the core behavior, then uses bold labels, bullets, and error summaries to make the constraints scannable. There is no filler or repeated schema content.

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

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

Given the tool's complexity, the presence of an output schema, and no annotations, the description covers all decision-relevant behavior: partial-update semantics, LLM gating, audit trail, soft-delete handling, and error conditions. An agent has enough context to invoke it correctly without opening sibling definitions.

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?

Despite 94% schema coverage, the description adds grouping semantics the schema alone does not convey: identity-bearing fields vs factor/notes fields, the no-status-field caveat, the requirement to send change_reason with factor fields, and the impossibility of setting impact directly. It clarifies the relationship between change_reason and the factor/rating parameters.

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 'Edit an existing asset. Only provided fields changed' states a specific verb and resource with scope, and the rest clarifies it updates rather than creates (contrasting with add_asset). It is clearly distinct from sibling edit tools for other entity types.

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 and preconditions: soft-deleted assets require restore_entity first, rating changes require setting factor values plus change_reason, there is no status field to set, and rejected edits must be handled by soft-delete + add-new. It names alternatives (add_asset, restore_entity) and the conditions that select them.

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 disclosure burden. It does disclose one meaningful side effect — editing creates a new model version — which is valuable versioning context that the schema does not state. However, it omits other behavioral traits like the predicate-rewriting semantics and the mutual exclusivity between clear_exclusion and exclusion_* params, both of which remain buried 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?

Two sentences with zero wasted words; the primary operation is front-loaded and the versioning side effect follows immediately. It is efficiently structured, though for a 12-parameter tool arguably under-specified rather than optimally sized.

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 rich 92%-covered schema and the presence of an output schema carry most of the load, so an agent that reads the schema can likely invoke this tool correctly. However, the description alone offers no when-to-use guidance and does not explain the versioned workflow implied by the required server_version param. Adequate but with clear gaps.

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

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

Schema description coverage is 92%, so the baseline of 3 applies; the schema thoroughly documents the exclusion_* rewrite behavior, defaults, and mutual exclusivity. The description contributes no parameter-level meaning, and notably it does not clarify the one required param without a schema description (server_version), which is a minor missed opportunity.

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?

"Edit an assumption" is a specific verb-plus-resource statement that clearly identifies the operation and, by verb choice alone, distinguishes it from the sibling add_assumption. The second sentence, "Creates a new model version," adds precision about what an edit entails, though the description never explicitly contrasts it with sibling 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?

No guidance is given on when to edit an assumption versus adding one (add_assumption) or converting assumptions to controls (convert_assumption_to_controls). There are no prerequisites, exclusions, or contextual cues beyond the bare operation itself, leaving the agent to infer applicability.

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 full behavioral burden and does so thoroughly: patch semantics, LLM gating, server-derived likelihood, quality_warning on contract violations, specific HTTP error conditions, and surface_extent attestation with forking and refusal rules. This goes far beyond a generic 'edit' 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?

Front-loaded with the essential edit semantics and dense with useful detail; no filler sentences. The surface_extent paragraph is long and intricate, but it encodes necessary refusal and forking semantics, so it earns its place despite being heavy.

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 17-parameter mutation tool with no annotations and an output schema present, the description covers all non-obvious behavior: patch semantics, gating, error responses, audit trail requirements, and attestation constraints. 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 94%, but the description adds critical meaning beyond it: capability must name operations performable from the position, likelihood is server-derived and cannot be set directly, change_reason triggers and error conditions, and surface_extent attestation has deep structural consequences. Without this, several parameters would be ambiguous.

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?

First sentence, 'Edit an existing attacker. Only provided fields changed,' names the exact verb/resource and clarifies patch semantics. It is unambiguously distinct from sibling creation/editing tools and even references add_attacker for the authoring contract.

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

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

Provides clear operational context: edits an existing attacker, only supplied fields change, identity fields are LLM-gated, and change_reason is required for factor/surface_extent edits. It does not explicitly contrast with alternatives like add_attacker or edit_asset, but its scope is unmistakable and the 'see add_attacker' pointer helps.

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 behavioral burden. It meaningfully explains the non-obvious partial-update behavior ('backend treats absent fields as unchanged') and clarifies that grade fields are independent orthogonal axes. This goes well beyond a bare 'edit a component', though it does not cover permissions, validation, or side effects.

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

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

The description is compact and front-loaded with the core purpose, then adds only the essential behavioral nuances. The 'orthogonal axes' metaphor is slightly dense but earns its place by framing the partial-update model. It is not bloated.

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 plus a 90%-covered schema is largely sufficient for calling the tool: required IDs are in the schema and partial-update semantics are stated. However, it lacks guidance on how this tool relates to sibling edit tools, and it leaves the required server_version parameter unexplained. The presence of an output schema mitigates some of the gap, but the overall guidance is not fully complete.

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

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

Schema description coverage is 90%, so the baseline is 3. The description adds valuable semantics beyond the schema by explaining that per-component grades are orthogonal and that leaving fields unset preserves server-side values. This clarifies how to handle the nullable grade fields and the empty-string fields in practice.

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 action ('Edit') and the resource ('a component's properties'), which distinguishes it from other edit_* siblings that target different resources. However, it does not explicitly differentiate itself from sibling tools by scope or use case, so it stops short of a 5.

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

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

The description gives solid operational guidance about partial updates ('absent fields are unchanged') and when to set grade fields ('set whichever apply'), but it does not explicitly say when to use this tool versus alternatives like edit_asset or edit_trust_boundary. Usage context is implied rather than stated.

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

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

With no annotations, the description carries the full burden and largely meets it: it declares the operation mutating and, more valuably, states the non-effect of removal on status and assertions - a semantic trait an agent could otherwise guess wrong. It still omits permission requirements, whether edits are auditable/undoable, and any 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?

Purpose is front-loaded in the first sentence, followed by a one-word mutation flag, then the semantic caveat. The caveat is slightly restated twice ('removing it changes neither the status nor any assertion' / 'Only assertions prove controls'), but both sentences carry distinct weight and nothing is padded.

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

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

Eight parameters at 88% schema coverage plus an output schema mean structured fields handle details; the description supplies exactly the missing conceptual layer - that this is a mutation of contextual metadata with no effect on control implementation status - which is what an agent needs to decide whether to call it.

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

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

Schema description coverage is 88%, so the schema already documents the action enum, item type values, and the zero-based evidence_index. The description adds only a high-level gloss (attach vs detach, what an item is), which is marginal beyond the structured data, so baseline 3 is appropriate.

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

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

States a concrete verb pair (attach/detach), the resource (an auxiliary evidence item), the item kinds (doc, link, artifact reference), and the parent object (a control). The closing line distinguishes evidence from assertions, which is exactly the boundary that separates this tool from assertion-oriented siblings in the list.

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

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

The statement that evidence 'does NOT count toward a control's implementation status' and that 'only assertions prove controls' implicitly tells the agent when this tool is appropriate versus proof-bearing tools. However, there is no explicit when-to-use rule, no prerequisite call chain (e.g., read evidence_index via get_controls before removing), and no named alternative.

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 one important side effect—edits create a new model version—which is valuable behavioral context for a mutation tool. However, it does not mention the audit trail, change_reason requirements, attestation implications, or whether edits are reversible.

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 only two sentences and front-loads the core purpose. The first sentence is somewhat redundant with the tool name, but the second earns its keep by revealing the versioning side effect.

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 9-parameter mutation tool, this is barely adequate. The rich paramether schema and presence of an output schema compensate for much of the missing detail, but the description alone does not fully convey the implications of editing a trust boundary, such as versioning consequences and the audit/change_reason context.

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

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

Schema description coverage is 89%, so the schema already explains most parameter semantics. The tool description adds no parameter-level details, but with high schema coverage the baseline of 3 is appropriate.

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

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

The description names a specific verb and resource ('Edit a trust boundary') and adds a meaningful distinguishing behavior ('Creates a new model version'). It clearly identifies this as the editing counterpart to add_trust_boundary and other edit_* tools, though it does not explicitly name a sibling alternative.

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

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

There is no guidance on when to use this tool vs. add_trust_boundary or other editing tools. The verb 'Edit' implies use for existing trust boundaries, but no exclusions, alternatives, or context signals are given.

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

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

With no annotations, the description carries the full burden and does so: it declares read-only/no side effects, discloses that pdf/html run as a potentially slow server-side job with automatic progress reporting, specifies the exact return fields per format (content, content_b64 + content_type, envelope), and enumerates what the archive does NOT include (earlier versions, activity, chat).

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 purpose and safety note, then organized as a clean scope→format matrix. The archive bullet is dense and long, but every clause conveys behavior an agent needs (contents, exclusions, return shape, downstream tool); minor verbosity 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?

An output schema exists, yet the description still pins down the format-dependent return keys, which is exactly the ambiguity an output schema alone would leave. For a read/export tool with two enums and a cross-field constraint, 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%, but the description adds substantial meaning beyond it: it explains that scope determines how scope_id is interpreted, which format values are legal per scope, and what each format's payload actually is. It documents the interaction the flat schema cannot express.

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 (export a threat model or tag as a downloadable document) and immediately bounds scope to two entity types. It also names the counterpart tool (import_threat_model_archive), so an agent can place it in the workflow 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?

Gives explicit when-to-use mapping: which format applies to which scope, and explicitly states that csv/pdf/archive are rejected for tag scope. It routes to import_threat_model_archive for restoring an archive. It stops short of stating when to prefer a different export/report tool (e.g. get_compliance_report, get_verification_report), so not a full 5.

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

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

With no annotations provided, the description carries the full disclosure burden and does so well. It explains side effects: refresh=true re-derives from scratch and replaces prior generated content while preserving manually authored content. It also discloses billing, time cost, and the systematic taxonomy-driven process.

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

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

The description is front-loaded with the core purpose, then adds a precise definition of the internal concepts, and finishes with operational constraints. Every sentence earns its place, and the length is appropriate for the complexity.

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 and the presence of an output schema, the description covers the input requirements, workflow, output nature, side effects, and usage constraints. An agent has enough context to invoke the tool correctly and understand its consequences.

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 model_id and refresh, and the description adds meaningful depth to refresh by specifying that it replaces prior generated (not manually authored) capabilities, objectives, and tests. However, server_version remains undocumented in both the schema and description, so coverage is not complete.

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

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

The description uses a specific verb, 'derive', and names the resource: capabilities, functional objectives, and concrete tests from a feature spec. It clearly distinguishes this generation tool from retrieval siblings like get_functional_objectives by emphasizing that it creates testable Given-When-Then objectives and implementable tests.

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

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

The description gives useful context about when to use the tool (from a feature spec, requires Pro plan, billable, may take time) but does not explicitly contrast it with related alternatives like get_functional_objectives, add_functional_test, or import_functional_tests. Usage is implied rather than explicitly routed.

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 behavioral burden and performs well: it discloses a multi-step AI pipeline, automatic progress reporting, the exact JSON shape returned on similar-model short-circuit, and the rule that the request is always treated as generation rather than a question or a change to another model. It does not state permission/auth requirements, rate limits, or whether created models are reversible, which keeps it from a 5.

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

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

The purpose is front-loaded in the first sentence, and the remaining sections are logically ordered: methodology, outputs, pipeline behavior, then similarity handling. It is longer than typical, but most sentences carry decision-relevant information; the closing paragraph about request intent is useful but slightly advisory.

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 multi-step generation, 10 parameters, 90% schema coverage, and an output schema, the description covers the non-obvious behaviors an agent needs: pipeline execution, progress reporting, similarity short-circuit return shape, and next-step routing. It stops short of stating permissions or workspace side effects, but those are secondary for this tool.

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

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

Schema description coverage is 90%, so the schema already documents the 10 parameters in detail; per the rubric that sets a baseline of 3. The description adds a usage cue for force=True but does not add meaning for parent_id, provenance fields, or the other parameters beyond what the schema provides.

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

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

States a specific verb (generate) and resource (threat model) scoped to a feature description, and names the methodology used. Sibling differentiation is explicit: the short-circuit paragraph points to refine_threat_model as the alternative when an overlapping model exists, so the agent can distinguish this tool from its nearest neighbor without opening schemas.

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