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

Annotations only provide readOnlyHint=false and destructiveHint=false, so the description carries meaningful behavioral weight. It explicitly discloses that this is a write operation requiring an editor role, and that accepting flips both the proposal and every citation under it together. This adds genuine 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?

The description is a single, dense sentence with no filler. It front-loads the action and role, and then adds the key scoping behavior about the whole card. 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 two-parameter write tool with no output schema and no nested objects, the description is complete. It covers what the tool does, who can use it, and the scope of the effect. The schema supplies parameter provenance, 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 coverage is 100%, with both org_id and proposal_id described and including acquisition sources. The description adds no direct parameter-level detail beyond identifying the resource as a control-level CDM proposal, so it does not need to compensate for schema gaps. 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 and resource: 'Accept a control-level CDM proposal'. It adds the write action and editor role, and clarifies scope by saying one decision covers the whole card. This distinguishes it clearly from sibling tools like scf_dismiss_cdm_proposal and scf_list_cdm_proposals.

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

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

The description implies when to use it: when accepting a control-level CDM proposal. It gives useful context by noting the editor role requirement and the whole-card atomicity of the decision. It does not explicitly name alternatives or exclusions, but the action verb and sibling names make the intended use 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?

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?

Annotations already indicate this is a write operation (readOnlyHint: false), and the description aligns by saying 'write'. It adds valuable context beyond annotations: admin role is required, the target user must already exist, and the exposure is limited to the engagement's frozen scope and queries. 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 concise and front-loaded, stating the core action first and the scoping limitation second. The parenthetical '(write — admin role)' is slightly cryptic but compact and informative. There is 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 simple three-parameter grant tool with no output schema, the description covers the operation, scope, authorization requirement, and what is deliberately not exposed. An agent can correctly select and invoke this tool without needing additional inference.

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 explained and sourced from a sibling list tool. The description reinforces the engagement-scoped meaning but does not add parameter-specific details beyond the schema. Baseline 3 is appropriate because 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?

