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

The description adds permission context ('editor+ role') and a prerequisite ('control must already be scoped') beyond what the annotations provide. Since readOnlyHint=false and destructiveHint=false are consistent with a non-destructive write operation, there is no contradiction.

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 telegraphic sentences, with the core operation and role in the first and the key prerequisite in the second. 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?

The definition covers operation, permission, and prerequisite, and the schema provides complete parameter semantics. It does not describe success/error response, but for a simple additive link operation with no output schema 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?

All three parameters are fully documented in the input schema, including UUID format, examples, and source tool names. The description itself adds no extra parameter 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 states a precise action ('Link a scoped control to a custom risk') and specifies the operation type (write) and required role. The verb 'Link' and the noun phrases distinguish it from sibling list/remove operations without ambiguity.

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

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

It gives an explicit precondition: the control must already be scoped (in-scope) for the organization. It also indicates the editor+ role requirement. It does not explicitly name an alternative for unscoped controls, but the condition is clear enough for an agent to route correctly.

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

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

The 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds that this is a write operation requiring editor+ role, executes in one transaction, and caps at 500 operations. It also flags the lowercase status-value convention, which helps avoid validation errors.

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-load the core purpose and constraints: limit, transaction, role, target key, and status format. There is no filler or redundant restatement 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?

The description covers the critical behavioral context: write access, editor+ role, transaction semantics, batch limit, and scf_id targeting. Since parameter details are fully captured in the schema and there is no output schema, this is sufficient for an agent to invoke the tool correctly.

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

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

The input schema already documents every parameter with descriptions, enums, and formats (100% coverage), so the description adds little new field-level meaning. It reinforces that scf_id is the operation target and that status values must be lowercase, but those facts already appear in the schema.

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

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

States a specific action ('Batch-update'), resource ('scoped controls'), and a concrete bound ('up to 500') in one transaction. The write designation and editor+ role further distinguish it from read-only siblings like scf_list_scoped_controls.

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 'batch' framing and 'up to 500' limit clearly indicate when this tool should be used for multi-control updates, and the editor+ role requirement sets an authorization precondition. It does not explicitly name the single-update sibling scf_update_scoped_control as an alternative, but the context is clear.

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

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

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 and readOnlyHint=false, and the description reinforces this with 'destructive write' and 'editor role'. It adds valuable behavioral context beyond annotations: the precise removal condition (controls mapped only to given frameworks), the preservation of shared controls, and that 'notes and status survive'. This is strong disclosure for a destructive operation.

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

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

Two sentences with zero waste. The destructive warning and role requirement are front-loaded, followed by the precise scoping rule and the survival guarantee. 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 destructive bulk operation with no output schema, the description covers the key facts an agent needs: what gets removed, what gets kept, what survives, and the required role. It does not mention audit trail behavior (though removal_reason param hints at it) or whether the operation is reversible, but the core decision-making context is complete.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds context about the overall operation but does not add meaning beyond the schema for individual parameters. 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 from scope'), a precise resource ('every control mapped only to the given frameworks'), and the exact condition that distinguishes it from related scoping tools ('Controls shared with another in-scope framework are kept'). This clearly differentiates it from siblings like scf_scope_framework and scf_update_scoped_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?

The description clearly explains the semantics of the operation: only controls mapped exclusively to the given frameworks are removed, while shared controls are kept. It also notes the destructive nature and editor role requirement. However, it does not explicitly name alternative tools or state when to use this vs. scf_scope_framework or scf_update_scoped_control, so it falls just short of a 5.

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

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

Annotations 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 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 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 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 establish readOnlyHint=false and destructiveHint=false, so the write behavior is expected. The description adds useful context beyond annotations by naming the editor+ permission requirement and noting that systems can later be linked to capabilities and evidence. It does not contradict the annotations.

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

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

The description is two concise sentences with no filler. The first sentence front-loads the core purpose and permission requirement, and the second adds relevant linking context without unnecessary detail.

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 straightforward create operation, the description plus the fully documented schema covers the essential invocation context. The only notable gap is that the description does not state what the create call returns, especially since there is no output schema, but this is minor given the tool's simple create behavior.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters and their meanings. The description adds no new parameter-level semantics, and the baseline of 3 is appropriate when the schema carries the parameter documentation 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 the precise action ("Create"), the resource ("system"), and the context ("organization's infrastructure inventory"). It also clearly signals the write nature and editor+ role, distinguishing this from read-only and mutation siblings like scf_list_systems and scf_update_system.

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

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

