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

Annotations only declare readOnlyHint=false and destructiveHint=false. The description goes further, disclosing that it marks the caller as approver with a current timestamp, captures rationale and expiry, renews existing acceptances, and returns 403 for a platform key with no associated user. It omits detail on reversibility or partial-failure behavior, keeping 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 core action is front-loaded in the first clause, and every subsequent clause adds a genuine behavior (write/admin classification, approver recording, renewal, exception, auth failure). It is dense but not padded; the middle sentence fragments are slightly clipped but readable.

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 write tool with no output schema, the description covers the action, the admin privilege requirement, the side effects (approver recording, timestamp, expiry), and a specific error path (403 on platform keys). That is nearly everything an agent needs; only the response shape or reversibility would add more.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters with formats, patterns, and validation rules. The description's mention of 'the rationale and expiry' only restates what the schema already conveys, so it adds little beyond 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?

Starts with a specific verb+resource ('Accept a risk') and then enumerates its distinct behaviors: recording an approver, renewing an accepted risk, and accepting a standards exception. This distinguishes it clearly from siblings like scf_create_risk and scf_update_risk_assessment.

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 names the concrete situations of use — initial acceptance, renewal of an accepted risk, and standards exceptions — so an agent knows when to reach for it versus creating or updating a risk. It does not name alternative tools or an explicit 'when not to use' condition, so it falls short of a full 5.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds real value by disclosing the write's authorization requirement (editor), its side effect (creates a linked deficiency record), and a server-side refusal condition. It does not cover idempotency or duplicate-finding behavior, 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 dense sentences, front-loaded with the action and its effect, followed by the precondition. Every clause carries information — nothing is redundant or padding.

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

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

For an 11-parameter mutation with full schema coverage and annotations declaring the safety profile, the description supplies the missing behavioral context. With no output schema, it does not say what is returned (e.g. the created finding/deficiency identifier), which is a minor remaining gap.

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

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

Schema description coverage is 100%, so every one of the 11 parameters is documented inline (including cross-tool hints like scf_list_organizations). The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (add a finding to a capability test) and immediately discloses the resulting artifact — the finding is recorded as a deficiency linked to the test. This lets an agent distinguish it from scf_create_deficiency and scf_update_capability_test without opening either schema.

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

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

Gives an explicit precondition and exclusion: the call is refused on a test already recorded as passed, and the caller should correct the test result instead. It also names the required role (editor). It stops short of naming the sibling tool (e.g. scf_update_capability_test) that performs that correction, so it is clear but not fully routing.

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

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

Goes meaningfully beyond the annotations by disclosing an authorization requirement (editor+) and a non-obvious side effect: changing an accepted exception's links clears its approval. That is exactly the kind of hidden consequence annotations (destructiveHint=false, readOnlyHint=false) cannot convey. It stops short of describing idempotency or conflict/duplicate-link 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?

Two compact clauses, front-loaded with the action and scope, with the permission note and the side-effect warning packed in without filler. 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 4-parameter mutation with no output schema, the definition covers what it writes, who can call it, and a key side effect, which is most of what an agent needs. Missing minor details such as duplicate-link handling and the shape of the confirmation response.

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

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

Schema coverage is 100% and each parameter already documents format plus its source tool. The description restates the optional document semantics ('document whose standard it is an exception against') that the schema property already spells out, so it adds little beyond the structured fields.

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

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

States a specific verb (link) and resource (control to custom risk), and the optional document qualification. An agent can distinguish it from siblings scf_update_custom_risk_control, scf_remove_custom_risk_control, and scf_list_custom_risk_controls 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.

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

Specifies the caller precondition ('write — editor+') and the optional document use case, which tells the agent when the exception variant applies. It does not explicitly contrast with the update/remove siblings, so alternative-choice guidance 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?

The description discloses that re-granting a revoked auditor reactivates the grant, a behavioral nuance not covered by annotations. It also clarifies that access is scoped to frozen scope and queries. Since annotations only indicate non-read-only and non-destructive, the description adds valuable behavioral context beyond what annotations provide.

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

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

The description is two sentences, front-loads the main action, and provides essential details without redundancy. Every clause adds information—the action, the scope, and the reactivation behavior—making it highly efficient.

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

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

For a simple grant operation with three fully documented parameters and no output schema, the description covers the action, scope, and a key edge case (re-granting). It does not explicitly state prerequisites like required admin permissions, but the 'write — admin role' hint implies this. Overall, it is sufficiently complete 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 description coverage is 100%, with each parameter having a clear description including how to obtain the UUID (e.g., from scf_list_organizations). The tool description does not add parameter-specific details beyond what the schema already provides, so 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 clearly states the action: granting an existing user read access to one engagement. It specifies the resource (engagement) and the recipient (existing user), and distinguishes from sibling tools like remove_engagement_auditor. The phrase 'write — admin role' adds a slight ambiguity but does not obscure the core purpose.

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

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

The description explains the scope of access (frozen scope and queries only) and mentions the re-grant behavior for revoked auditors, which gives context on when this tool is appropriate. However, it does not explicitly compare to alternatives such as scf_remove_engagement_auditor or scf_list_engagement_auditors, leaving the agent to infer the appropriate use case.

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

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

The description discloses the demotion side-effect (incumbent becomes member) and notes it's a write operation requiring admin. This goes beyond the annotations, which already mark destructiveHint=true, and provides meaningful behavioral context.

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

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

Two sentences with no filler. The critical behavioral detail (demotion) is included, and the sentence structure front-loads the action and role options.

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 write operation with four well-documented parameters and an explicit demotion rule, the description covers the essential context an agent needs. It doesn't specify return values, but no output schema exists and the behavior is clear enough.

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 already describes all four parameters with sources for IDs. The description adds semantic meaning for membership_role by explaining the three roles and the demotion rule, which clarifies the enum values beyond the schema's generic 'Seat on the team'.

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

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

The description states a specific action ('Add an organization member to a team'), the resource involved, and the allowable roles. It clearly distinguishes from siblings like scf_remove_team_member and scf_update_team by focusing on the add operation and the role semantics.

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

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

The description indicates the operation requires an admin role and explicitly notes the demotion behavior when a seat is taken. It doesn't name specific alternatives, but the context makes when to use this tool unambiguous given the sibling set.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description adds valuable behavioral context: admin role requirement, asynchronous execution, and the stale-preview guard. It also explains a failure mode (refusing stale previews), which is exactly the kind of info annotations don't convey. This is rich, non-redundant disclosure.

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

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

The description is compact and front-loaded: the core action, authorization, and async nature appear in the first sentence, followed by the key precondition and rationale. Every sentence earns its place; no filler or repetition of 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?

For a destructive, async write operation with no output schema, the description covers the essential preconditions, auth, and failure behavior. It doesn't explicitly state how to track the async result, but the sibling tool scf_get_catalog_reconciliation_status is present in context, so the agent can discover the next step. Minor gap: no mention of what a successful apply returns or whether it is undoable.

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 input schema already covers all three parameters with descriptions, including expected_to_version's role in guarding stale previews. The tool description reiterates the expected_to_version matching condition but adds no new parameter-level semantics. With 100% 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 opens with a specific verb and resource: 'Apply a previewed reconciliation run'. It adds context that this is a write operation requiring an admin role, and the 'previewed' qualifier distinguishes it from preview, list, rollback, and cancel siblings. This is a clear, unambiguous statement of what the tool does.

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 preconditions: the run must be 'previewed' and expected_to_version must match, with a concrete reason ('a stale preview is refused rather than applied'). This implicitly tells the agent to first obtain a preview before applying. It does not explicitly name alternative tools or exclusions, but the workflow implication is strong enough to guide usage.

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

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

Annotations already mark readOnlyHint=false and destructiveHint=true; the description reinforces this with 'write — editor+' and adds that the attester is recorded. It also flags the exclusive side effect ('The ONLY way a stage passes') and the conditional-pass constraint, giving the agent behavioral context beyond the structured fields.

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

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

Three short sentences: purpose, exclusivity/side effect, and conditional-pass rule. No filler or repetition of schema property descriptions.

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

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