States a specific verb ('Grant'), a specific resource (user read access to an engagement), and a clear scope (engagement-scoped, exposing only that engagement's frozen scope and queries). This clearly distinguishes it from sibling auditor tools like scf_list_engagement_auditors and scf_remove_engagement_auditor, even without naming them.

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

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

The description clearly establishes when to use this tool: to grant an existing user read access to a single engagement. It implies boundaries by noting the grant is engagement-scoped and exposes nothing else in the organization. It does not explicitly name alternatives or exclusions, but the context is sufficient for 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?

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?

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

Beyond the annotations, the description discloses a meaningful side effect: creating the engagement 'freezes the in-scope controls for the named frameworks against the current catalog version'. This explains why a snapshot is preserved even after catalog deprecations, which is valuable behavioral context not visible in readOnlyHint/destructiveHint.

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

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

The description is compact and front-loaded with the core action ('Create an audit engagement'), followed by the role requirement and the key behavioral consequence. Both sentences earn their place with 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?

Given that the schema fully documents parameters and there is no output schema, the description adequately covers purpose, permission level, and important side effects. It lacks explicit guidance on return values or error conditions, but those are less critical for a straightforward create operation with strong schema coverage.

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?

Input schema provides 100% parameter coverage, so the schema documents name, org_id, frameworks, start_date, and end_date. The description only loosely references 'named frameworks' and does not add new parameter-level meaning beyond what the schema already states, which aligns with the baseline for full schema coverage.

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

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

Description clearly states a specific action and resource: 'Create an audit engagement' with the qualifier '(write — admin role)'. It also differentiates this tool from engagement-management siblings like list/get/update/delete by emphasizing the creation and scope-freezing behavior.

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 implicitly conveys when to use it: when an audit engagement needs to be created, and it notes the admin-role requirement. However, it does not explicitly contrast with related tools such as scf_update_engagement or scf_delete_engagement, nor does it mention when not to use this tool.

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

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

Annotations only indicate the tool is non-read-only and non-destructive. The description adds that this is a write operation, requires specific permissions, and depends on the control being in frozen scope. This is useful behavioral context beyond the annotations, though it does not describe the response or side effects in detail.

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 action first, then the role requirement and the frozen-scope constraint. There is no filler or redundant wording; every clause carries useful 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 mutation tool with five required parameters and no output schema, the description covers the core action, permission model, and key scope precondition, while the schema covers parameter semantics. It leaves minor gaps such as what the successful response looks like, but 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%, and each parameter already has meaningful descriptions, including format constraints and sourcing guidance like 'obtain from scf_list_organizations'. The tool description itself adds no additional parameter-level meaning, 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 uses a specific verb ('Raise') and a specific resource ('auditor query against one control in the engagement's scope'). It clearly communicates the create action and distinguishes it from sibling query tools like scf_respond_to_engagement_query and scf_update_engagement_query_status.

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

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

The description states clear preconditions: the control must be in the engagement's frozen scope, and the user must have editor role or be an assigned auditor. It does not explicitly name alternatives or exclusion cases, but the purpose and constraints give an agent enough context to decide when to use this tool.

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

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

Annotations already 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?

The annotations already indicate this is not read-only, and the description reinforces that by saying 'write'. It adds useful behavioral detail beyond the annotations: the editor+ role requirement and the fact that likelihood and impact scores populate the 5×5 risk matrix. No contradiction with annotations is present.

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

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

Two sentences, no fluff, and the primary action is front-loaded befure the behavioral detail. Every phrase earnes 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 schema covers field semantics and required parameters well, and the description explains the write nature and role requirement. However, there is no mention of what the tool returns after creation, and the distinction from scf_create_custom_risk is left unstated, which matters given the large sibling list. Reasonable but not fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning by clarifying that likelihood and impact are not just 1–5 numbers but feed directly into the 5×5 risk matrix, which is not stated in the schema. This modest additional context justifies moving 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 clearly states the action ('Create a new risk assessment') and the resource ('the risk register'), so an agent knows what the tool does. It stops short of a 5 because it does not explicitly distinguish itself from the sibling scf_create_custom_risk, which is a plausible 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?

It provides useful context by labeling the operation as 'write' and requiring an 'editor+ role', which helps an agent understand permissions. However, it gives no explicit guidance on when to choose this tool over scf_create_custom_risk or other risk-related tools, leaving the differentiation 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 signal mutation (readOnlyHint=false) and non-destructiveness (destructiveHint=false), and the description adds the specific authorization requirement 'editor+ role,' which is genuinely useful behavioral context beyond the annotations. The note that systems can be linked to capabilities and evidence also clarifies the entity's relationships, though it stops short of describing side effects or return behavior.

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

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

The description is a single, front-loaded sentence that establishe the action, the resource, the permission level, and a key relational capability without any 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?

Given the schema covers all nine parameters (including required fields, enums, and source lookups) and the description supplies the role requirement, the tool is callable with no critical gaps. The absence of an output schema means the return payload is not described, but for a simple CRUD create this is a minor omission rather than a blocker.

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 already documented (e.g., org_id says 'obtain from scf_list_organizations,' vendor_id and catalog_template_id have similar sourcing notes. The description adds no parameter-level semantics, 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 opens with a specific verb and resource: 'Create a system in the organization's infrastructure inventory,' which unambiguously distinguishes this from sibling tools such as scf_update_system, scf_list_systems, and scf_create_vendor. The parentetical '(write — editor+ role)' further clarifies the action type.

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 create verb plus the 'wite' marker give clear context for when tis tool applies, and the absence of an explicit alternative-routing note is acceptable because the sibling list contains scf_update_system for modifications and scf_list_systems for reads. It does not name those alternatives explicitly, but the usage context is unmistakeable.

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 readOnlyHint=false and destructiveHint=false. The description adds value beyond that by disclosing the editor+ role requirement and the meaningful side effect that the platform auto-scores risk based on criticality and data handling. These details help the agent anticipate post-creation behavior.

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

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

The description is a single compact sentence that front-loads the core action, then adds the permission and side-effect context. Every clause earns its place and there is no redundant or filler 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?

The description covers the core purpose, required permission, and the primary behavioral side effect, while the input schema fully documents all eight parameters. It omits explicit return-value or post-creation confirmation behavior, but given the high schema coverage and simple create semantics, this is only 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 every parameter. The description adds minimal extra meaning by connecting criticality to automatic risk scoring, but it does not elaborate on individual parameters such as status, website, or contact_email beyond what the schema provides.

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

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

The description opens with a specific verb and resource, 'Create a vendor in the TPRM registry,' and explicitly labels the operation as a write with an editor+ role. This clearly distinguishes it from list, get, update, and trigger siblings such as scf_list_vendors, scf_get_vendor, and scf_update_vendor.

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 creation context and notes the required editor+ role, implying use when a new vendor must be added. However, it does not explicitly contrast with scf_update_vendor or state that it should not be used to modify existing vendors; the alternative guidance is implied rather than stated.

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

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

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?

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 this as destructive, but the description adds valuable behavioral context: it requires an admin role, returns no content on success, deletes the frozen scope, and revokes auditor access granted through the engagement. These details go beyond the structured annotations and help the agent anticipate 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?

Three short sentences, each carrying distinct useful information: what is deleted, the danger/authorization, the return behavior, and a key side effect. 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 simple two-parameter delete operation, the description covers the required admin role, the destructive nature, the success return behavior, and the consequential revocation of auditor access. Nothing essential is missing 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%, with both parameters already clearly documented as UUIDs sourced from scf_list_organizations and scf_list_engagements. The description adds no further parameter-level detail, 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 names the exact operation ('Delete an audit engagement and its frozen scope') with a clear destructive verb and resource. It distinguishes this from the many sibling engagement tools by stating it covers both the engagement and its frozen scope, plus the revocation of auditor access.

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

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

The description clearly implies the intended use: permanently remove an audit engagement. It provides relevant context such as the admin role requirement and the side effect on auditor access, though it does not explicitly name alternatives like scf_remove_engagement_auditor for cases where only a single auditor should be removed.

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 only mark this as a non-read, non-destructive operation. The description adds meaningful behavioral detail beyond those annotations: the proposal and its citations are dismissed together, and an optional reason is stored on both. This gives the agent a clear picture of side effects without contradicting 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 one focused sentence that front-loads the purpose, role, scope, and side effects. Every clause adds useful information without redundancy or filler, making it efficient for an agent to parse.

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 three-parameter write operation with no nested objects and full schema coverage, the description covers the essential invocation context: target, role requirement, grouped dismissal behavior, and reason handling. It does not mention what the response or resulting status is, but with no output schema and a straightforward action, this is a minor gap rather than a blocking one.

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

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

Schema description coverage is 100%, so the input schema already documents org_id, proposal_id, and reason with adequate descriptions. The tool description's mention of the reason being stored on each citation mostly restates the schema's existing parameter description, so it adds little new semantic value.

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 ('Dismiss') with a specific resource ('control-level CDM proposal') and clearly indicates a write operation requiring an editor role. It also states the key side effect that proposal and citations are dismissed together, which clearly distinguishes it from sibling tools like scf_accept_cdm_proposal.

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, requires an editor role, and acts on control-level CDM proposals with their citations. It does not explicitly name alternatives like scf_accept_cdm_proposal or state when not to use it, but the role and operation context are strong enough for an agent to infer appropriate use.

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?

The readOnlyHint annotation already establishes safe read behavior, and the description adds useful context about what the audit trail contains. It does not disclose additional behavioral traits such as ordering, time range limitations, pagination defaults, or whether results are limited to a certain period, but the annotation lessens 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 a single focused sentence that front-loads the core purpose and then gives the key content detail. Every part is informative, with no repetition of the title or schema.

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

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

For a simple read-only paginated list endpoint, the description covers the returned content well: field-level changes, actor, timestamp, and before/after values. It could mention ordering or the exact set of 'related entities', but the schema and annotation provide enough for basic correct invocation.

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

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

Schema description coverage is 100%, and each parameter already has a clear description including defaults and bounds. The tool description adds no extra parameter-level meaning, but none is needed since the schema fully documents org_id, limit, and offset.

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: 'Get one organization's audit trail', and adds concrete detail about the content (field-level changes to controls, evidence, and related entities with actor/timestamp/before-after values). It is clear and informative, though it does not explicitly contrast with similar siblings like scf_get_document_history or scf_get_catalog_changelog.

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 implies when to use the tool: when retrieving an organization's audit trail. However, it gives no explicit guidance on when not to use it or how to distinguish it from related history/changelog tools, leaving the agent to infer the boundaries.

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 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 already declare readOnlyHint=true, and the description reinforces this with 'read — viewer role' and 'Get'. It adds useful behavioral context by explaining what the map contains (per-domain coverage, silent corpus areas) and the role requirement, going beyond the structured 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 compact and front-loaded with the tool's core behavior. The final sentence 'Finds documentation gaps' is largely redundant with 'where the corpus is silent,' but the overall structure is efficient and readable.

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

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

For a single-parameter read-only tool with no output schema, the description conveys the essential semantics: what the map shows, what it is used for, and the required role. It lacks explicit return-format details, but given the tool's simplicity and annotation coverage, it is adequately 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%: org_id is fully described, including where to obtain it. The tool description adds no additional parameter-level semantics, 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 clearly identifies the tool as retrieving the CDM document map, with specific semantics: per-domain coverage of ingested documents mapped to SCF domains and identification of silent areas. This distinguishes it from related sibling tools like scf_list_cdm_mappings or scf_list_cdm_documents by emphasizing coverage and gap analysis.

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 read-only operation for a viewer role that finds documentation coverage gaps. It does not explicitly name alternative tools or state when not to use it, but the purpose is specific enough that 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 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.

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

The annotations already declare readOnlyHint=true, and the description adds context by tying the operation to the authenticated caller and specifying the profile contents returned. This gives an agent useful behavioral understanding beyond the annotation alone, though it does not discuss error cases or exact response structure.

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 action, resource, and the key fields returned. Every word earns its place with no redundancy or filler.

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

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

For a zero-parameter read-only profile lookup, the description fully covers purpose, return content, and the authentication context. No output schema exists, but the enumerated fields give an agent sufficient expectation of what the tool returns.

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

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

The tool has zero parameters and 100% schema coverage, so there is no parameter burden for the description to carry. The description correctly implies the operation requires no input, which is consistent with the empty schema.

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

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

The description states a specific verb ('Get') and a specific resource ('the authenticated caller's profile'), and enumerates the returned fields: name, email, organization memberships, and per-org role. This clearly distinguishes it from sibling tools that list organizations or members.

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 identifies the exact use case: retrieving the current authenticated caller's identity and organization context. It does not explicitly contrast with sibling tools, but no sibling appears to be an alternative for this operation, so the context is 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 flag readOnlyHint=true, and the description reinforces this with 'read' and adds extra behavioral context: the required viewer role, full-document scope, and the merge-state values returned (clean, edited, conflicted, pending retirement). This goes beyond the annotation without contradicting 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?

One compact, front-loaded sentence states purpose, required role, return scope, and merge-state vocabulary with no wasted words.

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

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

For a simple two-parameter read with readOnlyHint and fully documented parameters, the description adequately conveys what the caller receives. It could be slightly more complete by pointing to the section-level sibling or mentioning access failure behavior, but nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, with both org_id and document_id documented and linked to scf_list_organizations and scf_list_documents. The description itself adds no parameter-level semantics, so it meets the baseline of 3 rather than exceeding 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 names a specific operation ('Get one generated document in full'), the resource (a single generated document), and the scope (metadata plus every section with merge state). This differentiates it from list-style siblings like scf_list_documents and section-level tools like scf_get_document_section_generated, and closes with an explicit invocation cue: 'Use this to read a document.'

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

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

It clearly establishes when to use the tool: when an agent needs to read a full generated document as a viewer. However, it does not explicitly name sibling alternatives or state when not to use it, such as pointing to scf_get_document_section_generated for a single section or scf_get_document_history for history.

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 readOnlyHint=true, and the description reinforces this with '(read — viewer role)'. It adds useful behavioral detail beyond the annotation by documenting the idle sentinel: Returns {status: 'idle'} when nothing is running, and signals that it reflects in-flight work.

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, purposeful sentences with no filler. The core purpose is front-loaded, the viewer-role note is concise, and the return behavior and usage trigger are each stated in one 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 one-parameter polling tool with no output schema, the description is largely complete: it states the idle return value, the relationship to scf_generate_documents, and when to stop polling. It does not explicitly document the non-idle status values, but 'until it completes' sufficiently implies the polling contract.

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 the single org_id parameter with a clear description and source instruction ('obtain from scf_list_organizations'). The tool description itself adds no additional parameter meaning, so a baseline of 3 is appropriate given 100% schema coverage.

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

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

The description states a specific verb ('Poll'), a specific resource ('this organization's in-flight document generation'), and clarifies it is a read operation with viewer role. It clearly distinguishes itself from the large sibling set by focusing on document generation status, and even names its companion tool scf_generate_documents.

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: call it after scf_generate_documents and keep polling until completion. It does not explicitly name alternative status tools or say when not to use it, but the 'Call after...' instruction is clear enough for correct 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 provide readOnlyHint, and the description reinforces this with 'read — viewer role' while adding meaningful behavioral detail about lifecycle transitions and version changes. It does not mention ordering or pagination, but for a simple read tool with no output schema the disclosed behavior is sufficient.

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 core purpose and then packs in the specific information the history returns. There is 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 two-parameter read-only tool with no output schema, the description is complete enough: it states the purpose, the auth role, and the response content. An agent can decide when to call it and what to expect in return.

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 both parameters with sourced descriptions (org_id from scf_list_organizations, document_id from scf_list_documents), so schema coverage is 100%. The tool description adds no additional parameter-level meaning, keeping this at the baseline 3.

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

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

The description uses a specific verb and resource ('Get a document's version and transition history') and enumerates exactly what the history covers: who moved it, when, why, and what changed per generation. This clearly distinguishes it from related tools like scf_get_document or scf_get_audit_log.

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 by marking the operation as a read for viewer-role users, so an agent knows it is a safe read-only retrieval of document history. It does not explicitly name alternative tools or 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?

Annotations already mark readOnlyHint=true, and the description adds useful context: 'read — viewer role' clarifies permission expectations, and 'ignoring any human edit' reveals a key behavioral trait. It does not contradict annotations and adds value beyond them.

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

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

Two sentences carry the purpose, read-only role, behavioral distinction, and intended usage context without fluff. The important 'ignoring any human edit' qualifier is front-loaded in the first 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 read-only get tool with well-documented parameters, the description covers what the tool does, who can use it, and when to use it. There is no output schema, but the return concept is clear from 'get the generator's own version of a section'; a bit more return-shape detail would make it fully complete.

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

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

Schema description coverage is 100%, and each parameter already has meaningful descriptions (source tool, formatting warning for slashes, optional version behavior). The tool description itself adds no parameter-level detail, 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 and resource: 'Get the generator's own version of a section', and crisply distinguishes it from human-edited content by stating 'ignoring any human edit'. This makes the tool's unique purpose clear against similar document/section siblings.

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

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

It gives an explicit use case: 'Use it to see what the platform would produce before resolving a conflict.' This tells the agent when to invoke it, though it does not explicitly name alternatives like scf_get_document or scf_resolve_document_section for contrast.

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 meaningful behavioral context: the viewer-role requirement and the specific settings that will be returned. It also implicitly conveys there are no side effects, which is consistent with the read-only hint.

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 sentence that front-loads the operation and resource, then compactly lists the three settings returned. There is no redundant or filler 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 getter with one well-documented parameter, the description covers role, operation, resource, and return contents. No output schema exists, but the list of returned settings compensates adequately, so nothing important 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 description coverage is 100%, and the org_id parameter already has a helpful description pointing to scf_list_organizations. The tool description does not need to add parameter semantics; the schema carries the full burden, so the baseline score 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') and names the exact resource ('organization's document-generation settings') with the precise fields returned. It clearly differentiates from the sibling 'scf_update_document_settings' by emphasizing the read-only 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 gives clear context by stating this is a read operation appropriate for a viewer role and enumerates what it returns. It does not explicitly name alternatives or exclusions, but the read vs. update contrast with sibling tools is evident.

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's 'read' label aligns with that. The description adds useful behavioral context by specifying role-based access restrictions (viewer or assigned auditor), which is not present in the annotations or schema. No contradiction found.

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 with no filler. The core action and resource are front-loaded, and the role restriction is compactly appended in parentheses. 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 a simple two-parameter read-only getter with no output schema, the description covers purpose, resource, and authorization context. It does not describe return shape, but the absence of an output schema lowers that burden. Minor gap: it doesn't mention sibling tools that return different engagement-related views, but the tool is simple enough that this is not a major omission.

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 text ('Organization UUID — obtain from scf_list_organizations', 'Audit engagement UUID — obtain from scf_list_engagements'). The tool description itself adds no parameter-level detail, so the schema carries the burden; 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 and resource: 'Get one audit engagement's detail.' It clearly identifies the singular engagement focus and includes role context. It doesn't explicitly differentiate from sibling tools like scf_get_engagement_scope or scf_get_engagement_presentation, but 'detail' is reasonably distinct from those.

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 access/role context ('read — viewer role, or an auditor assigned to this engagement') which implies when the tool is usable, but it does not explicitly state when to choose this over alternatives such as scf_list_engagements, scf_get_engagement_scope, or scf_get_engagement_presentation. Usage context is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'read — viewer, or assigned auditor'. It adds that the output is organized by the framework's own structure, but it does not disclose error/access-failure behavior or response shape, so it adds only moderate context 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?

The description is a single sentence that front-loads the core action and packs the distinguishing behavior into a parenthetical and colon. It is compact, though the 'read — viewer, or assigned auditor' phrase is somewhat dense and could be clearer.

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 tool with three required parameters and a fully documented schema, the description is mostly sufficient. It gives a high-level idea of the return (controls organized by framework structure), but because there is no output schema it could say more about exact return format, and it does not provide explicit routing guidance relative to sibling tools.

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 three parameters (org_id, engagement_id, framework) are already documented in the schema. The description merely echoes the framework constraint and does not add new syntax or parameter-level detail beyond what the schema provides.

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

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

The description states a specific action and resource: get the engagement's scope rendered in a chosen framework's native structure. The phrase 'as an auditor reads them' and 'one of its frameworks' helps distinguish it from generic scope/control-list siblings, though it never explicitly names an alternative.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no sibling alternatives are named. The 'natively in one of its frameworks' wording implies its niche versus similar tools like scf_get_engagement_scope or scf_list_scoped_controls, but the agent must infer this.

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 annotation readOnlyHint=true already covers the safety profile, so the description's '(read)' echo adds little. It does add useful behavioral context via the role requirement and the 'full response thread' scope, but it does not describe return shape or error behavior. This is comparable to the calibration example where annotations carry most of the safety weight.

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 verb and resource, then appends the read semantic and role constraint. There is no filler, repetition, or extraneous 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 read-only tool with three well-documented UUID parameters and no output schema, the description covers what is returned (one query plus its full response thread) and who can call it. The only notable gap is that it does not enumerate the fields inside the response thread, which is minor given the operation's simplicity.

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 each UUID parameter includes provenance ('obtain from scf_list_engagements', etc.). The description itself adds no parameter-level detail beyond saying the tool fetches one query and its thread, 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 specific verb ('Get'), a singular resource ('one auditor query'), and a distinguishing feature ('full response thread'). It is clearly differentiated from sibling query tools like scf_list_engagement_queries, scf_create_engagement_query, and scf_respond_to_engagement_query.

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 by labeling the call as a read and stating the access prerequisite ('viewer role, or an assigned auditor'). It does not explicitly name alternatives or exclusions, but the schema's 'obtain from' instructions for each UUID parameter effectively guide the agent to the right lookup flow.

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 important behavioral details: the scope is frozen, rows carry a catalog lifecycle badge, and controls deprecated since the freeze still render as marked. This gives the agent meaningful expectations about the data without contradicting 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 a single focused sentence with no filler. It front-loads the core purpose, then adds the role constraint and the key behavioral nuance about deprecated controls in a compact, efficient way.

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

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

For a two-parameter read-only tool with fully documented parameters, the description is complete enough for an agent to select and invoke it correctly. It covers what the tool does, who can call it, and an important output behavior, so no critical missing context remains.

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 covers both parameters fully, including format, required status, and provenance instructions ('obtain from scf_list_organizations' / 'scf_list_engagements'). The description adds no parameter-specific semantics, but none are needed given the high schema coverage.

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

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

The description uses a specific verb ('Get') and a precise resource ('an engagement's frozen control scope'), and clarifies that this is a read operation. The phrase 'frozen control scope' distinguishes it from related sibling tools like scf_list_scoped_controls, which would presumably return the current scope.

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 establishes the context: use this tool to retrieve the frozen control scope for an engagement, and it notes the role requirements (viewer or assigned auditor). It does not explicitly name alternative tools or state when not to use it, so it stops short of full routing guidance.

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

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

Annotations already mark this as read-only, and the description adds meaningful behavioral context by indicating that this is an async polling operation triggered by scf_trigger_evidence_assessment. It also previews the status field, which implies the result may be in progress, adding value 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?

The description is a single, focused sentence that front-loads the core purpose, then efficiently enumerates the key returned fields and the required polling relationship. 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 no output schema, the description compensates by listing the expected response contents (status, relevance score, findings, summary, audit metadata). The parameter details are fully covered by the input schema, and the async polling relationship is explicitly stated, making this sufficiently 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 input schema already explains how to obtain each parameter (e.g., 'obtain from scf_list_evidence_files'). The tool description itself adds little about parameter semantics, so it stays at the schema-covered 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 clearly states the verb and resource: 'Get the AI assessment for an evidence file', and lists the returned content (status, relevance score, structured findings, summary, audit metadata). It does not explicitly distinguish itself from closely named siblings like scf_get_evidence_assessment_summary, so it misses full sibling 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 gives explicit usage context with 'Poll after scf_trigger_evidence_assessment,' telling the agent when it is appropriate to call this tool. It does not, however, clarify when to prefer a sibling such as scf_get_evidence_assessment_summary over this one, so exclusions are not fully addressed.

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 safe read-only nature is covered. The description adds useful context about the scope (organization dashboard) and the exact metrics returned, but it does not disclose potential nuances like how statuses are categorized, whether aggregates are point-in-time or time-bounded, or how average relevance is computed. Given the annotation coverage, a middle score is appropriate.

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 core purpose and then compactly lists the returned metrics. Every word earns its place, with 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 simple read-only tool with one well-documented parameter, the description provides enough context for an agent to select and invoke it correctly. It names the data returned, the aggregation scope, and the cost unit. The only minor gap is the absence of any note about response shape or empty-result behavior, but the output schema is absent and the tool is simple enough that this is not a significant omission.

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

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

There is only one parameter, org_id, and its schema description is 100% covered, even providing a source hint ('obtain from scf_list_organizations'). The tool description adds no parameter-level meaning beyond the schema, but none is needed given the high schema coverage.

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

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

The description states a specific verb ('Get') and resource ('aggregate AI assessment metrics') and enumerates the exact returned fields (total assessed, counts by status, unassessed count, average relevance score, total cost in cents). It clearly identifies what the tool does, though it does not explicitly differentiate it from sibling summary tools like scf_get_evidence_validation_summary or scf_get_window_assessment_summary.

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 'for the organization dashboard' implies the intended use case: retrieving high-level aggregate assessment metrics for display or reporting. However, there is no explicit guidance on when to prefer this tool over sibling summary tools, nor any exclusions or alternative recommendations.

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 read-only, so the safety profile is covered. The description adds meaningful behavioral context beyond the annotation: the tool returns metadata plus a pre-signed download URL, and the URL expires in 15 minutes. This helps the agent understand response timing and re-invocation 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?

The description is two sentences with no filler. The key facts — metadata, pre-signed URL, 15-minute expiry, single artifact — are front-loaded and every sentence earns its place.

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

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

For a read-only single-file retrieval tool with 100% schema coverage and three well-documented parameters, the description conveys the essential behavior. There is no output schema, so slightly more detail about what 'metadata' includes could improve completeness, but it is adequate for correct invocation.

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

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

Schema description coverage is 100%, and each parameter already has a clear description with a source command for obtaining its value. The tool description does not add 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 states a specific action and resource: retrieving metadata and a pre-signed download URL for a single evidence file. The phrase 'single evidence file' and 'specific uploaded artifact' clearly distinguishes this from listing or aggregation siblings like scf_list_evidence_files or scf_get_evidence_maturity.

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 to use the tool to inspect or retrieve a specific uploaded artifact, which gives clear context for when it applies. It does not name alternatives or exclusion conditions, but the 'single file' wording implicitly sets it apart from list or bulk operations.

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 meaningful behavioral context by specifying the output structure and the classification scheme (green/amber/red against collection frequency). For a read-only health query, the description provides sufficient transparency about what the agent should expect.

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 action and resource, then packs the essential output semantics into a compact clause. No filler, no repetition of schema information, and 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 a one-parameter read-only tool with no output schema, the description conveys enough: what is returned (per-item freshness status and roll-up summary), the scope (organization), and the evaluation basis (collection frequency). The agent can select and call this tool confidently without additional context.

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

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

Schema coverage is 100%: org_id is fully documented with type, format, pattern, and a source hint ('obtain from scf_list_organizations'). The description only weakly reinforces the organization scope and adds no parameter-level detail beyond the schema, so the baseline score 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 states a specific action and resource ('get evidence collection health') and defines the output at a useful level of detail: per-item freshness status (green/amber/red) against collection frequency plus a roll-up summary. This clearly distinguishes it from sibling tools like maturity or validation summaries.

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 'for the organization' clarifies that this tool reports organization-level health rather than item-level detail, and the mention of freshness against collection frequency gives an agent a clear basis for choosing it. However, it does not explicitly name alternatives or exclusion conditions, so it stops short of full 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 readOnlyHint annotation already establishes that this is a safe read operation, so the description does not need to restate that. It adds some useful behavioral context by listing the returned data dimensions, but it does not disclose additional traits such as auth requirements, rate limits, pagination, or what happens when the evidence item is missing.

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 wasted words. It states the scope, defines the level scale inline, and lists the output categories compactly. This is an efficient and well-structured description.

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 carries the burden of explaining return values, and it does so by naming current level, contributing factors, upgrade potential, and tracking state. The inputs are fully documented in the schema, and the readOnlyHint covers safety. A small gap is that 'tracking state' and 'upgrade potential' are left terse, and no relationship to the similar evidence-maturity sibling is mentioned, but for a simple read tool this is largely adequate.

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

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

Schema description coverage is 100%, and both parameters already have meaningful descriptions with provenance instructions ('obtain from scf_list_organizations' and 'obtain from scf_list_evidence'). The tool description itself adds no parameter-level semantics beyond what the schema provides, so the baseline score 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 a specific verb-resource pair: 'Get one evidence item's collection maturity', which clearly identifies both the action and the exact scope. It also enumerates what the tool returns (current level on the 1-5 scale, contributing factors, upgrade potential, tracking state), making its purpose unambiguous and distinguishing it from the collection-level sibling scf_get_evidence_maturity via the 'one evidence item' qualifier.

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 implies this tool is for a single evidence item's maturity, giving the agent a straightforward context for when to select it. However, it does not explicitly name alternatives or state when not to use it, such as pointing to scf_get_evidence_maturity for overall maturity or scf_get_evidence_upgrade_recommendations for detailed upgrade paths.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful behavioral context beyond that by enumerating what the summary contains: average maturity score, automation percentage, distribution by maturity level, and improvement opportunities.

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 verb and resource, then lists the return contents in a compact list. Every element earns its place and no unnecessary words are 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 read-only summary tool with one fully documented parameter, the description covers the key return areas sufficiently. It does not describe the exact response structure, but no output schema exists and the listed fields give an agent enough context to invoke and interpret the call.

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

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

Schema description coverage is 100%, and the org_id parameter already has a clear description telling the agent to obtain it from scf_list_organizations. The tool description itself adds no additional parameter-level meaning, 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?

States a specific verb ('Get'), a clear resource ('organization's evidence maturity summary'), and the exact data included. The 'organization's' qualifier and contents distinguish it from sibling tools like scf_get_evidence_item_maturity and scf_get_evidence_validation_summary.

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 org-level use by naming the organization's summary, but it provides no explicit when-to-use guidance or exclusions. It does not tell the agent to prefer scf_get_evidence_item_maturity for item-level maturity questions.

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 annotation readOnlyHint=true already communicates that this is a safe read operation, and the description does not contradict it. The description adds meaningful behavioral detail beyond the annotation by enumerating what the tool returns: current collector, capable systems, and tailored guidance. It does not discuss error cases or permission requirements, but those are minor given 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?

A single well-structured sentence front-loads the core action and then expands with a colon-delimited list of exactly what the response covers. Every phrase adds value, with no filler or repetition of the title.

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

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

The description compensates for the absent output schema by explicitly listing the main components of the returned suggestions. For a simple two-parameter read-only tool, this is sufficient context. It does not cover edge cases such as no tracked system or invalid evidence ID, but those are not necessary for correct tool 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%, so both parameters are already documented with types and source hints like 'obtain from scf_list_organizations.' The description does not need to repeat parameter details and adds no new parameter-level semantics. Baseline 3 is appropriate because the schema 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 names a specific verb and resource: 'Get system-aware collection suggestions for one evidence item.' It distinguishes itself from the many evidence sibling tools by clarifying the output scope: tracked system, capable in-scope systems, and tailored guidance. This is not a tautology and leaves little 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 clearly implies when to use it: for a single evidence item when the agent needs collection suggestions and system comparisons. It does not explicitly name alternatives or provide when-not-to-use exclusions, but the 'one evidence item' scoping and 'system-aware' framing give strong contextual direction in a crowded tool set.

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

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

With readOnlyHint=true already declared, the safety profile is covered by annotations. The description adds useful context by specifying what the response contains (target level, effort, impact, step-by-step actions) and that it mirrors platform UI guidance, but it does not disclose response format, pagination, or any other behavioral traits. 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?

A single well-structured sentence that front-loads the verb and resource, lists the output components in a compact colon-separated form, and closes with a grounding remark about the platform UI. 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 read-only tool with two fully documented parameters and no output schema, the description compensates well by naming the expected output components. Minor gaps remain: no indication of response structure/format beyond the component list and no explicit exclusions against sibling tools, but nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, and the parameter descriptions are genuinely helpful, including source-lookup hints ('obtain from scf_list_organizations') and an example format ('E-RSK-02'). The tool description itself adds no parameter-level meaning, so the baseline of 3 applies as the schema 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 ('Get'), resource ('upgrade-path recommendations'), and scope ('one evidence item's collection'), then enumerates concrete output components (target level, effort, impact, step-by-step actions). This is clear enough for an agent to understand what the tool does, though it does not explicitly differentiate itself from the similarly named sibling scf_get_evidence_suggestions.

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

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

Usage is implied: an agent can infer this tool is for when it needs upgrade/maturity-path recommendations for a single evidence item, and the parameter descriptions hint where to obtain IDs. However, the description names no alternatives and gives no when-not-to-use guidance, leaving the distinction from scf_get_evidence_suggestions and scf_get_evidence_maturity 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?

The readOnlyHint annotation already covers the safety profile, and the description adds meaningful behavioral detail by specifying exactly what the response contains, especially valuable given no output schema exists. It does not describe edge cases such as missing validation results, but for a simple read operation this is sufficient.

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 operation, the scope, and the key returned fields without any filler. Every element earns its place and the structure makes it easy to scan.

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 getter with no output schema, the description covers the essential return values and the parameter schema handles the inputs. It could more explicitly differentiate itself from summary or maturity tools, but the per-file scope and detailed field list make it adequately complete for correct invocation.

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

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

Schema description coverage is 100%, and each parameter already has a description with guidance on where to obtain the value (e.g., 'obtain from scf_list_organizations'). The tool description adds no 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 uses a specific verb and resource ('Get the validation result for a single evidence file') and enumerates the return contents (status, completeness score, rule findings, source, timestamp). This clearly distinguishes it from siblings like scf_get_evidence_validation_summary by emphasizing per-file granularity and individual rule findings.

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 'for a single evidence file' implies this tool is for detailed, per-file validation data rather than aggregate summaries, but it never explicitly names alternatives or states when not to use it. An agent must infer the intended usage from the description and sibling names.

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 readOnlyHint annotation already covers the safety profile. The description adds useful context about the aggregated nature and output fields, but does not disclose additional behavioral traits such as potential data staleness, scoping rules, or whether the metrics are computed live. With annotations present, this level is acceptable.

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 that front-loads the main action and resource, then specifies exactly what is returned. 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 read-only aggregate tool with one well-documented parameter and no output schema, the description fully conveys the purpose and expected return contents. It is complete enough 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?

The input schema already provides 100% coverage for the single parameter, including format, pattern, and a pointer to scf_list_organizations for obtaining valid org_id values. The description does not add further parameter-level meaning, 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') and resource ('aggregate evidence validation metrics'), and clearly enumerates the returned data (counts by status, pass rate). It differentiates itself as an organization-dashboard aggregate, which distinguishes it from per-file validation tools, though it does not explicitly name sibling tools.

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

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

The phrase 'for the organization dashboard' implies the intended context, but the description offers no explicit guidance on when to use this tool versus closely related siblings like scf_get_evidence_validation, scf_get_evidence_health, or scf_get_evidence_assessment_summary. No exclusions or alternative conditions are provided.

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 readOnlyHint=true, and the description adds value by disclosing the 404 behavior when no completed assessment exists and by listing the specific return fields (RAG status, recommendation, executive summary, report_markdown/report_json). This goes beyond the structured annotation data.

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 covers purpose, returned content, and error behavior with no wasted words. It earns every word it uses.

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 present, the description compensates by naming the included report fields, and it covers the key edge case (404 when no completed assessment exists). Parameters are fully handled by the schema, and the read-only stance is covered by annotations. Nothing needed to call this tool correctly is missing.

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

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

Schema description coverage is 100%, and both org_id and vendor_id already carry actionable descriptions ('obtain from scf_list_organizations' and 'obtain from scf_list_vendors'). The tool description does not add additional parameter-level meaning, 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 states a specific verb ('Get'), a specific resource ('a vendor's latest completed AI security assessment'), and even enumerates the fields returned. It distinguishes itself from sibling tools like scf_get_vendor_assessment and scf_list_vendor_assessments by emphasizing 'latest completed'.

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: when you need the latest completed assessment, and it notes a 404 condition. However, it does not explicitly name alternatives or state when not to use it, leaving the agent to infer which sibling tool is appropriate in other scenarios.

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's 'Get' is consistent. The description adds value by specifying that only the caller's notifications are returned and by listing the included event types. However, it does not disclose response shape, sorting, or pagination behavior beyond what the schema's limit parameter implies.

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, focused sentence with the verb and resource front-loaded. The category list is compact and informative without any redundant 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 simple read-only list tool with two optional, well-documented parameters, the description provides sufficient scope and content clarity. The lack of an output schema is partially mitigated by the clear 'notifications' resource and category list, though a bit more detail on the returned fields would make it fully complete.

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

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

The input schema fully documents both parameters with defaults, ranges, and descriptions (100% schema description coverage), so the description does not need to repeat them. It adds no additional parameter-level meaning, which meets the baseline for a fully documented 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 uses a specific verb ('Get') with an explicit resource ('the caller's notifications') and enumerates the notification categories. This clearly identifies the tool's purpose and distinguishes it from the many unrelated sibling tools, none of which target notifications.

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 caller-scoped phrasing makes the usage context clear: this returns the current user's own notifications, not some workspace-wide feed. There is no sibling notification tool to differentiate against, so the lack of explicit alternatives is acceptable, though the description stops short of stating 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?

The readOnlyHint annotation already signals this is a safe read operation. The description adds value beyond the annotation by stating what data the response contains (subscription tier, member count, usage limits, settings), which helps an agent predict the tool's output.

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 action, the target resource, and the key return fields with no filler. Every part of the sentence earns its place.

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

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

For a simple one-parameter, read-only retrieval tool, the description is largely complete: it identifies the resource, the required input source, and the expected detail categories. There is no output schema, but the description compensates by listing the major output areas, though it does not detail error behavior or authorization requirements.

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 property description already explains the UUID and how to obtain it from scf_list_organizations. The main description adds no additional 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 ('one organization's detail') and then enumerates the exact data categories returned: subscription tier, member count, usage limits, and settings. This clearly distinguishes it from sibling list operations like scf_list_organizations.

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 retrieving a single organization's details rather than listing organizations. The parameter description adds workflow guidance by stating the org_id should be obtained from scf_list_organizations, though it does not explicitly name alternatives or exclusion cases.

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

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

The readOnlyHint annotation already signals a safe read operation, and the description adds useful behavioral context: the operation is an async polling call for a queued job, implying it can be called repeatedly without side effects. It doesn't disclose the full status lifecycle, but the polling guidance adds real value 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?

Two sentences with no wasted words. The purpose is stated first, and the second sentence gives a direct actionable usage instruction referencing the prerequisite tool. Every sentence earns its place.

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

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

For a simple 2-parameter read-only status tool, the description plus schema provides enough to select and invoke correctly: required IDs, their provenance, and the prerequisite generation call. Since there is no output schema, a note about possible status values would be a nice addition, but its absence does not block correct invocation.

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

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

The input schema already provides 100% parameter coverage with helpful descriptions for both org_id and system_id, including where to obtain them. The tool description adds no parameter-level information, 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 uses a specific verb ('Get the status') with a clear resource ('queued AI recipe-generation job for a system'). It distinguishes itself from the generation tool by explicitly framing this as the status-check step, so an agent can tell it apart from scf_generate_system_recipes.

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 to poll this after scf_generate_system_recipes, giving a clear triggering context and sequencing. It does not enumerate exclusions or alternative tools, but for a standalone status poll the usage guidance is sufficient.

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 readOnlyHint=true, and the description adds meaningful context beyond that: it is safe for a viewer role, it returns the computed diff, and it shows the planned action "currently recorded" rather than an applied action. This helps the agent understand the read-only and inspection-oriented nature of the call without contradicting 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?

The description is a single well-structured sentence with no filler. It front-loads the core semantics ("Get one reconciliation run in detail"), then briefly conveys the read-only nature and the key output components, making every part informative.

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 tool with readOnlyHint and full schema coverage, the description is complete. It describes the return content sufficiently even without an output schema, and the parameter descriptions cover where to obtain the required IDs. No critical gaps remain 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%, and both parameters already have helpful descriptions explaining how to obtain org_id and run_id. The description does not add parameter-level detail, but with full 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 states a specific verb and resource: "Get one reconciliation run in detail," and enumerates its contents (computed diff, deprecated entities needing a decision, planned action). This clearly distinguishes it from scf_list_reconciliation_runs (list vs. single detail) and from action-oriented siblings like scf_set_reconciliation_actions or scf_apply_catalog_reconciliation.

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 context clear: use this when you need detailed information about one reconciliation run, and the parenthetical "read — viewer role" indicates it is a read operation accessible to viewers. It does not explicitly name alternatives or exclusion cases, but the context is sufficiently clear for an agent to select it over listing or mutation 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?

The readOnlyHint annotation already signals a safe read operation, and the description aligns with that by using 'Get.' It adds useful behavioral context by listing the specific fields returned, which partially compensates for the lack of an output schema. No contradictions or hidden side effects are suggested.

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 with the verb and resource front-loaded, followed by a compact enumeration of the returned fields. There is no filler, repetition, or unnecessary explanation.

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 retrieval tool, the description plus fully documented parameters and readOnlyHint provide enough information for an agent to select and invoke the tool correctly. The field list in the description compensates for the absent output schema, and no critical usage details are 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 include meaningful descriptions, including how to obtain the IDs from scf_list_organizations and scf_list_risks. The tool description does not add parameter-level detail, but it does not need to because the schema is already self-sufficient.

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 ('one risk assessment') and enumerates the exact returned content: likelihood, inherent and residual impact scores, treatment plan, owner, and review date. This clearly distinguishes it from sibling tools like scf_list_risks and scf_get_risk_summary.

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 retrieving a single detailed risk assessment, but it does not explicitly state when to use it versus alternatives such as scf_list_risks, scf_get_risk_summary, or custom-risk getters. The schema's parameter descriptions hint at the workflow by pointing to scf_list_risks, but the description itself provides no direct usage 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 readOnlyHint annotation already establishes this as a safe read operation. The description adds useful behavioral detail by specifying the output shape (5×5) and semantic content (risk distribution across likelihood × impact), which goes beyond what the annotation alone provides. It does not describe pagination or error behavior, but those are low-risk concerns for a matrix read.

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 most important identifying information (5×5 risk matrix data) is front-loaded, followed by the distribution semantics and visualization purpose. 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 one-parameter read operation with a read-only annotation, the description is largely complete. It explains what the output represents well enough for an agent to know what to expect, even without an output schema. It could be marginally stronger by noting whether this covers standard and custom risks, but that is not a blocking 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 input schema fully documents org_id, including how to obtain it via scf_list_organizations, so the schema carries the parameter-semantics burden. The description adds no additional parameter meaning, which is acceptable given 100% schema coverage. A baseline of 3 is appropriate here.

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 identifies a specific resource (5×5 risk matrix data), a specific action (Get), and clarifies the matrix dimensions and axes (likelihood × impact). This clearly distinguishes it from sibling tools such as scf_get_risk and scf_get_risk_summary, which focus on individual risks or summarized counts rather than a visualization-ready matrix.

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 'risk distribution across likelihood × impact, ready for visualization' gives clear context for when to use this tool: when the agent needs matrix-shaped data for visual presentation. It does not explicitly name alternatives or state when not to use it, so it falls short of a full 5, but the intended use case is still clear.

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