The description gives clear usage context: creating a system in the org inventory and requiring editor+ permissions. It does not explicitly contrast with scf_update_system for existing systems, but the "Create" verb and inventory context make the appropriate scenario obvious. No misleading usage guidance is present.

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 declare readOnlyHint=false, so the description's 'write' is consistent and adds the role requirement (editor+). The description also discloses a non-obvious behavior: the platform auto-scores risk based on criticality and data handling, which tells the agent that risk scoring will happen as a side effect of creation.

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 first sentence states the action, resource, and permission; the second adds the key behavioral side effect. Every word 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 an 8-parameter creation tool with 100% schema coverage and no output schema, the description is adequate: it states permission, the auto-scoring behavior, and the registry context. It could mention what the response returns, but that's a minor gap for a simple create operation.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters. The description adds the note that risk auto-scores based on criticality and data handling, which gives semantic weight to criticality, but it does not need to repeat parameter details.

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 states a specific verb ('Create'), resource ('vendor in the TPRM registry'), and scope ('write — editor+ role'), and it is clearly distinct from sibling tools like scf_update_vendor or scf_create_system. The permission note further disambiguates who can invoke it.

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

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

The description's 'write — editor+ role' and the auto-scoring note give useful context about when this tool applies. It does not explicitly name alternatives or exclusions, but the sibling list makes the distinction obvious, and the schema note on org_id ('obtain from scf_list_organizations') provides a prerequisite.

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?

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds meaningful behavioral context beyond them: it is a write requiring admin role, it is asynchronous (returns a task_id), it skips existing documents, and force overrides that skip. No annotation contradiction — 'write' aligns with readOnlyHint=false and the skip behavior is consistent with 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 short sentences, each carrying distinct essential information: operation+role, async contract+follow-up tool, and skip/force edge case. The verb and resource are front-loaded, and there is zero 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 an async write tool with no output schema, it discloses the essential contract: what is queued, the admin role requirement, the returned task_id, the polling endpoint, and idempotency behavior. Remaining details like batch failure semantics are reasonably delegated to the referenced status tool and the well-documented schema.

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

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

Schema description coverage is 100%, and the schema already provides strong parameter guidance (org_id sourced from scf_list_organizations, generator from scf_list_document_generators, domain_id from scf_list_document_domains, requests bounded 1-40). The description restates the force behavior already documented in the schema, so it adds no new parameter-level meaning 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?

States a specific verb+resource ('Queue ISMS document generation') with explicit scope ('one or more generators') and clearly differentiates itself from siblings by specifying it returns a task_id to poll rather than a document, separating it from document-read/export tools like scf_get_document and scf_export_document.

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

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

Names the intended follow-up explicitly ('poll scf_get_document_generation_status') and gives a usage rule for the force flag ('Existing documents are skipped unless force is set'). It provides clear context but does not explicitly state when-not-to-use versus alternatives like scf_export_document or scf_generate_system_recipes.

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 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.

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

Annotations already declare readOnlyHint=true, so the description does not need to restate read-only safety. The description adds transparency about what the read returns (metrics and confidence tiers) but does not disclose details like output grouping, potential empty results, or whether org_id must have associated capability themes. It is adequate, 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?

Two sentences with no filler: the first enumerates the returned metrics, and the second gives the intended use case. All content earns its place and the key 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 single-parameter, read-only tool, the description covers what the call returns and when to use it. There is no output schema, so the metric list is helpful, though it could more explicitly state that results are grouped by capability theme. Overall, an agent has enough 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%, with org_id already documented as an Organization UUID obtainable from scf_list_organizations. The tool description does not add further parameter-level detail, so the baseline of 3 applies. The phrase 'per-theme' clarifies output granularity but not the input parameter.

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

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

Description uses a specific verb ('Get') and resource ('per-theme evidence metrics') and lists concrete output content: controls with evidence, file counts by assessment status, average relevance score, and derived confidence levels. This is clearly differentiated from siblings like scf_get_evidence_maturity and scf_get_capability_theme_scorecard by the specific metric set.

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 sentence 'Use for KSI evidence dashboards' provides a clear intended use context. It does not explicitly name alternative tools or exclusion criteria among the many evidence-related siblings, but the dashboard use case is sufficient to guide selection in most situations.

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?