With no output schema and a write/destructive tool, the description covers permission level, what happens when called, and the condition for target_date; the schema covers identifier sourcing. It is complete enough to invoke correctly, though it does not spell out reversibility or response shape.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including that conditional requires target_date. The description reinforces the conditional/target_date dependency but does not add new parameter-level meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description opens with 'Pass a journey stage by named attestation' — a specific verb, resource, and mechanism. It further distinguishes itself by declaring it is 'The ONLY way a stage passes — nothing advances on computed evidence', so an agent can see this is the write pathway, not a computed assessment.

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 when-to-use context: passing is manual/named and nothing advances automatically, so the agent knows not to wait for computed evidence or use a read-only journey tool. It also states conditional passes require target_date. It does not name an alternative tool, but within this domain there is no equivalent stage-passing sibling, so no exclusion is needed.

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

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

Annotations declare readOnlyHint=false and destructiveHint=true, but the description adds valuable behavior beyond that: it is explicitly a write operation, requires an admin role, executes in one transaction, and produces one aggregate notification. It does not elaborate on side effects like overwriting existing assignments, but it meaningfully exceeds the annotation baseline.

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

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

Two tight sentences with no filler: the core action and limits are front-loaded, followed by a memorable one-line purpose tag. Every clause carries information.

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

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

For a batch write tool with five parameters and no output schema, the description covers the essential operational constraints: max batch size, item types, transaction semantics, notification behavior, and role requirement. It could be more complete by mentioning whether prior assignments are replaced, but the essentials for correct invocation are present.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents org_id, team_id, type, item_ids, and is_accountable. The description reinforces that item_ids target controls or evidence and caps at 500, but it does not add deeper meaning such as the default false behavior of is_accountable or interaction with existing assignments.

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 ('Assign'), a precise resource ('one team to up to 500 controls or evidence items'), and a clear transactional scope. It also adds the tagline 'bulk accountability tool' that distinguishes it from the single-item sibling scf_create_team_assignment and the read-only scf_list_team_assignments.

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

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

The description communicates clear usage context: this is the batch variant, capped at 500 items, for assigning one team across controls or evidence. It does not explicitly name scf_create_team_assignment as the alternative for single assignments, nor state when-not to use it, so it stops short of a 5.

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

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

Adds substantial behavior beyond the annotations: atomic single-transaction semantics, an editor+ authorization requirement, a 409 refusal path for deselecting material/MCR controls, and the non-obvious side effect that at_risk raises a deficiency. These are exactly the traits an agent cannot infer from readOnlyHint=false / destructiveHint=false.

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

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

Three tight sentences, front-loaded with the verb/resource/cap, followed by permission, then the two failure/side-effect rules. No filler or restated title.

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 2-parameter, 100%-documented batch mutation, the description covers purpose, auth, limits, and error semantics well. The only gap is the response shape — there is no output schema, and the description never says whether partial failures return per-operation results or whether the whole transaction rolls back.

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

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

Schema description coverage is 100%, so every field is already documented, and the description's scf_id reference and the 409 deselect rule are both restatements of the schema's own `selected` description. Baseline 3 applies since the description adds no new parameter meaning.

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 (batch-update), resource (scoped controls), and scale/scope (up to 500, one transaction). This clearly differentiates it from the single-record sibling scf_update_scoped_control without the agent needing to open either schema.

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

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

Gives an actionable usage gate (write — editor+) and the shape of an operation (each targets an scf_id), which tells the agent when the tool is applicable. It stops short of naming the single-control alternative or stating when a batch is inappropriate (e.g., 1-item updates).

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

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

Annotations already signal write (readOnlyHint=false) and non-destructive (destructiveHint=false), and the description adds meaningful context beyond that: it runs in one transaction, requires editor role, and applies partial updates so only provided fields change. The 'one transaction' wording also implies all-or-nothing behavior, which is valuable for an agent deciding whether to call this 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?

Two dense sentences with no filler. The first sentence delivers scope, capacity, atomicity, and role; the second adds upsert semantics and points to the appropriate sibling tool. Every clause earns its place.

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

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

For a 2-parameter batch write with a fully described schema, the description covers capacity, transactionality, permissions, partial-update behavior, and sibling routing. No output schema exists, but nothing essential for selecting or calling the tool 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 100%, so the baseline is 3. The description adds valuable cross-parameter semantics by stating that each operation is keyed by evidence_id and that only given fields change—information not fully expressed by individual parameter descriptions. This elevates it above baseline.

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

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

The description states a specific verb and resource: create or update up to 500 evidence tracking records in one transaction. It further clarifies the upsert key (evidence_id) and distinguishes this batch operation from single-record tools like scf_update_evidence. There is no ambiguity about what the tool does.

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 frames when to use the tool: 'Use instead of 500 scf_update_evidence calls.' It also indicates an access prerequisite (editor role), giving an agent both the trigger condition and the relevant alternative. This is clear routing guidance with no inference required.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false; the description adds meaningful behavior: the operation is a write, requires editor+ role, is asynchronous, caps at 50 files, and returns a queued count. This goes well beyond the structured annotations.

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

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

Three short sentences pack the essential facts: purpose, role, async behavior, batch limit, input options, and return value. Every clause earns its place and the most important constraints are front-loaded.

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

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

For a four-parameter tool with no output schema, the description covers the operation, permissions, async behavior, limits, selector inputs, and return value. It is slightly incomplete in not stating explicitly that at least one of evidence_id/file_ids/assess_unassessed is practically needed to do useful work.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description's 'Provide evidence_id, file_ids, and/or assess_unassessed' adds minimal grouping guidance but does not meaningfully clarify syntax or semantics beyond the schema.

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

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

The description names a specific verb ('Queue'), a specific resource ('AI assessments for multiple evidence files'), and key constraints (write, editor+ role, async, max 50). The bulk scope clearly distinguishes it from single-file assessment 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?

The description tells the agent what to provide ('evidence_id, file_ids, and/or assess_unassessed') and conveys the async nature and batch limit. It does not explicitly contrast with close siblings like scf_trigger_evidence_assessment, so it stops short of full when-to-use/when-not-to-use guidance.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses that this is a write operation requiring editor+ role, that it is async, and that items lacking tracking or a frequency set appear under `skipped_detail`. This meaningfully explains side effects and edge-case behavior, though it does not detail post-queue tracking or partial failure semantics.

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

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

Two sentences with no filler; the core operation is front-loaded, and the parenthetical captures role and async behavior efficiently. The skipped-item behavior is placed where it is actionable.

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 2-parameter async queue operation, the description covers inputs, role requirement, async behavior, and a key response field (`skipped_detail`). It does not mention how to check the outcome of the queued assessments, but sibling tools exist for that and no output schema is expected.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds the skipped_detail behavior tied to evidence_ids, but does not add new syntax, format, or selection guidance beyond what the input schema already documents.

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 ('Queue') and resource ('windowed AI assessments'), and scopes the operation to 'up to 25 evidence IDs.' This clearly distinguishes it from the single-item trigger/list/get siblings like scf_trigger_window_assessment and scf_get_window_assessment.

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

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

The description implies batch usage with 'up to 25 evidence IDs' and notes the async write nature, but it does not explicitly state when to prefer this over scf_bulk_assess_evidence or scf_trigger_window_assessment. No exclusions or alternative routing are provided, so the agent has to infer the intended use case.

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

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

Annotations already declare destructiveHint=true, but the description adds real value: it names the required role ('editor'), discloses what is preserved ('Shared controls are kept'), and describes the escalation path to admin + reason for MCR/material-control cases. It stops short of covering reversibility or restorability, 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 tight sentences with zero filler; the destructive/scope semantics and the role requirement are front-loaded, and the qualifier that shared controls survive comes immediately after.

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

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

With annotations covering the safety profile and the schema covering all parameters, the description supplies the remaining behavioral context an agent needs (role, preserved controls, escalation). No output schema exists, but the description rightly omits return-value detail, leaving only the audit/rollback behavior unstated.

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

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

Schema description coverage is 100%, so org_id, frameworks slugs, and the removal_reason requirement are already documented in the schema. The description reinforces the removal_reason escalation rule but adds no syntax or format detail beyond what is already provided, so the baseline 3 applies.

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

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

States a specific verb and resource ('Unscope every control mapped only to these frameworks'), with the scope qualifier 'mapped only to' plus 'Shared controls are kept' pinning down exactly which controls are affected. This clearly distinguishes it from scf_scope_framework (the inverse) and scf_set_scope_override (single-control).

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 the escalation condition for edge cases (MCR framework or material-control removal needs an admin and a reason), which is useful context, but never states when to call this versus siblings like scf_scope_framework, scf_preview_framework_scope_change, or scf_set_scope_override. Usage is implied rather than explicit.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description carries the burden of explaining behavior. It adds that this is a write operation requiring admin role, that it applies only to unapplied runs, and that the catalog version is unchanged — useful context beyond the structured annotations.

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

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

The description is a single, compact sentence that front-loads the core action, then provides the precondition, permission, and safety outcome. Every clause earns its place with no redundant wording.

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

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

For a two-parameter mutation tool with no output schema, the description covers the essential context: what is cancelled, when it can be cancelled, who is allowed to cancel it, and what happens to the catalog. It could be slightly more complete by pointing to rollback as the alternative for applied runs, but overall it is well-rounded.

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

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

Schema description coverage is 100%, and both parameters already have descriptive provenance (org_id from scf_list_organizations, run_id from scf_list_reconciliation_runs or scf_preview_catalog_reconciliation). The description adds no additional parameter-level meaning, so 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 uses a specific verb ('Cancel') and resource ('a reconciliation run'), and adds the key condition 'that has not been applied.' It also signals the write nature and admin role requirement, making the tool's purpose distinct from related reconciliation operations like apply or rollback.

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

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

The description clearly states the precondition 'has not been applied' and the outcome 'The organization stays on its current catalog version,' which gives an agent clear context for when cancellation is appropriate. However, it does not explicitly name alternatives such as scf_rollback_catalog_reconciliation for runs that have already been applied, so it stops short of full when-not/alternative guidance.

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

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

Annotations already mark it as a write operation (readOnlyHint=false, destructiveHint=false). The description adds meaningful context beyond the annotations: it explicitly states the editor role requirement, that the status is set to completed, that a completion date is stamped, and that notes are persisted. It does not mention reversibility or idempotency, but for a simple status transition this is adequate.

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

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

A single sentence with no filler. The purpose and role are front-loaded, followed by the two behavioral effects and the notes detail. Every clause earns its place.

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

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

The tool is a simple state transition with two simple parameters and no output schema, so the description covers the essential call context: what changes, who can call it, and what inputs matter. It could mention error cases or idempotency, but nothing required for a correct call 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 100% and both parameters already have good descriptions — task_id even points to how to obtain it (scf_list_evidence_tasks) and completion_notes says 'Notes recorded on completion'. The description adds minor value by clarifying that completion notes are optional and that a completion date is stamped, but the schema already carries the semantic weight.

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

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

The description opens with a specific verb-resource pair: 'Mark an evidence collection task completed (write — editor role)', which unambiguously identifies the action and target. It further specifies what the operation does — sets status to completed, stamps the completion date, stores optional notes — making it distinct from sibling tools like create/update/delete evidence task variants.

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 context is clear: use this tool when an evidence collection task should be transitioned to completed, with optional notes. It does not explicitly name alternatives or exclusions (e.g., 'for other edits use scf_update_evidence_task'), so it misses the top tier, but the described purpose makes the usage situation obvious enough for an agent to select it 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's 'write' is consistent but adds little new information. The 'editor role' provides a permission nuance not in the annotationshola, but there is no disclosure of idempotency, duplicate-handling, or post-creation effects. With annotations covering the primary safety profile, this is a minimal but acceptable addition.

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 waste. The action is front-loaded, the parameters are implied, and the alternative tool is mentioned at the end as a pointer. Every word contributes to selecting or invoking the tool correctly.

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 flat create operation with no output schema)Skip, the description is sufficient for correct invocation: it names the resources, roles, and the relevant bulk alternative. It could mention reversibility via scf_delete_assignment or behavior on duplicate assignments, but those are not necessary for correct selection or 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 100%: each parameter (assignable_type, assignable_id, user_id, role) has a detailed description including UUID format and source (scf_list_members). The tool description merely mirrors the enum values (control, evidence, task; primary, collaborator) without adding new parameter-level details. Baseline 3 is appropriate when the schema carries the full burden.

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 ('Assign') and resource ('a user to a control, evidence item or task'), lists the allowed roles (primary or collaborator), and includes a permission note ('write — editor role'). It clearly differentiates from the bulk update sibling by naming it directly, so an agent can identify what this tool does at a glance.

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

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

It explicitly points to scf_batch_update_evidence for bulk evidence owner updates, which is an exclusion condition for this tool. It also conveys the role options that affect behavior. While it doesn't mention team assignments, the schema's user_id parameter implicitly limits to individual users, and the explicit alternative satisfies the requirement.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a write operation that is not destructive. The description adds meaningful context beyond that: it requires an editor role, each supplied finding becomes a deficiency linked to the test, and violating the result/findings rule returns a 422. It does not cover rate limits or idempotency, but the added behavioral detail is solid.

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

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

The description is three short sentences with zero waste. It front-loads the primary action ('Record a capability test as run'), then adds permission and validation constraints in order of importance. 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 write tool with 8 parameters, 7 required, nested findings, no output schema, and full schema coverage, the description is largely complete enough to invoke correctly. It covers the write nature, editor requirement, the finding-to-deficiency effect, and the validation rule. It could be stronger by routing the agent away from sibling update/add-finding tools, but nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely repeats what the schema already says ('passed needs no findings; passed_with_findings or failed need at least one' mirrors the result field description, and 'Each finding becomes a deficiency' mirrors the findings field description). It only adds the 422 status code for that rule, which is a minor incremental detail.

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

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

The description states a specific verb and resource: 'Record a capability test as run.' It also indicates the write nature and required permission ('write — editor'). However, it does not name or differentiate this tool from closely related siblings such as scf_update_capability_test or scf_add_capability_test_finding, leaving some ambiguity about when to create a new test versus add findings to an existing one.

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

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

The description gives no explicit when-to-use guidance or alternatives. It does not say to use this instead of scf_update_capability_test or scf_add_capability_test_finding, nor does it mention prerequisites like obtaining org_id via scf_list_organizations. The only operational rules are validation constraints on findings, which are not usage routing.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds context about permission ('any member') and side effects (notifying mentioned users, threading), which goes beyond annotations. However, it does not disclose details like immediate visibility, idempotency, or rate limits, leaving some gaps.

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

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

The description is a single, front-loaded sentence that states the primary action first, then efficiently adds two key usage notes (mentions and threading). Every word earns its place with no filler or redundancy.

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

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

For a simple create operation with a fully documented schema, the description covers the essential behavior: what it creates, the permission context, and the two special features. It does not mention the return value, but that is not critical for a create tool and no output schema exists. The description is sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so all parameters are documented in the schema. The description largely restates schema details (mentions notify users, parent_comment_id is a reply) without adding new meaning. It meets the baseline for full schema coverage but does not enrich parameter understanding further.

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 'Post a comment' and the specific resource types (control, evidence item, task). It also includes a permission note ('any member') and distinguishes from sibling comment tools like list, update, and delete by focusing on creation. The purpose is unambiguous.

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

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

The description does not explicitly contrast with alternatives such as scf_update_comment or scf_list_comments, but the creation intent is clear. It does provide a specific use case (replying via parent_comment_id) and mention behavior, which implies when to use it. However, it lacks explicit guidance on when not to use it or when to choose a sibling tool.

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

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

The annotations already declare readOnlyHint=false and destructiveHint=false, indicating a non-destructive write. The description adds value by explicitly stating '(write — editor role)', which clarifies the permission requirement, and it mentions the default effectiveness rating ('default partial'), which is not present in the schema annotations. No contradiction with annotations.

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

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

The description is a single, compact sentence that front-loads the primary purpose and includes the role and default behavior. There is no waste; every clause contributes meaning. It is appropriately concise for a create operation with a well-documented schema.

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 complete for a create tool with no output schema. It explains the core purpose, the role requirement, and the default effectiveness. It relies on the schema to document parameter details, which it does well. It could mention that this creates a new record, but the name and verb make that clear. Overall, nothing essential is missing for an agent to call it correctly.

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

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

Schema coverage is 100% with each parameter described, so the baseline is 3. The description adds some semantic clarity by summarizing the core fields: gap_description is 'what the gap is', compensating_control is 'what offsets it', and effectiveness_rating is 'how effective that is'. It also notes the default for effectiveness. However, it does not add new meaning for org_id, vendor_id, or risk_reduction_notes 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 clearly states the verb 'Record' and the resource 'compensating control' with the specific context 'for a vendor gap'. It also lists the key inputs (what the gap is, what offsets it, effectiveness) which makes the purpose unambiguous. However, it does not explicitly contrast with the sibling update/delete tools, so it relies on the name and context for differentiation.

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

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