readOnlyHint=true already covers the safety profile, so the description need not restate it. It adds useful detail about the returned KSI dimensions and composite bands, though it does not mention pagination, ordering, or behavior for organizations with no capability themes.

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 focused sentences with zero filler. The main action and scope are front-loaded, and the metric list is compact and information-dense.

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

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

For a read-only, single-parameter report, the description is largely complete: it names the five returned axes and the composite score. It does not describe response shape or pagination, but no output schema exists and the endpoint is simple enough that 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?

The single org_id parameter is already fully documented in the schema, including its source via scf_list_organizations. The description adds no parameter-specific semantics beyond the report's scope, 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 action ('Get') and concrete resource ('multi-axis KSI scorecard for every capability theme'), and enumerates the exact metrics returned: Implementation Coverage, Maturity, Evidence Coverage, Evidence Quality, and composite KSI Posture Score bands. It is clearly not a single-theme or evidence-only endpoint, though it does not explicitly call out a sibling for contrast.

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

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

No guidance on when to select this over nearby siblings such as scf_get_capability_theme_evidence_posture or scf_get_control_assessment_composite. The scope 'every capability theme' implies an aggregate view, but alternatives and conditions are left unstated.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'read — viewer role,' adding the required permission level. It also discloses the ordering ('newest first'), scope ('this organization's'), and the nature of the returned data ('what changed across reconciliations... what did we decide?'), which goes beyond the annotation.

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

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

A single, information-dense sentence covers purpose, read-only nature, role requirement, scope, ordering, and the core question the tool answers. 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?

With only three parameters, all fully described in the schema, and a read-only annotation, the description supplies the essential behavioral context: what the changelog contains, how it is ordered, and who can access it. Nothing critical for an agent to invoke the tool correctly is missing, even without an output schema.

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

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

Schema description coverage is 100%, so the schema already fully documents org_id, limit, and offset. The description adds only indirect context through 'this organization's,' which maps to org_id, but provides no additional parameter-level detail beyond what the schema already gives.

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: 'Get this organization's catalog changelog.' It clearly defines the scope (organization-level), the content (what changed across reconciliations), and the ordering (newest first). It even frames the practical question it answers, distinguishing it from audit logs or reconciliation-run 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 provides clear context for when to use the tool: to retrieve catalog change history across reconciliations, focused on control changes and decisions. It does not explicitly name alternatives or exclusions, but the phrasing 'this organization's catalog changelog' and 'across reconciliations' makes the intended use unambiguous among the many sibling tools.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces the read-only nature. It adds useful behavioral context beyond annotations: this is the reference definition, not an org tracking record, and it returns mapped controls. 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 tightly written sentences with no filler. The core purpose is stated first, and the distinguishing clarification and sibling pointer are delivered efficiently in the second sentence.

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

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

For a simple single-parameter read operation, the description plus schema are sufficient. It states what is returned (one catalog evidence entry with mapped controls), how to obtain the ID, and how this differs from scf_get_evidence. No output schema exists, but the return expectation is adequately described.

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 already fully documents evidence_id. The description adds no new parameter-level meaning, though it does clarify the overall return includes mapped controls. Baseline 3 is appropriate because the schema handles parameter documentation.

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 ('Get') and resource ('one catalog evidence entry') plus the additional behavior of returning mapped controls. It explicitly distinguishes itself from scf_get_evidence by clarifying this is the reference definition, not an organization's tracking record.

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 direct usage context: 'read, no org' tells the agent this is a read-only catalog lookup independent of organization. It also names the alternative tool, scf_get_evidence, for the org-specific case, making the selection criteria 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 supply readOnlyHint=true, and the description adds value by stating the 'viewer role' requirement and what state the tool reports (due or in flight). These go beyond the annotation while remaining consistent with it.

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

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

The description is a single well-structured sentence that front-loads the action, then provides the read-only qualifier, output contents, and the 'Start here' workflow nudge with no filler. Every phrase 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?

With no output schema, the description compensates by naming the three result components: catalog version, platform version, and reconciliation due/in-flight state. For a one-parameter read-only status endpoint, this is complete: the agent knows input source, required permission, output semantics, and where this tool fits in the workflow.

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

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

The input schema already covers org_id completely with a UUID format, required flag, and guidance to obtain it from scf_list_organizations. The description does not add parameter-level meaning beyond 'this organization's', so baseline 3 is warranted.

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 ('Get this organization's catalog position') and lists exactly what is returned: catalog version, platform's current version, and reconciliation due/in-flight state. The '(read — viewer role)' qualifier and the 'Start here' cue distinguish this top-level status check from reconciliation-run-specific 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?

'Start here' explicitly frames this tool as the entry point for catalog reconciliation status, and the viewer-role/read qualifier tells the agent it can be used safely in read-only contexts. It does not enumerate alternatives or exclusions, but the workflow cue is clear and appropriate for this simple status 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 only mark readOnlyHint; the description adds operational context: it is a cheap probe, requires only viewer role, and returns two values (timestamp and row count). It also discloses the intended polling pattern, which annotations cannot convey. 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 dense sentences front-load the purpose, cost, and auth level before giving the polling instruction. Every clause earns its place; 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 one-parameter read-only probe with no output schema, the description covers purpose, return values, role requirement, and the exact usage pattern. The only mild ambiguity is 'the pair you last saw,' but the preceding clause identifies the pair as timestamp and row count.

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 org_id schema already explains it is an Organization UUID from scf_list_organizations. The tool description only restates 'for one organization' and adds no parameter-level detail 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?

Description opens with 'Cheap has-anything-changed probe' and specifies it returns 'newest audit timestamp and row count for one organization', giving a concrete verb, resource, and output. The 'poll this before re-pulling the audit log' line distinguishes it from the audit-log fetching sibling without ambiguity.

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

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

Explicitly instructs when to call: 'poll this before re-pulling the audit log' and how to use results: 'Compare with the pair you last saw.' It also implies the alternative (full audit log fetch) and frames this as the cheap pre-check, so an agent knows when to choose it.

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

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

Annotations already declare readOnlyHint=true, and the description adds value by specifying exactly what the read returns: description, mapped frameworks, assessment objectives, and linked evidence items. This gives the agent a concrete picture of the operation without contradicting the read-only annotation.

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

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

The description is a single, information-dense sentence with no filler. The primary action and target are front-loaded, followed by a concise list of returned 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 simple single-parameter read tool with no output schema, the description covers the input format via the schema and the key return categories in prose. It is complete enough for an agent to select and invoke the tool correctly, though exact output structure is not specified.

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 the single parameter scf_id is already fully described with a format and examples. The description adds no additional parameter semantics beyond restating that the lookup is 'by ID', 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 ('Get'), a concrete resource ('a single SCF control by ID'), and clarifies the catalog scope ('from the reference catalog'). This clearly distinguishes it from list-style siblings like scf_list_controls and from scf_get_scoped_control, which operates on scoped controls.

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

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

The phrase 'from the reference catalog' implies this is the tool for reference-catalog controls rather than scoped controls, providing some contextual guidance. However, it does not explicitly state when to choose this over scf_list_controls, scf_get_scoped_control, or scf_list_assessment_objectives, nor does it provide exclusions.

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

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

Beyond the readOnlyHint annotation, the description discloses the 404-when-row-not-yet-computed error behavior, the async nature of composite generation, and the exact response composition (five field groups). With no output schema present, this behavioral disclosure carries the return-format burden and notably tells the agent a 404 is a legitimate 'not ready yet' state rather than a malformed request.

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 first front-loads the verb, resource, and available return fields; the second delivers the critical error/timing caveat. The field enumeration earns its place because there is no output schema to compensate for missing return-value documentation.

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 read-only tool with fully documented parameters and a readOnlyHint annotation, the description covers operation, return content, and error behavior — a solidly complete picture. The only gap is the absence of an explicit pointer to scf_list_control_assessment_composites for browsing, and minor ambiguity about status-band value ranges, which keeps it shy of a 5.

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

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

Schema description coverage is 100%: org_id already includes cross-tool sourcing guidance ('obtain from scf_list_organizations') and scf_id already gives the DOMAIN-NN format with examples. The tool description adds no parameter-level detail beyond loosely echoing scf_id with 'one SCF control,' so the schema does the heavy lifting — 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 and resource ('Get the rolled-up assessment composite for one SCF control') and enumerates the returned content (composite score, status band, included/missing evidence IDs, mandatory gaps, per-window detail). 'One SCF control' and 'rolled-up' clearly distinguish it from the plural sibling scf_list_control_assessment_composites and from window/evidence-level 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 singular scope ('for one SCF control') gives clear context that this is the single-entity getter versus scf_list_control_assessment_composites, and the async/404 note signals when it is appropriate to call vs wait. However, it never explicitly names an alternative or states when not to use it — the routing 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.