The description implies the tool is for creating a new compensating control by using 'Record', and it provides context ('for a vendor gap'). It does not explicitly state when to use it versus scf_update_compensating_control or scf_delete_compensating_control, nor does it mention any exclusions or prerequisites beyond the editor role. The usage guidance is implied rather than explicit.

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

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

Annotations already signal write (readOnlyHint=false) and non-destructive, and the description goes well beyond them: it discloses the editor+ role requirement, the auto-generation of the R-ORG-N code, and the non-obvious side effect of also creating the matching risk assessment record. That side effect is exactly the kind of behavioral context an agent needs before invoking.

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

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

Two tightly packed sentences: the first delivers the verb, resource, and permission requirement; the second discloses the two side effects. No filler, no repetition of schema content, and the most decision-relevant 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 moderate-complexity create tool with full schema coverage and annotations, the description covers purpose, permission, code generation, and side effects. The only notable gap is return-value behavior (does it return the created risk object or the generated code?), which matters because there is no output schema to fill that in.

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

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

Schema coverage is 100%, so the schema fully documents all five parameters, giving a baseline of 3. The description adds marginal value by implying no code parameter is needed (the R-ORG-N code is auto-generated), but it does not elaborate on title, org_id, description, or the two category defaults beyond what the schema already states.

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

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

States a specific verb ('Create'), resource ('custom org-defined risk'), and key side effects (auto-generated R-ORG-N code, matching assessment record). The 'org-defined' qualifier plus 'Custom' in the title clearly distinguishes this from the sibling scf_create_risk, so an agent can tell them apart without opening either schema.

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

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

Implies when to use it — when an org-defined custom risk is needed rather than a standard risk — and states the editor+ role prerequisite. However, it never explicitly names the alternative (scf_create_risk) or states when not to use this tool, leaving the contrast to inference.

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

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

Annotations already declare this is a non-destructive write, so the description's job is to add mutation context beyond that. It does: it discloses the editor role requirement, the initial lifecycle state ('Starts open'), and the referential constraints (control must be in scope; risk must be assessed). It stops short of describing whether the response returns the new id or how 422s surface, but the added context is real.

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 clauses, front-loaded with the action and scope, then the constraint, then the initial state. No filler and nothing repeated from the title or schema.

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 10-parameter mutation with no output schema, the description covers the critical input constraint and lifecycle starting point. It leaves owner-name vs owner-user-id precedence and post-create behavior unstated, which is a minor gap rather than a blocking one.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description supplies a cross-field rule the schema does not encode: the required list is only org_id and title, yet scf_id or risk_code must be present in combination. That is meaningful semantics beyond the structured data.

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 ('Raise a deficiency') and adds a distinguishing qualifier ('by hand') that separates it from auto-generated deficiencies reachable through sibling tools. An agent can tell it apart from scf_update_deficiency and scf_get_deficiency without opening any schema.

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

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

Gives a concrete prerequisite ('At least one of scf_id or risk_code is required') tied to the target being an in-scope control or an assessed risk, which is the key selection condition for this tool. It does not name alternatives or exclusions, but the required context is clear.

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

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

Annotations already indicate write and non-destructive, but the description adds key behavior: freezes in-scope controls against current catalog version and requires editor role. This adds context beyond the annotations.

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

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

One concise sentence, front-loaded with purpose and includes the important scope-freezing side effect without verbosity.

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?

Complete for a creation tool: explains purpose, draft status, scope freezing, and permission. No output schema is present, but that is not required. Minor lack of return value details is acceptable.

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

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

Schema coverage is 100% with each parameter described. The description does not add meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Create) and resource (audit engagement), and distinguishes from siblings like scf_update_engagement and scf_delete_engagement by specifying draft creation and editor role. The purpose is 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?

Implies usage for creating new engagements, but does not explicitly mention alternatives or conditions for not using it. No reference to scf_update_engagement for modifications, leaving some inference required.

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

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

The description explicitly notes 'write — org member or assigned auditor', adding permission context beyond the readOnlyHint annotation (which only says false). It also discloses the constraint that the control must be in the engagement's frozen scope. It does not describe return values or error behavior, but for a write operation this is acceptable given annotations.

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

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

The description is a single sentence that efficiently conveys the core action, permission, and scope constraint. It is front-loaded with the verb 'Raise' and packs necessary context without fluff. A slightly clearer separation of the scope constraint could improve readability, but it is still concise.

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 5 required parameters and no output schema, the description covers the essential purpose, permission, and a key precondition (frozen scope). However, it does not mention what happens on success (e.g., whether a query ID is returned) or any failure conditions, which an agent might need to know for a write action. This leaves some 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?

All 5 parameters have schema descriptions (100% coverage), so the schema already documents them. The tool description adds no extra parameter-specific details beyond what the schema provides, such as the format for scf_id or the purpose of title/body. Therefore, it meets the baseline but does not exceed it.

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

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

The description clearly states the action ('Raise an auditor query') against a specific resource ('one control in the engagement's scope'), and distinguishes it from related tools like scf_respond_to_engagement_query or scf_update_engagement_query_status by focusing on the creation act. The permission note and scope constraint further sharpen its purpose.

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

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

The description implies when to use the tool (to create a new query) but does not explicitly mention alternatives or contrast with sibling tools such as scf_list_engagement_queries, scf_respond_to_engagement_query, or scf_update_engagement_query_status. It does state the prerequisite that the control must be in the frozen scope, which is helpful but not a full usage guideline.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive. The description adds value by specifying the editor+ role requirement and the behavioral effect: it starts tracking an evidence item for the organization. This gives the agent useful context beyond the annotation flags.

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

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

The description is one tight sentence with the core action and role front-loaded. The second sentence adds a useful behavioral clarification without redundancy. No filler or unnecessary detail 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?

For a create operation with no output schema, the description covers the action, the role requirement, and the intended effect. All parameter meaning is fully handled by the schema, and annotations cover the safety profile. The only minor gap is that the description does not hint at what the tool returns, but this is acceptable for a straightforward create-with-2-required-params 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 100%, so the schema fully documents all 10 parameters. The description adds only that evidence comes from a catalog ID, which is already in the evidence_id parameter description. This is the baseline 3 case where the schema carries the parameter meaning.

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 ('Create'), a specific resource ('evidence tracking record'), and a clear source ('from a catalog evidence ID'). It also distinguishes this creation action from the many list/update tools in the sibling set, especially scf_list_evidence and scf_update_evidence.

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

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

The description clearly communicates that this tool is for creating or starting to track evidence, and even notes the editor+ role requirement. However, it does not explicitly say when to use this instead of alternatives like scf_update_evidence, scf_list_evidence, or scf_list_evidence_catalog, so the guidance is implied rather than explicit.

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

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

Annotations already mark this as a non-read-only, non-destructive operation. The description adds the editor-role authorization requirement and the fact that the task is attached to a tracking record, which is useful behavioral context beyond annotations.

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

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

A single sentence that front-loads the action and resource, then packs the critical facts (role, required fields, defaults) with no fluff.

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 create tool with no output schema, the description covers core invocation facts but omits what the call returns, how to handle errors, and relationship to related evidence-task tools. The rich parameter schemas compensate partially.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats the required parameters and defaults already present in the schema, adding no new parameter-level meaning beyond highlighting them as key.

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

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

The description states a specific verb and resource ('Create a manual evidence collection task against a tracking record') and clarifies it is a write operation requiring editor role. It is clear but does not explicitly differentiate from siblings such as scf_create_evidence or scf_update_evidence_task.

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: this is the tool for manually creating an evidence task, and the editor-role note restricts who should call it. However, it provides no explicit when-to-use guidance, exclusions, or alternative tools such as scf_list_evidence_tasks or scf_update_evidence_task.

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

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

Annotations only cover write/safety flags; the description adds the required role (editor) and a concrete failure mode (409 when a material control lacks an accepted, linked risk with an approval in force). That is real behavioral context beyond structured fields, though nothing is said about side effects on linked risks 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?

Two compact sentences, front-loaded with the action and scoped by the write role and the conditional risk_code rule; no filler.

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

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

For a 7-parameter mutation tool with no output schema, the description covers purpose, authorization, and the key error condition. Return shape and the optional fields (effectiveness_rating, risk_reduction_notes) are left to the schema, which is adequate.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds qualifying semantics the schema does not state: risk_code must be accepted, linked to the control, and carry an approval in force, and is mandatory on material controls.

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

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

Specific verb+resource: 'Record a compensating control for an in-scope control'. The 'in-scope control' qualifier begins to separate it from the catalog-level sibling scf_create_compensating_control, though it never names that sibling, so an agent must infer the distinction.

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 precondition context ('write — editor', risk_code required on a material control), which is usable guidance, but never states when to use this tool instead of scf_create_compensating_control or scf_update_org_compensating_control.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the description correctly implies a mutation but not destructive. It adds the 'editor+ role' requirement and the fact that likelihood/impact populate the 5x5 matrix. This goes beyond annotations by specifying who can call it and the resulting matrix behavior. However, it doesn't warn about side effects like creating a default treatment_status or triggering notifications, but that's minor given annotations.

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

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

The description is concise, with two sentences that are front-loaded with the primary action and key constraints. It avoids redundancy. Slight deduction because it doesn't mention the optional parameters (owner, control_id, treatment_status) that an agent might need to infer, but overall it's well-structured and quickly digestible.

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

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

Given the 8 parameters (5 required) and no output schema, the description could have provided more context on how the risk assessment integrates with the risk register, such as the significance of the treatment workflow or how the matrix is used downstream. However, the schema's thorough parameter descriptions and the explicit mention of the matrix partially compensate. The description is complete enough for an agent to call correctly, but not exhaustive about side effects or return values.

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

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

Schema description coverage is 100%, so the schema already documents all parameters, including required fields and valid ranges. The description adds no additional parameter-level context beyond what the schema provides. Baseline 3 is appropriate because the schema fully covers semantics, and the description doesn't need to repeat them.

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 ('Create a new risk assessment in the risk register'), specifies the target resource, and distinguishes it from related tools like scf_create_custom_risk by focusing on the risk register's 5x5 matrix. It also notes the write nature and required role, 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 implies when to use it: when creating a new risk assessment in the risk register. However, it does not explicitly contrast with alternatives like scf_create_custom_risk or distinguish from scf_update_risk_assessment. No explicit 'when not to use' guidance is provided, leaving some ambiguity for an agent comparing siblings.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/additive nature is covered structurally. The description adds the editor+ authorization requirement, which the annotations do not convey, plus the note that systems link to capabilities and evidence. It omits idempotency/duplicate-name behavior and what is returned, keeping it short of a 5.

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

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

Two short sentences, front-loaded with the action and target before the role constraint and the linkage note. No filler or restatement of the title.

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

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

For a create tool with a fully documented 15-parameter schema and annotations covering the safety profile, the description supplies the missing auth/role context and the entity's relational role. The only real gap is post-call behavior (returned ID, duplicate handling), which is modest for an additive, non-destructive create.

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

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

Schema description coverage is 100%, so every one of the 15 parameters is already documented in the schema, including enums, defaults, and UUID sourcing hints (scf_list_organizations, scf_list_vendors, scf_list_system_catalog). The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description gives a specific verb ('Create') plus resource ('a system') and scopes it to the 'organization's infrastructure inventory', which cleanly separates it from siblings such as scf_create_vendor, scf_create_team, and scf_create_evidence. An agent can identify the target entity without opening the schema.

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

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

The parenthetical '(write — editor+ role)' communicates the permission precondition and write nature, which is genuine usage guidance. However, it names no alternative tool and states no when-not condition (e.g., use scf_update_system for existing systems), so selection guidance is only implied.

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

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

Annotations establish this is a write but not destructive operation; the description adds useful behavioral context by indicating an editor role is required, stating the one-capability-per-evidence/system constraint, and giving defaults for status and confidence. It does not discuss duplicate handling or returned values, but the annotation coverage lowers the burden.

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

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

Two sentences with no filler; the core action, permission requirement, uniqueness constraint, and defaults are all front-loaded. Every clause contributes information the agent needs.

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

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

For a create operation with fully documented parameters and clear annotations, the description covers the conceptual model and constraints sufficiently. The only notable omissions are duplicate/error behavior and explicit return information, but these are secondary when the schema and annotations already carry most of the load.

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 already documents all parameters with 100% coverage, so the baseline is 3. The description adds value by linking evidence_id and system_id to the uniqueness rule and by clarifying default behavior for capability_status and confidence_level beyond the schema entries.

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

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

The description states a clear action — declaring/creating a link between a system and one evidence type — and adds the key granularity rule (one entry per evidence_id per system). It is distinguishable from related tools like scf_update_system_capability by the create semantics, though it does not explicitly name a sibling alternative.

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

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

The intended use is implied: call this when a system should be recorded as providing an evidence type, and the uniqueness constraint hints that an existing capability should not be recreated. However, it does not explicitly state when to prefer scf_update_system_capability or what to do if the entry already exists.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description adds meaningful context: it is a write requiring admin role, and empty teams are allowed but reported through health warnings rather than rejected. This is useful non-obvious behavior beyond 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, front-loaded with the core action, and every clause earns its place. The behavioral caveat about empty teams is concise and relevant.

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 fully documented parameters and minimal annotations, the description covers the essential action, authorization, and a notable behavioral edge case. It does not mention the return value, which would be useful since there is no output schema, but this is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds only general context about business-function alignment, not additional parameter-level meaning, 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 and resource: 'Create a team aligned to a business function.' It also signals the operation type ('write — admin role') and is clearly distinguishable from sibling tools like scf_update_team, scf_list_teams, and scf_add_team_member.

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 the intended use clear: creating a new team, not updating or populating one. The 'born empty' note implies member management belongs elsewhere, though it does not explicitly name alternatives such as scf_update_team or scf_add_team_member.

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

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

The description aligns with the annotations (readOnlyHint=false, destructiveHint=true) by explicitly labeling the tool as 'write — admin role'. It goes beyond annotations by disclosing a specific side effect: is_accountable makes the team accountable and demotes any incumbent to consulted. This is exactly the kind of behavioral context that adds value.

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

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

Two sentences with no wasted words: the first front-loads the action, scope, and role, and the second covers the key behavioral nuance. Every clause earns its place, making the description easy to parse quickly.

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 five parameters, full schema coverage, annotations, and no output schema, the description covers the essential purpose, the administrative requirement, and the most important side effect. It could mention the response shape or what happens when is_accountable is false, but the absence of an output schema lowers that burden. Overall it is adequate for confident tool 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 100%, so the baseline is 3. The description adds meaningful semantic value for is_accountable by explaining the demotion of an incumbent team, which is not stated in the schema property. It also clarifies the item scope (control or evidence), reinforcing the type enum without repeating it verbatim.

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: 'Assign a team to one scoped control or evidence item', which clearly states what the tool does. The scope 'one' implicitly differentiates it from scf_batch_create_team_assignments, and the '(write — admin role)' qualifier adds context. It does not explicitly name sibling alternatives, so it falls short of a 5.

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

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

The description provides a clear operational context: it is a write operation requiring an admin role, and it is for assigning to a single scoped control or evidence item. However, it does not state when to prefer this over scf_batch_create_team_assignments or how it relates to scf_delete_team_assignment, so usage guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds two things structured data cannot: the editor+ role requirement and the side effect that the platform auto-scores risk from criticality and data handling. That side effect is important behavioral context for a create 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?

Two short sentences, front-loaded with purpose and immediately followed by the permission requirement and side effect. No filler and nothing repeated from the title or schema.

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

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

For an 11-parameter mutation with no output schema, the description covers role and scoring side effect but omits what happens on duplicate vendor names, what is returned (e.g., vendor id for follow-up calls), and any validation constraints. Adequate but with clear gaps.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics by stating that 'criticality' and data-handling inputs drive automated risk scoring — meaning those fields have downstream consequences rather than being passive metadata. It does not elaborate on other fields, which the schema already covers.

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 (vendor) plus the registry it lands in (TPRM), which distinguishes it from scf_list_vendors and scf_update_vendor. It does not explicitly name those siblings, but the create 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?

The parenthetical '(write — editor+ role)' tells the agent the required permission, which is genuine usage guidance. However, there is no guidance on when to use this versus alternatives such as scf_create_system or scf_trigger_vendor_research, and no prerequisite steps beyond the implied org_id lookup.

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

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

The description discloses the write nature ('write — editor role') which goes beyond the annotations (readOnlyHint=false, destructiveHint=false) by specifying the required role. It also states defaults for priority and status, which are additional behavioral details. No contradictions with annotations; the description adds useful context.

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

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

A single, tightly worded sentence that states the main purpose, the role requirement, the typical use case, and two defaults. No fluff, front-loaded with the primary action. Every element earns its place.

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

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

Given the 11 parameters and no output schema, the description plus the fully documented schema provide enough for correct invocation. It covers the role, defaults, and typical workflow. It does not mention what the tool returns on success, but that is not critical since no output schema exists and the annotations clarify this is a write operation. Strong overall.

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

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

Schema coverage is 100% with each parameter having a description, so the schema already carries the parameter semantics. The description only reiterates defaults that are already in the schema (e.g., 'default medium', 'default open'), adding no new parameter-specific information. Baseline 3 as schema does the heavy lifting.

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

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

The description states a specific verb ('Create'), a resource ('remediation action item'), and a target ('against a vendor'). It also adds typical provenance ('typically from an assessment finding') which distinguishes it from other create tools like scf_create_evidence_task or scf_create_risk. No ambiguity about what this tool does.

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

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

The description provides a clear typical scenario ('typically from an assessment finding') which tells an agent when to use this tool. It does not explicitly name alternatives like scf_update_vendor_action_item or scf_delete_vendor_action_item, nor state when not to use it, but the context is sufficient for the intended use. Lacks explicit exclusion but is otherwise clear.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false. The description adds that it is a write operation and defines the editor role requirement, and notes status default and expiry tracking. However, it doesn't mention whether the operation is additive/substitutive or if it affects existing vendor data, but this is minor given annotations are clear about mutation.

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

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

Two sentences, front-loaded with the main action and examples, then key behavioral notes. Efficient and no filler. Could add a bit more on usage but it's concise enough.

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?

Tool is a straightforward create with 10 params, all well-documented in schema, and no output schema required. Annotations cover mutation. This is adequate but lacks any mention of error conditions or idempotency, and the absence of output schema means the agent doesn't know what response to expect. However, given it's a simple create, it's sufficient.

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

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

Schema description coverage is 100%, and the schema already provides details for all 10 parameters (e.g., org_id source, date format). The description adds the default for status and the purpose of expiry_date (renewals), but does not go beyond schema for most fields, 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 ('Record'), resource ('vendor certification'), and purpose ('a vendor holds'), with examples ('ISO 27001 or SOC 2'). Clearly distinguishes from siblings like scf_update_vendor_certification and scf_list_vendor_certifications.

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

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

The description implies when to use it (recording a new certification) but does not explicitly state when not to use it or when to prefer scf_update_vendor_certification (e.g., for changing existing certifications). No clear exclusions or alternative routing.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false, so the description carries the burden of explaining the write nature and admin requirement. It adds critical non-obvious behavior: the plaintext HMAC signing secret is returned exactly once, must be stored immediately, and cannot be retrieved later. This is exactly the kind of behavioral disclosure an agent needs.

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

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

Two tight sentences: the first defines the action and purpose, the second delivers a one-time secret warning. No filler, no repetition of schema content, and the most important operational caveat is front and center.

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 a fully documented input schema, the description covers the key non-obvious outcome: the one-time return of the HMAC secret. It does not enumerate the full response shape, but no output schema exists and the critical handling instruction is present. Overall, an agent has enough to invoke the tool correctly and handle the result safely.

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

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

The schema has 100% parameter description coverage, so the description does not need to explain parameters. It does not add much parameter-specific meaning beyond the schema, staying at the baseline for high schema coverage. The mention of HMAC secret is about the response, not the 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?

States a specific verb and resource: 'Create a webhook endpoint' with a clear purpose ('for evidence-inbox ingestion'). The parenthetical '(write — admin role)' further clarifies the operation type. Among the many webhook-related siblings (list/get/delete/rotate), this stands out as the creation tool.

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

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

The description clearly indicates this is for creating a webhook endpoint and flags that it is a write operation requiring admin role. It does not explicitly name alternatives such as scf_list_webhooks or scf_rotate_webhook_secret, but the creation context is unmistakable and sufficient for basic tool selection.

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?

It explicitly flags the operation as destructive and states the required editor role, adding auth context beyond the destructiveHint/readOnlyHint annotations. It does not describe side effects or reversibility, but the role and destructive label are valuable.

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

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

One sentence that front-loads the action and packs the destructive nature and role requirement into a parenthetical. No filler or repetition.

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

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

With one well-documented parameter, destructiveHint annotation, and a clear purpose plus role, the description is largely sufficient. It could be more complete by naming deletion alternatives, but the schema and sibling list partially cover that.

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

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

Schema coverage is 100%: assignment_id has format, pattern, and a description pointing to scf_list_assignments. The tool description itself adds no parameter-specific detail, so the baseline 3 applies.

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

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

The description uses a specific verb ('Remove') and clarifies the resource as a user assignment, distinguishing it from sibling tools like scf_delete_team_assignment. The destructive-write label reinforces the mutation nature.

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

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

The description implies the tool is for removing a user assignment, and the editor-role note states a prerequisite, but it does not explicitly say when to prefer this over scf_delete_team_assignment or other delete tools. No exclusions or alternatives are 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?

Annotations already mark destructiveHint=true, so the description is not expected to restate destructiveness. It adds value by disclosing the soft-delete nature (thread keeps place, body withdrawn) and the authorization requirement (author only). It does not mention reversibility, but this is a minor gap given the annotation already signals destruction.

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

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

A single, front-loaded sentence that packs in the action, the permission model, and the structural consequence. Every word contributes information, with no fluff or repetition.

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

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

For a one-parameter destructive action, the description covers what, who, and the behavioral effect. It does not describe the returned payload, but since no output schema exists and simple success/failure is expected, the essential context is adequate. Error cases (e.g., non-owned comment) are implied by the author-only constraint.

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 already provides a strong description for comment_id (format and provenance from scf_list_comments). The description adds the semantic constraint that the ID must reference a comment authored by the caller, which meaningfully narrows the valid value domain beyond what the schema describes.

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 'retract' and the resource 'comment', and adds the constraint 'you authored' which immediately distinguishes it from scf_update_comment (which edits body text) and other scf_delete_* tools targeting different resources. The soft-delete clarification removes any ambiguity about the operation's effect.

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

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

It provides clear context: the tool is only for comments the caller authored, and the soft-delete behavior implies when it is appropriate (retract a comment without removing the thread). It does not explicitly name alternatives or state 'use update_comment instead if you want to edit', but the verb and author-only constraint make the usage conditions sufficiently clear.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'destructive write' is redundant. It does add one useful piece of context—the 'editor role' requirement—but it does not disclose irreversibility, cascading effects, or what happens if the record is not found. With annotations covering the core safety profile, this is adequate but not rich.

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

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

The description is a single front-loaded sentence with no filler, but the parenthetical 'destructive write' repeats what annotations already state. The 'editor role' part is valuable. Overall compact, with a minor redundancy preventing a 5.

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

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

For a simple delete operation, the definition is largely complete: the resource is clear, the destructive nature is covered by annotations, the role is stated, and all parameters are fully described in the schema. It could add a note on permanence or cascading effects, but these are minor given the annotations.

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

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

Schema description coverage is 100%, with each UUID parameter already documented including how to obtain it (e.g., 'obtain from scf_list_compensating_controls'). The description itself adds no parameter semantics, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Delete') and names an exact resource ('vendor compensating control record'), which distinguishes it from sibling delete tools like scf_delete_vendor_certification or scf_delete_vendor_action_item. The title also reinforces the resource. No ambiguity about what operation this performs.

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

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

The description gives no guidance on when to choose this tool over alternatives such as scf_update_compensating_control or scf_list_compensating_controls. The intended use is only implied by the verb 'Delete'; there are no conditions, exclusions, or mentions of related siblings.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, and the description adds meaningful behavioral context beyond that: it deletes the definition, its assessment record, every control mapping, requires editor+ role, and is irreversible. This materially helps an agent predict 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 two short, information-dense sentences. It front-loads the core action and immediately highlights the critical destructive scope, role requirement, and irreversibility 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?

For a two-parameter delete operation without an output schema, the description covers the essentials: what is deleted, the permission required, and irreversibility. Nothing necessary for an agent to safely invoke this tool is missing.

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

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

Schema description coverage is 100%, with both org_id and risk_code already described in the schema, including how to obtain them. The tool description adds no parameter-level detail, so the baseline of 3 applies.

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

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

The description uses the specific verb 'Delete' with the explicit resource 'custom risk definition' and states the cascade scope: assessment record and every control mapping. This clearly distinguishes it from partial operations like scf_remove_custom_risk_control and other delete tools among siblings.

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

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

The description conveys clear context: it is a destructive write requiring an editor+ role and is irreversible. It implies this tool is for full custom-risk deletion rather than partial mapping removal, but it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, and the description adds meaningful behavioral context: admin role requirement, 409 refusal for non-draft engagements, revocation of auditor grants, and deletion of frozen scope. This goes well beyond the annotation surface.

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

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

Three dense sentences deliver all essential facts with no filler. Destructive/role information is front-loaded, followed by refusal behavior and side effects.

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

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

For a destructive write tool with no output schema, the description covers prerequisites, failure mode, side effects, and scope of impact. The parameter schema completes the picture, making the tool fully callable by an agent.

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

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

Schema description coverage is 100%, with both params fully described including how to obtain each UUID. The description adds no additional parameter-level meaning, but none is needed because the schema already carries the burden.

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 ('delete'), a specific resource ('draft audit engagement'), and a scope boundary ('and its frozen scope'). It clearly distinguishes the tool from related siblings like scf_update_engagement and scf_create_engagement by restricting it to draft engagements.

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 says when to use it (draft engagements) and when not to (non-draft engagements), and it directs the agent to close non-draft engagements instead. This gives unambiguous selection guidance.

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

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

The description goes beyond annotations by explaining the soft-delete behavior: the record is marked deleted, drops out of listings, and the stored object is retained for audit and retention. This adds meaningful behavioral context that annotations alone do not convey.

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

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

The description is concise, with two sentences that front-load the core purpose and role, then explain the behavioral outcome. No redundant or extraneous information 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?

For a simple delete operation with three well-documented parameters and no output schema, the description covers the essential behavioral aspects and role requirement. It is complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, and the description does not add any parameter-specific semantics beyond what the schema already provides. The parameter meanings are fully captured in the schema, so no additional value is added.

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

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

The description uses a specific verb 'soft-delete' and identifies the resource 'evidence file', clearly distinguishing it from other file operations like get or list. It also states the destructive write and editor role, which 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?

It provides clear context on when to use this tool (soft-delete scenario) and the role requirement, but does not explicitly name alternatives or exclusions. The context is sufficient for an agent to select it correctly among sibling file 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?

Even though annotations already mark destructiveHint=true, the description adds valuable context: the required role, the destructive nature, and the precise scope of deletion. It explains that the catalog or custom risk definition is preserved, giving an agent a clear picture of 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?

Two sentences with no filler. The destructive warning and role requirement are front-loaded, followed by a precise clarification of what remains versus what is removed.

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

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

For a simple two-parameter destructive action with annotations covering the safety profile and schema covering parameters, the description is fully adequate. It includes the role requirement, the destructive nature, and the exact scope of the deletion.

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

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

Schema description coverage is 100%, with both org_id and risk_code already documented in the input schema. The description reinforces that the deletion is organization-scoped, but it does not need to add more because the schema already carries the parameter meaning.

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: it deletes an organization's scoring of a risk code. It also clearly distinguishes this from deleting the risk definition itself, which differentiates it from sibling tools like scf_delete_custom_risk.

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

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

The description provides clear context: this is a destructive write requiring an editor role, and it explicitly clarifies that the risk definition remains while only the org's assessment row is removed. It does not name an alternative tool explicitly, but the scope is clear enough for an agent to avoid using it for definition deletion.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description reinforces this with 'destructive write.' It adds useful context beyond annotations by specifying the admin-role requirement, which an agent needs to know before invoking the 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?

A single sentence front-loads the operation, states the target scope, and appends a compact warning about destructiveness and admin role. Every word earns its place with no redundancy.

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

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

For a simple two-parameter destructive operation, the description is complete: it names the operation, the target resource, the parent scope, and the authorization requirement. Annotations cover the destructive/read-only profile, and the schema fully documents parameter origins, so nothing essential is missing.

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

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

Schema description coverage is 100% and both parameters include provenance guidance ('obtain from scf_list_organizations' and 'from scf_list_team_assignments'). The description itself adds no parameter-level detail, but the schema already carries the full burden, 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?

The description states a specific verb ('Remove'), a clear resource ('a team's assignment'), and the target scope ('from a control or evidence item'). It goes beyond the title by clarifying exactly what object the assignment is removed from, which distinguishes it from sibling delete tools like scf_delete_assignment.

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

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

The description implies usage when a team assignment needs to be removed and adds an admin-role prerequisite. However, it does not explicitly contrast this with alternatives such as scf_delete_assignment or scf_create_team_assignment, nor does it state conditions like 'use scf_delete_assignment for non-team assignments.'

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description's 'destructive write' confirms rather than adds. It does add genuinely new context: the editor-role authorization requirement and the visibility-related cancellation alternative.

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

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

Two short sentences, front-loaded with verb and resource, with no filler. The cancellation guidance is packed into fewer than ten 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 3-parameter destructive delete with no output schema, the description plus rich schema covers the essential call path. It could specify permanence or error behavior, but the destructive annotation and role note already cover the main risk.

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

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

Schema description coverage is 100%, with each UUID given a source via list tools, so the description doesn't need to add parameter details. It adds no extra semantics 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 opens with the exact operation ('Delete a vendor action item') and reinforces scope with 'destructive write — editor role.' This is clearly distinguishable from sibling tools like scf_update_vendor_action_item or scf_create_vendor_action_item.

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

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

It explicitly warns to prefer status=cancelled when the record must remain visible, which is a clear exclusion for soft-delete scenarios. It doesn't name the sibling update tool, but the guidance is sufficient to route an agent away from hard deletion in that case.

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

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

Annotations already provide destructiveHint=true and readOnlyHint=false, so the 'destructive write' label is redundant. However, the description adds an 'editor role' permission requirement, which is not in the annotations, and it explains the softer alternative of status-based retirement. This adds meaningful context beyond the structured metadata.

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 entire description is a single, dense sentence that front-loads the action and resource, then packs in the role and the history-preservation guidance. Every clause earns its place; there is no fluff or repetition of schema details.

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

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

For a destructive delete tool with three fully documented UUID parameters, no output schema, and safety cues in annotations, the description covers the core usage: what it deletes, who can do it, and when to avoid it. It could mention cascading effects or audit-log implications, but for the stated scope this is sufficient.

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

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

Schema description coverage is 100%, with each UUID parameter documented as obtainable from a specific list tool (e.g., 'obtain from scf_list_organizations'). The description itself adds no parameter-level detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description opens with 'Delete a vendor certification record,' a specific verb and resource that unambiguously identifies the operation. It further clarifies this is a destructive write, and the sibling set includes create/update/list vendor certifications, so the tool is easily distinguished without opening the schema.

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

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

The description gives a clear when-not-to-use condition: 'Prefer status=expired or revoked when the history matters.' This tells the agent to avoid hard deletion when record history is important. It stops short of naming the alternative tool (scf_update_vendor_certification), but the guidance is explicit enough to route behavior.

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

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

Beyond annotations (destructiveHint=true), the description adds valuable behavioral detail: this is a soft-delete, the endpoint is marked inactive, future deliveries return 403, the record is retained for audit, and admin role is required. This fully informs the agent of the operational consequences.

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

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

The description is a single, tightly packed sentence that front-loads the core action and then efficiently conveys soft-delete behavior, permissions, delivery impact, and audit retention. Every clause adds useful information with no waste.

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

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

For a destructive two-parameter tool with no output schema, the description covers the essential context: what action is performed, what happens to future deliveries, why the record persists, and who can perform it. The schema fully documents parameters, so nothing critical is missing.

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

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

Schema description coverage is 100%, with both org_id and endpoint_id documented including how to obtain them. The description adds no further parameter-level meaning, so the baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description states a specific verb ('Revoke') and resource ('webhook endpoint'), and clarifies the soft-delete semantics that distinguish it from a hard delete. It clearly differentiates this from sibling webhook tools like create_webhook, get_webhook, and rotate_webhook_secret by the action of revoking.

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 the usage context clear: use this when you need to revoke a webhook endpoint so it stops receiving deliveries. It does not explicitly name alternative tools or state when not to use it, but the destructive-write and admin-role notes provide enough contextual guidance for an 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?

Annotations already mark readOnlyHint=true, and the description reinforces this with '(read — viewer role)', adding an authorization requirement beyond the annotation. It also discloses that PDF is a binary download intentionally not offered here, which helps the agent avoid expecting a binary response.

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

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

Two tight sentences with no filler. The core purpose is front-loaded, and the PDF exclusion is delivered in a clear, useful second sentence. Every clause earns its place.

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

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

For a simple read-only export tool with fully documented parameters and no nested objects, the description plus schema covers the essentials: role, format options, parameter sourcing, and the PDF limitation. It does not describe response shape in detail, but the description's 'text' framing makes the expected output sufficiently clear.

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

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

Schema description coverage is 100%, with all three parameters already well documented: format's enum and default, org_id's provenance from scf_list_organizations, and document_id's provenance from scf_list_documents. The description adds minimal parameter-level meaning beyond the schema, so 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 clearly states the action ('Export'), the resource ('a document'), and the exact output forms ('rendered markdown or HTML text'). It also draws a bright line against PDF export, which is explicitly excluded, helping an agent distinguish this tool from any PDF-related expectation.

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 context: use this tool for markdown/HTML text export, and if PDF is needed, fetch it from the web UI instead. It does not specifically route to sibling tools like scf_get_document or scf_preview_document, but the PDF exclusion and format scoping provide clear practical 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing the admin-role requirement, the async task_id handoff with a named polling tool, and the skip-existing-unless-force idempotency semantics. These are exactly the behavioral traits an agent needs before invoking a mutation.

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

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

Three tight sentences with the write/admin constraint and the async contract front-loaded; every sentence carries information 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?

With no output schema, the description compensates by stating the return value (task_id) and the polling path, plus the permission level and skip/force behavior. An agent has everything needed to call it and handle the result.

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

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

Schema description coverage is 100%, so org_id, requests, generator, domain_id, and force are already documented in the schema; the description's 'unless force is set' restates the force schema text. Baseline 3 applies since the description adds no new parameter syntax or constraints.

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 ('Queue ... generation'), the resource ('ISMS document'), and the scope ('one or more generators'), which cleanly separates it from siblings such as scf_preview_document, scf_list_documents, and scf_get_document_generation_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?

Gives clear operating context: it is a write requiring admin role, it is asynchronous (poll scf_get_document_generation_status), and existing documents are skipped unless force is set. It names the follow-up tool but does not contrast against alternatives like preview or the synchronous document tools.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds valuable behavioral detail: required role (editor+), asynchronous execution, expected HTTP status (202), and follow-up polling behavior. It also clarifies that the tool queues work rather than returning final results synchronously. No contradiction with annotations exists.

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

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

The description is compact, front-loaded with the primary action, and packs essential operational facts (role, async behavior, HTTP status, polling endpoint) into two short sentences. There is no filler or repetition of schema details.

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

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

For a two-parameter async tool with no output schema, the description gives the essential call-and-follow-up flow: invoke with org/system IDs, expect 202, poll status endpoint. It could be slightly more complete by stating whether the response includes a generation ID or other correlation token needed for the status poll, but the stated workflow is enough for an agent to proceed.

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

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

Schema coverage is 100%, and both parameters already have descriptive text explaining they are UUIDs obtainable from scf_list_organizations and scf_list_systems respectively. The tool description does not add further parameter-level meaning beyond indicating the action is for a system, so the baseline score 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 opens with a specific verb ('Queue') and resource ('AI generation of evidence-collection recipes for a system'), making the operation's intent unmistakable. It also distinguishes this from sibling retrieval tools like scf_get_system_recipes by framing it as an asynchronous generation action, not a read.

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

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

The description gives clear context: this is a write operation requiring editor+ role, is asynchronous, and returns HTTP 202. It also explicitly directs the agent to poll scf_get_recipe_generation_status afterward, which is actionable follow-up guidance. It does not mention exclusions or alternative tools for cases like retrieving already-generated recipes, but the core usage context is clear.

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

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

Annotations only declare readOnlyHint=true, so the description goes further by specifying the viewer role, 'worst first' ordering, and the behavioral difference between tier=file and tier=window. It stops short of describing response shape or pagination behavior, but the existing annotation lowers the burden.

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: two sentences with no filler. It front-loads the core purpose, ordering, and access role, then efficiently covers tier behavior.

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

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

For a read-only list tool, the description covers the essential selection context: what is listed, in what order, with what access, and how tiers differ. The schema fully documents parameters, so invocation details are available; only the absence of an output schema leaves minor uncertainty about exact response fields.

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 input schema covers 100% of parameters with useful descriptions, so the baseline is 3. The description adds a slight extra meaning for tier by noting it maps to the web app's Awaiting-confirmation queue, but it does not materially improve on the schema for limit, offset, status, or org_id.

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

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

The description uses the specific verb 'List' with a clear resource: AI verdicts awaiting a human decision. It also conveys ordering ('worst first'), access level ('read — viewer role'), and the two tier modes, making it easy to distinguish from nearby review-action 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?

The description gives clear context for when to use this tool: when retrieving AI verdicts that need human review. It also explains the tier distinction between file-level and window-level queues, but it does not explicitly state exclusions or name alternative review tools in the description itself.

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

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

Annotations already declare readOnlyHint=true, so the description's 'read' is consistent. It adds valuable behavioral context beyond the annotation: the trail is append-only, requires viewer role, and returns field-level changes with actor, source, and before/after values. No contradiction with annotations.

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

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

Two sentences with no filler. The first sentence states the core purpose and return content; the second enumerates the filter dimensions. All essential 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?

There is no output schema, but the description partially compensates by naming the returned content (field-level changes with actor, source, and before/after values). The schema fully documents all 14 parameters, and the description covers the filter dimensions. It could add ordering or pagination behavior, but nothing critical is missing for selecting and invoking the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by grouping the 14 parameters into meaningful filter categories ('entity, control, action, actor, source, date or text'), which helps an agent map intent to the right parameter without reading every schema entry.

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 ('Query'), a specific resource ('one organization's append-only audit trail'), and the exact content ('field-level changes with actor, source and before/after values'). It also states the access level ('read — viewer role'), making it clearly distinguishable from the many mutation tools in the sibling list.

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

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

The description makes the tool's context clear: it is for reading audit log entries for a single organization, with filtering by entity, control, action, actor, source, date, or text. It does not explicitly name alternatives or state when not to use it, but the purpose is specific enough that an agent can infer when this is the right tool.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds one genuinely non-obvious behavioral fact — findings are returned as deficiencies — but says nothing about pagination, error behavior, or permissions, and no output schema exists to carry that load.

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

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

A single front-loaded sentence with no filler. The phrase 'each returned as a deficiency' is slightly awkward but does earn its place by disclosing return behavior.

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

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

With no output schema, the description should describe the return shape; it only hints that findings surface as deficiencies without clarifying the deficiency payload or structure. Adequate for a simple read, but leaves the return contract thin.

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

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

Schema description coverage is 100% and both UUID parameters are fully documented in the schema with acquisition hints. The description adds no syntax or meaning beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ('Get one capability test') and its singular scope distinguishes it from scf_list_capability_tests. It does not explicitly name the sibling, but the 'one' vs 'list' distinction 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?

No guidance on when to use this versus scf_list_capability_tests or scf_update_capability_test beyond the implicit singular lookup. The schema tells the agent the IDs come from scf_list_organizations/scf_list_capability_tests, but the description itself offers no when/when-not or prerequisite context.

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

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

Annotations declare readOnlyHint=true, and the description aligns with that by describing a read operation. It adds value by specifying what data will be returned (posture, multi-axis scores, band, legacy posture_percentage), which goes beyond the annotation and helps the agent set expectations.

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

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

The description is a single, front-loaded sentence that names the operation, the resource, and the key distinguishing return fields. There is no filler or redundancy.

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

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

For a simple two-parameter read-only getter with no output schema, the description gives enough context about what the tool returns and what kind of resource it operates on. Combined with the schema's parameter documentation and the readOnly annotation, nothing essential is missing for correct selection and 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 100%, with both org_id and theme_code documented including how to obtain them from list tools. The description itself adds no new parameter semantics, so 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 uses a specific verb ('Get') and resource ('a single capability theme (KSI)') and enumerates the key returned content: posture, multi-axis scores, band, and legacy posture_percentage. This distinguishes it from sibling list tools like scf_list_capability_themes and related getters like scf_get_capability_theme_scorecard.

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 the use case clear: retrieve one specific capability theme by org_id and theme_code, with rich posture data. It doesn't explicitly name alternatives or state when not to use it, but the 'single theme' framing gives adequate context against the sibling list and scorecard tools.

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