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

The description is consistent with readOnlyHint=true and adds scope by listing the assessment types covered. However, it does not add behavioral context such as role requirements, async composite availability, or pagination behavior beyond what annotations and schema already provide.

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

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

The description is a single front-loaded sentence with no wasted wording, and it efficiently lists the supported assessment categories. The ending "Pick with method" is terse but functional, though the sentence could better structure the method-selection instruction.

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

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

For a 9-method, 13-parameter polymorphic read tool, the description is minimal and relies heavily on the detailed method enum in the schema. It gives enough orientation to select the tool, but it does not explain return shapes or method-specific behavior at the top level.

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 parameter meanings are already fully documented in the input schema. The description adds only the high-level instruction to select behavior with method, which is useful but already reflected 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?

The description states a specific read operation for AI evidence assessments and enumerates the main assessment categories: file verdict, file summary, review queues, window assessments, and control composites. It is clearly distinct from a write tool, though it does not explicitly name sibling alternatives.

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 "Pick with method" gives essential dispatch guidance for a polymorphic tool, but it does not explain when to use this tool versus related read tools or when each method is appropriate. The detailed method guidance lives in the schema rather than in the description.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false; the description adds the editor+ role requirement and the async/queued nature, which the annotations do not cover. It omits the more consequential behaviors — that rejecting a window raises deficiencies, that verdict decisions are version-bound, that bulk calls cap at 50/25 — leaving those to the schema. Notably, 'rejected raises a deficiency per in-scope control' is a side effect sitting under destructiveHint=false, but that disclosure exists in the schema rather than contradicting the description text.

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

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

A single front-loaded sentence that compresses eight dispatch methods into parallel clauses ('assess a file or many, assess a window or many'), with no wasted words and the permission/async qualifier placed high.

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 15-parameter polymorphic dispatcher with no output schema, the description is thin: it never states that exactly one method must be chosen and that required parameters vary by method, nor what each method returns (counts, skipped_detail, poll targets). The schema carries most of that load, so the definition is workable, but the top-level description does not fully prepare an agent for method dispatch.

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 enum descriptions already tag each parameter with its applicable method ('Used by: ...'), including prerequisites and 422 conditions. The description contributes no parameter semantics beyond that, so the baseline 3 applies.

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

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

The description uses a specific verb and resource ('Run and review AI evidence assessments') and enumerates the eight concrete operations (assess file/window, bulk, refresh stale, confirm/override verdicts, set acceptance). The '(write)' title and the tool name separate it from scf_assessment_read, though the description never names that read sibling as the alternative, so the differentiation is inferred rather than stated.

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

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

'(editor+, async)' tells the agent the required role and that operations are queued rather than synchronous, which is real selection context. However, no when-to-use guidance appears in the description itself — the per-method routing (which method to pick, what to poll afterward, when to skip) lives entirely in the schema's enum descriptions, so the description alone only implies 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?

readOnlyHint=true already establishes the safety profile, so the description only needs to add depth. It hints at return content for each mode (multi-axis scorecard, per-theme evidence posture) but says nothing about pagination behavior, cost of the scorecard mode, or how bands/confidence values are derived. Adequate but thin given annotations already cover safety.

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

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

A single front-loaded sentence lists the five modes, followed by a short imperative on how to choose among them. Nearly every clause earns its place, though 'Pick with method' is terse to the point of being cryptic for a first-time reader.

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, a five-mode read tool needs to convey what comes back per mode; the description does so only at a high level and omits band semantics, evidence confidence meaning, and the fact that org_id originates from scf_list_organizations. It is passable because the method enum compensates, but the description alone is not self-sufficient.

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

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

Schema description coverage is 100% and the method enum already spells out each mode's output in detail, so the schema does the heavy lifting. The description only reinforces that method drives behavior; it adds no meaning about limit, offset, scope_status, or theme_code beyond what the schema states.

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

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

The description uses a specific verb (Read) plus resource (capability themes/KSIs) and enumerates the five result shapes: theme list, single theme, scorecard, evidence posture, and mapped controls. That distinguishes it well from sibling read tools such as scf_control_read, though it does not name any sibling outright and leaves the 'KSI' acronym unexplained.

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?

'Pick with method' is the only routing guidance, telling the agent that mode selection is done via the method parameter. It does not say when to prefer this tool over scf_control_read or scf_assessment_read, nor does it warn which modes require theme_code, leaving that to the schema's per-value 'Used by' notes.

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 declares the safety profile, so the description's main contribution is the catalog-versus-org scoping note and the hint that a single-control read returns objectives and evidence. It does not disclose pagination behavior, result caps, or deprecated-row handling beyond what the schema enumerates. Useful but not rich behavioral context.

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

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

A single compact sentence with the resource and scope front-loaded and the operation list following. Every clause maps to real functionality. It is dense list-style prose but has no filler sentences.

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

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

For an 11-parameter, eight-method multiplexed tool with no output schema, the description is thin; most of the actionable detail lives in the method enum descriptions rather than the top-level description. It is adequate because the schema compensates, but the description alone would not tell an agent enough about method-specific behavior.

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

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

Schema description coverage is 100%, including per-method descriptions and per-parameter 'Used by' mappings, so the schema carries parameter semantics. The description adds the dispatch pattern ('Pick with method') but no parameter format or constraint detail beyond the schema. 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 names a specific verb and resource ('Read the SCF reference catalog') and enumerates the object types available (controls, single control with objectives/evidence, domains, frameworks, assessment objectives, evidence definitions). The '(no org)' qualifier is a meaningful scope distinction against the org-scoped sibling tools, though no sibling is named explicitly and the agent must infer that scf_control_read / scf_evidence_read are the org-scoped counterparts.

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?

'Pick with method' tells the agent how the operation is selected but gives no when-to-use versus when-not guidance, and no explicit routing to the sibling read tools for org-scoped data. The '(no org)' hint implies the alternative exists without stating it, leaving usage selection to inference from the name and the method enum.

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 'Read' is consistent with that. The description flags that preview_framework_change is non-mutating by calling it a preview, but omits the important caveats (permission level for the preview/framework_scope modes, pagination semantics for list) that live only in the schema.

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

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

A single front-loaded sentence with the resource first and the modes enumerated in the same order as the method enum, followed by the routing hint. Nothing is redundant or buried.

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 20-parameter, five-mode multiplexed tool with no output schema, the description gives enough to understand the surface and select a mode, and the method enum carries the detailed per-mode behavior. It stops short of describing what list/stats return in any useful shape, but the schema shoulder most of that burden.

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 is unusually explicit, including per-parameter 'Used by:' tags, so the baseline would be 3. The description adds a small amount by pairing each mode name with the data it returns, but contributes no syntax or constraints beyond what the 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+resource ('Read the organization's control scope') and enumerates all five modes the method parameter selects (list, get, stats, framework_scope, preview). An agent can tell this is the read-side counterpart to scf_control_write, though it never names that sibling explicitly.

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

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

'Pick with method' is the only routing instruction, and it defers entirely to the method enum's schema text for when to choose each mode. There is no when-not guidance and no mention of alternatives outside the tool; usage 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 already declare readOnlyHint=false and destructiveHint=true, so the write/destructive profile is covered. The description adds the authorization dimension (editor+ baseline, admin for some methods) which annotations do not carry. It does not itself disclose irreversibility, the audit-trail recording, or the 403/404/409 failure semantics — those live only in the schema text.

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

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

A single front-loaded sentence with the resource and permission level up front and the operation list after. It is dense but every clause maps to real capability; the only weakness is that the long comma-run of overrides is slightly harder to scan than a short bulleted mapping would be.

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 ten-method polymorphic mutation tool, the description covers purpose and role requirements but omits the single most important structural fact — that the tool is dispatched by a required `method` parameter. Given the very rich schema and the destructive annotation, the remaining gaps are tolerable, but an agent must open the schema to call it at all.

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% across 24 parameters, with per-parameter "Used by: <method>" tags that fully document the polymorphism, so the baseline of 3 applies. The description only restates the operation families and the role floor; it adds no meaning beyond the schema's own method/parameter mapping.

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 ("Change the organization's control scope") and then enumerates the concrete operations: update/batch-update controls, scope/unscope a framework, and the scope, basis, maturity, materiality and procedure overrides. An agent can map the ten schema methods onto these phrases. It stops short of naming when this is preferred over the sibling read tools, but the write/read naming pair makes that largely self-evident.

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?

Adds permission gating ("editor+; some methods admin"), which is real usage context, but gives no criterion for choosing among the ten methods or for preferring this over scf_update_org_settings / scf_list_scoped_controls. The description never mentions the required `method` discriminator, so an agent reading only prose would not know operations are selected by a parameter.

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 the safety profile, so the description only needs to add scoping context. It confirms this read covers org-defined risks and their linked controls, but adds nothing about permissions, whether custom risks are mutable through this path, or output shape beyond what the schema's enum text already supplies.

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, zero waste, with the resource and both modes front-loaded before the method hint. Nothing is repeated or padded.

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

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

For a low-complexity read tool with a fully documented three-parameter schema and no output schema, the definition covers what is needed to call it. The one soft spot is that the conditional dependency of risk_code on the controls method is only implied by 'linked to one' and carried by the schema, not stated in the description.

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

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

Schema description coverage is 100% and the method enum text is unusually rich (R-ORG-N codes, catalog_control_ids, links, scoped_controls with implementation status), so the baseline is 3. The description contributes 'list them, or list the controls linked to one', which paraphrases the enum semantics in task-oriented language and slightly clarifies intent 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?

States a specific verb (read) and resource (organization-defined custom risks) and enumerates both modes: listing risks or listing controls linked to one. It does not differentiate itself from scf_risk_read (static catalog risks) or scf_custom_risk_write, so an agent must infer that boundary from the name prefix alone.

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

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

'Pick with method' tells the agent that the method parameter selects the operation, and the two modes are named. However, there is no explicit when-to-use guidance against alternatives such as scf_risk_read or scf_custom_risk_write, nor a statement that the controls mode requires an existing risk_code.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description's "destructive" adds little; the real added value is the editor+ role gate. The deeper consequences (delete removes the assessment record and all control mappings; link changes clear an accepted exception's approval) live only in the method's schema entry, not the description.

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

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

A single compact sentence that front-loads the resource, the role requirement, and the operation groupings before the routing hint. Minor density cost from the parenthetical "(destructive)" sitting mid-clause, but nothing is wasted.

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

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

For a 9-parameter, six-method polymorphic write tool it correctly signals the method-dispatch pattern and the role gate, and the per-method parameter mapping is fully covered by the schema, so no output schema is needed. The only shortfall is the absence of any guidance on precedence between scf_custom_risk_write and scf_custom_risk_read.

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 every parameter is documented per-method with format hints and provenance (e.g., obtain from scf_list_custom_risks), so the schema does the heavy lifting. The description only says to choose via method and contributes no additional field semantics, which is the baseline 3 case.

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 resource (custom risks) and enumerates the six concrete operations grouped into risk-level (create/update/delete) and control-link-level (add/update/remove) actions, which is well beyond restating the name. It stops short of naming the sibling read tool (scf_custom_risk_read) as the non-destructive alternative, so the write/read split is only inferable from the name.

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?

"Pick with method" gives a minimal dispatch cue and the "(editor+)" tag flags a permission prerequisite, but there is no explicit when-to-use vs. when-not guidance and no pointer to the read counterpart for fetching risks. An agent must open the schema to learn which method suits its intent.

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 establishes the safe-read profile, and the description is consistent with it, adding that results include download URLs and validation outcomes. It does not mention the 15-minute URL expiry, scope breadth, or any rate/consumption caveats, all of which sit only in the schema.

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

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

A single front-loaded sentence that enumerates the four modes and closes with the selection instruction — no filler and nothing buried.

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 dispatcher with a fully documented schema and no output schema, the description is nearly complete for selection purposes. The only gap is that the mapping between modes and the optional file_id/evidence_id arguments is left entirely to the schema.

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

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

Schema coverage is 100%, so the baseline of 3 applies. The description names the method as the discriminator but adds no format, dependency, or required-parameter-pairing detail 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?

Names a specific verb (read) and resource (an evidence item's files) and enumerates the four concrete result shapes the caller can obtain. It is clearly distinguishable from scf_evidence_file_write by naming the read modes, though it does not explicitly contrast itself with scf_evidence_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?

"Pick with method" signals that the enum is the selector, but the description itself gives no when-to-use criteria across the four modes or against the sibling evidence tools. The real guidance lives in the method enum's schema descriptions rather than in the description text.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description's '(destructive)' label mostly restates structured data. It does add the editor+ authorization requirement, which is genuine added context, but it says nothing about what review/revalidate return or about side effects like deficiencies being raised (that detail lives only in the schema).

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

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

A single front-loaded sentence that lists the operations and ends with the dispatch instruction. No filler, no restatement of the title, and the destructive element is called out inline.

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

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

For a 6-parameter, 3-mode write tool with no output schema, the description covers all modes and the required role. It does not explain return values or the mode-specific edge cases (e.g. the 410 per-window review case), but those are documented in the schema, so nothing critical is missing at the description layer.

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

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

Schema description coverage is 100%, so every parameter including the method enum is already fully documented in structured data. The description's only contribution is signaling that 'method' is the discriminator, which is minimal added meaning over the enum descriptions.

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 concrete verb and resource ('Act on an uploaded evidence file') and enumerates the three actions it covers: approve/reject/request revision, re-run validation, and soft-delete. That is enough to separate it from the read sibling scf_evidence_file_read, though it never names that sibling explicitly.

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

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

Usage is only implied: the agent is told to 'Pick with method' and given the list of operations, but there is no explicit when-to-use/when-not guidance or any routing statement versus scf_evidence_task_write or scf_evidence_write. The role hint '(editor+)' gives a precondition but not a selection rule.

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 safety profile is covered and the description's 'Read' prefix is consistent with it. But beyond that the description adds no behavioral context of its own: no mention of the viewer-role requirement on `upcoming`/`frequency_health`, the 90-day observation window, the 404 for untracked evidence, or the 90-day cap on `days` — all of which live only in the schema.

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

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

It is a single front-loaded sentence with no filler, which is structurally sound. However, most of its content is a compressed restatement of the method enum names already fully documented in the schema, and the telegraphic list style ('gaps, health, upcoming, frequency health, maturity and upgrade guidance, suggestions') sacrifices parseability without adding new 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 nine-parameter, eleven-mode endpoint with no output schema, the description gives only mode labels and never characterizes what any mode returns (record fields, coverage percentage, green/amber/red statuses, maturity levels). The rich schema compensates for parameter completeness, but the absence of return-shape signal leaves a real gap for a multi-mode read 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 already documents all nine parameters, including per-method applicability ('Used by: list'), enum meanings, and where to obtain IDs. The description adds no parameter meaning beyond that, 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+resource ('Read evidence tracking') and enumerates the operation families the single multiplexed endpoint covers (list, get, requiring controls, gaps, health, upcoming, frequency health, maturity, upgrade guidance, suggestions). It is distinguishable from the write sibling and from scf_evidence_file_read by naming the tracking records themselves, though the compressed phrasing ('one record with its in-scope requiring controls, requiring controls alone') makes several modes hard to separate at a glance.

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

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

Listing the modes implies which value to pass to `method`, but the description never says when to prefer one mode over another, nor when to use a sibling such as scf_get_evidence_requiring_controls instead of the `requiring_controls` method. That routing guidance exists only in the schema's method descriptions, so usage selection 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 already declare this is a non-read-only, non-destructive write tool, and the description corroborates that with the editor+ requirement. Beyond that it adds little: it doesn't say whether updates are partial, whether completion is reversible, or what happens on invalid state transitions – most of that lives only in the method enum's schema text.

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 the resource and the three operations front-loaded, followed by the dispatch instruction. No filler, though it is arguably too terse given 12 parameters.

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

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

For a polymorphic 12-parameter write tool, the schema carries the heavy lifting: per-method required fields, defaults, and UUID sourcing hints are all documented, and there is no output schema to explain. The description covers the operation set and the role gate adequately, leaving only cross-tool routing implicit.

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 method enum text already spells out per-method requirements, defaults, and field applicability. The description's only added signal is that create targets a tracking record and complete accepts notes, which is redundant with the schema, so the baseline 3 applies.

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

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

The description uses a specific verb and resource ("Manage evidence collection tasks") and enumerates the three concrete operations: create against a tracking record, update fields, and mark completed with notes. It distinguishes itself from evidence-record siblings (scf_evidence_write, scf_evidence_file_write) by naming tasks explicitly, though it never names those siblings directly.

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 tells the agent to select an operation via the method parameter, which is genuine dispatch guidance, and notes the editor+ role prerequisite. However, it gives no when-not guidance and no routing to related tools such as scf_list_evidence_tasks for obtaining IDs or scf_evidence_write for the underlying tracking records.

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

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

Annotations only cover readOnlyHint=false and destructiveHint=false; the description adds real context beyond them — the editor+ permission floor, the 500-record batch ceiling, the transactional nature of batch_update, and the fact that update upserts a row if missing. It omits what a failed batch does (partial vs full rollback) and what the response contains.

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 leads with the verb and resource, then enumerates the modes in the order an agent needs them, ending with the discriminator. No filler or redundant restatement of the title.

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

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

For a 12-parameter mutation tool whose schema is fully documented and whose annotations declare the safety profile, the description supplies the essential framing: role gate, batch limit, and mode selection. The only gap is response behavior, which matters somewhat given no output schema exists.

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

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

Schema description coverage is 100%, so per-parameter meaning (including the detailed method enum semantics and the 'Use instead of 500 scf_update_evidence calls' note) is already documented in structured data. The description only restates the method names and the catalog-id concept, adding no syntax or edge-case detail 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?

States a specific verb and resource ('Create or update evidence tracking records') and enumerates the three modes it supports: single create from a catalog id, single-record upsert, and batch upsert of up to 500. It is clearly a write counterpart to scf_evidence_read, though it never names that sibling explicitly.

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

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

Gives a clear selection rule — 'Pick with method' — plus an upfront role requirement ('editor+') that gates who may call it. It does not state when to prefer this over scf_evidence_task_write or other write siblings, leaving that routing to the agent.

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

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

The annotations declare readOnlyHint=true, so safety is already covered. The description adds useful behavioral context by framing the result as a work queue and mentioning optional filters, but it does not disclose pagination, ordering, or whether some parameters are mutually exclusive. This is acceptable for a read-only list tool but does not go beyond the baseline.

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

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

The description is two sentences, front-loaded with the verb and resource, and contains no filler or redundant restatement of the tool name. The second sentence efficiently summarizes the optional filtering capability. 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 read-only list tool with a fully documented schema and readOnlyHint annotation, the description provides sufficient conceptual framing: it identifies the resource, the queue semantics, and the key filters. It does not describe the exact return fields or pagination, but the description's 'what needs to be collected, by whom, and by when' partially conveys return content, and no output schema was provided. The missing pieces are relatively minor for this tool type.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters clearly, including enums and filter semantics. The description re-states only 'filter by assignee or status' and does not add meaning beyond the schema. The baseline of 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?

The description opens with a specific verb and resource: 'List evidence collection tasks. It further clarifies what this means by describing the tool as 'the work queue showing what needs to be collected, by whom, and by when', which distinguishes it from other list tools like scf_list_assignments or scf_get_work_queue. The verb-resource pair directly matches the tool name and clearly signals a read-only listing operation.

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

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

The description explains what the tool does and that filtering is optional, but it gives no guidance on when to choose this tool over closely related siblings such as scf_get_org_work_queue, scf_get_work_queue, or scf_list_assignments. There are no explicit exclusions, preconditions, or alternative-routing clues, so an agent must infer usage from the resource name alone.

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 is consistent with this being a session-capability operation rather than a data mutation, so there is no contradiction; the description usefully adds that the response surfaces the newly available tools and that loading is incremental. It does not disclose whether repeated loads are idempotent, whether previously loaded groups persist, or any cost/limit on session size — context an agent would want before calling with "all".

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

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

Two sentences, front-loaded with the action and scope, with the return behavior appended last. Nothing is redundant and no sentence could be dropped without losing 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 single-parameter tool with full schema documentation and no output schema, the description covers what it does and what it yields. The only gap is the absence of an explicit precondition statement telling the agent when a group must be loaded before its tools can be invoked.

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 enum description already spells out each group and the sibling read/write tools it unlocks, so the schema does the heavy lifting. The description's parenthetical list of group names only echoes the enum values and adds no new semantics (e.g. no note on ordering, minItems handling, or "all" equivalence).

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 ("Load") and resource ("SCF tool groups") plus an explicit enumeration of the loadable groups, and the closing sentence clarifies the effect ("Returns the tools now available"). This is clearly distinguishable from every sibling, all of which are per-resource read/write tools rather than a capability loader.

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 "Load more ... into this session" implies the trigger is needing a group that isn't yet available, and the description hints that new tools appear afterward. However, it never states the condition explicitly (e.g. "call this when a required scf_*_read/write tool is missing") and gives no guidance on batching groups versus calling "all".

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

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

Annotations already establish readOnlyHint=false and destructiveHint=false. The description adds useful context beyond annotations: the operation is self-only, supports bulk marking, and is meant as an acknowledgment step. It does not contradict the annotations.

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

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

The description is a single compact sentence that front-loads the action and scope, then efficiently covers both parameter modes and the intended workflow. There is no filler or repetition.

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

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

For a simple self-scoped write operation with two optional parameters and no output schema, the description is complete enough: it names the parameters' roles and the correct sequencing relative to scf_get_notifications. It does not describe return values or error behavior, but these are low-risk omissions for an acknowledgment operation.

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

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

Schema description coverage is 100% and the schema already explains both parameters, including the precedence rule ('ignored when notification_id is given'). The description restates this behavior but adds no new semantic 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 clearly states the action ('Mark notifications read'), the scope ('for the current user (write — self only)'), and the two invocation modes (by notification_id or all=true). It also distinguishes itself from the sibling scf_get_notifications by framing this as the write/acknowledgment counterpart.

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

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

It explicitly instructs when to use the tool: 'Acknowledge after processing scf_get_notifications.' This gives the agent a clear workflow context. It does not list exclusions, but there is no competing sibling for marking notifications read, so the 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 declare readOnlyHint=true, so the safety profile is covered and the description carries a lower burden. What remains undisclosed is genuinely useful context the description could have supplied: that most methods require an org_id obtained elsewhere, that audit_log is append-only and filter-heavy, that change_cursor is a cheap polling probe to run before re-pulling the log, and the viewer-role requirements — all of which appear only in the schema's method enum, not the description.

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

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

Two short sentences, front-loaded with the verb and resource, and the enumeration of methods is the right way to signal scope in minimal space. It is not padded, though 'Pick with method' is filler that could have been spent on real selection guidance.

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 16-parameter, seven-method multiplexer with no output schema, the definition is only adequate: the schema does the heavy lifting on parameter applicability and per-method return content, and readOnlyHint covers safety. An agent can invoke it correctly, but the description itself gives no picture of what to expect back from each method or how to sequence calls.

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 every parameter is annotated with its purpose and which method consumes it ('Used by: audit_log', etc.), so the baseline of 3 applies. The description contributes essentially nothing beyond naming 'method' as the selector, adding no format, default, or interaction detail over 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?

The description opens with a specific verb and resource ('Read organization data') and then enumerates the seven resource views covered (list, one org, settings, members, audit log, change cursor, work queue), which lets an agent tell this apart from read siblings like scf_user_read or scf_evidence_read. It stops short of naming any sibling or stating the boundary against scf_update_org_settings, so it is clear but not fully differentiated.

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

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

'Pick with method' only tells the agent that the method enum is the selector; it gives no guidance on which method to choose for a given intent, no ordering advice (the 'list first to get org_id' pattern lives only in the schema), and no when-not or alternative-sibling routing. The agent must open the schema to learn anything actionable about 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?

The readOnlyHint annotation establishes non-mutating behavior, and the description consistently presents read operations without contradicting it. Beyond listing the available views, it adds little operational context; authorization requirements and the schema's caveat that an unset profile is auto-created with defaults are not surfaced in the description.

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

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

Two compact sentences front-load the purpose and then provide the dispatch instruction. The operation list is dense but efficient, with each item identifying a distinct capability and 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 seven-method, nine-parameter read dispatcher, the description supplies an adequate top-level map while the rich schema covers per-method results, identifiers, and filters. Explicit sibling routing and important read-side caveats would improve it, but the supplied definition generally enables 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 coverage is 100%, and the schema already documents the method values, method-specific parameters, filters, formats, and sources for identifiers. "Pick with method" and the plain-English operation list provide a useful overview but little parameter meaning beyond the schema, 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 verb "Read" and resource "risk register" are explicit, and the enumerated views clarify the tool's scope. It does not explicitly distinguish itself from siblings such as scf_custom_risk_read or scf_risk_write, leaving that differentiation to inference.

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?

"Read the risk register" establishes the usage context, while "Pick with method" explains how to select an operation. There are no when-not conditions or named alternatives for writes, custom-risk reads, or other related 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=false and destructiveHint=true, and the description reinforces this by labeling delete as destructive and noting only this org's assessment row is removed while the catalog definition persists. It further adds non-obvious constraints – accept requires admin, a platform key without a user gets 403, expiry must be in the future – that go beyond the annotations, though it does not describe the response shape.

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 dense sentence plus a routing instruction, with the resource, the role gate, and the destructive warning all front-loaded. No filler sentences.

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 19-parameter multiplexed mutation tool with no output schema, the description plus the fully documented method enum give an agent enough to pick the right method and understand the permission and destructive implications. Residual gap is that nothing describes the return payload, but that is minor given the schema's richness.

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 carries per-method 'Used by' annotations, so the description adds essentially nothing per-parameter beyond restating which method is chosen. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description opens with a specific verb+resource ("Change the risk register") and then enumerates the four operations the single tool multiplexes (create, update, delete, record/renew acceptance), which clearly separates it from the read-side sibling scf_risk_read and from scf_custom_risk_write.

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 states that method selects the operation and flags role gates (editor+ for changes, admin for accept), plus the schema's method enum explicitly routes approval recording to scf_accept_risk instead of setting treatment_status to accepted. There is no explicit statement of when to prefer this over scf_custom_risk_write, which keeps it below 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?

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context. It does add that recipe_status is a queued AI job (inferable polling semantics) but omits permission requirements, pagination, and result limits; the 'viewer role' and return-shape notes appear only in the schema, not the description.

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

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

A single front-loaded sentence with no filler; the verb and resource come first and the method list follows. It is dense but compact, though the listed phrases are not verbatim method names, forcing a small mental mapping to the enum.

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

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

For a 9-parameter multiplexed tool with no output schema, the description is thin: it never says what a call returns or that behavior varies sharply by method, leaving that entirely to the schema's enum text. It is adequate to identify the tool but not to predict responses.

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 every parameter is documented with its applicable methods, so the schema does the heavy lifting. The description adds only a high-level mapping of names to operations ('one system', 'recipe status') and no format, ID-source, or enum semantics beyond that.

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 ('Read the systems inventory') and then enumerates the nine sub-operations the tool covers, so an agent can see the full scope without opening the schema. It does not name siblings such as scf_system_write or scf_evidence_read to sharpen the boundary, which keeps it from a 5.

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

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

The enumeration implies which method to pick for a given information need, but there is no explicit when-to-use / when-not-to-use guidance and no routing to alternative tools for overlapping needs (e.g., evidence lookups via scf_evidence_read). The real routing hints ('Poll this after scf_generate_system_recipes', 'obtain from scf_list_system_catalog') live in the schema's enum description, not the tool description.

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 genuinely non-structured context: the editor+/editor role requirement per operation, and that generate_recipes is asynchronous returning HTTP 202 with progress tracked via a separate status tool. It still does not mention reversibility, what a null field does on update (that detail is in the schema), or rate limits, but for a write tool it goes well 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 role scope is front-loaded in a parenthetical and the three capability families follow in one compact sentence, so it reads quickly with little waste. The single dense sentence forces the reader to parse a comma-heavy list, and "(async)" is tacked on without saying what is returned.

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 24-parameter, five-mode multiplexed write tool with no output schema, the description covers the mode inventory, role gates, and the async follow-up, which is the core framing. It stops short of summarizing the mode-to-parameter contract (e.g. that system_id is required for four of the five methods, or that update treats all fields as optional/partial) or what the non-async methods return, leaving the agent to reconstruct that from the schema.

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

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

Schema description coverage is 100% and each parameter already carries per-method "Used by:" annotations plus enum value explanations, so the schema does all the parameter work. The description adds only the generic instruction "Pick with method" and no per-mode parameter guidance or conditional-requirement summary beyond what the schema states.

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

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

The description states a specific verb and resource ("Manage the systems inventory") and then enumerates all five things the tool can do: create/update a system, declare/update an evidence capability, and generate collection recipes. The name is scf_system_write and the sibling scf_system_read exists, so the write-vs-read split is inferable, but the description never names that sibling or otherwise explicitly differentiate itself from the read 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?

It gives a meaningful selector ("Pick with method") and flags that generate_recipes is async, plus a follow-up pointer to scf_get_recipe_generation_status. However, it does not say when to use scf_system_write versus scf_system_read (or scf_capability_theme_read / scf_catalog_read) for related lookups, and the when-to-use detail lives almost entirely in the per-method enum descriptions inside the schema rather than in the description itself.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false. The description adds two things annotations cannot: it is an admin-gated write, and it is a partial update where only passed fields change — important behavior for a PATCH-style call. It stops short of describing the clear/replace semantics of null and {} values, which the schema carries instead.

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, zero filler. The operation, the scope of writable fields, the admin gate, and the partial-update contract are all front-loaded before any detail is deferred to the 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?

No output schema exists, so the description should ideally say something about what a successful update returns or whether it echoes the new settings. It covers fields, partial semantics, and the admin gate, and safety is handled by annotations, so the gap is small but present.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in depth (enum values, 4000-char limit, whole-map replacement rules, 422 on unknown domain codes). The description only echoes the three field names, adding little beyond that. With coverage this high, it does what is expected and no more.

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 (update) and resource (organization profile and maturity targets) and enumerates the exact writable fields: business_size, mission_statement, maturity_targets. An agent can immediately distinguish this from the read-side sibling scf_get_org_settings and from scf_set_target_maturity (per-control targets).

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 '(write — admin)' tag signals a permission precondition, which is useful for deciding whether the agent can call it at all. However, it gives no when-to-use vs when-not guidance and never names the obvious alternative, scf_set_target_maturity, for per-control targets — that precedence rule lives only in the parameter schema.

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 safety profile is covered. The description adds a genuinely useful behavioral fact beyond them: the identity returned is the API key's identity, meaning there is no parameter to target another user — an agent could otherwise waste calls trying to pass a user id. It does not mention pagination behavior beyond the limit param or response size.

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

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

Two short sentences, front-loaded with the scope constraint before the method list, with no filler. 'Pick with method' is mildly instructional and repeats what the required enum already makes obvious, which keeps it from a 5.

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

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

For a small, read-only, three-parameter tool with no output schema, the description covers scope, identity semantics, and the mode selector adequately. Minor gaps remain around result ordering/pagination across the modes, but nothing essential to invoking 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 method enum descriptions are far richer than the tool description (work queue contents, notification types such as risk_acceptance_expired). The description adds no syntax, format, or default details beyond what the schema already states, so baseline 3 applies.

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

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

States a specific verb ('Read') and a clearly bounded resource ('the caller's own view'), then names the three variants: current user, work queue, notifications. This implicitly separates it from org- or entity-scoped siblings like scf_org_read, though it never names an alternative explicitly.

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

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

'Pick with method' tells the agent how to choose among the three modes, but that routing is already fully enumerated in the method schema description. There is no guidance on when to use this instead of sibling reads (e.g., scf_org_read for organization data) or instead of scf_mark_notifications_read when handling notifications.

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 supplied, the description adds essentially no behavioral context beyond what annotations and schema cover — no mention of pagination behavior, 404 conditions, permission requirements, or freshness of research results. Its only contribution is a resource inventory that duplicates the method enum descriptions.

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 terse sentences, front-loaded with purpose and then the resource list; nothing is padded or redundant. The dense parenthetical list is compact at the modest cost of readability.

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 ten-method multiplexed read tool with no output schema, the description at least enumerates the full method surface, and the schema fills in per-method semantics. However it does not describe return shapes, pagination handling, or the polling relationship to the trigger tools, leaving gaps for an agent that never reads the full enum text.

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 method enum documents each of the ten options in detail, so the baseline of 3 applies. The description's only parameter-related content is "Pick with method," which restates the schema rather than adding syntax, defaults, or cross-parameter constraints.

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

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

The description opens with a specific verb+resource ("Read third-party risk data") and enumerates the sub-resources covered (vendors, research, assessments, certifications, compensating controls, action items), so an agent can tell this is the TPRM read surface rather than a write tool. It stops short of naming scf_vendor_write or other siblings as alternatives, so it falls just below 5.

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

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

"Pick with method" points the agent at the required method parameter as the routing mechanism, which is implied usage guidance. There is no explicit when-to-use/when-not, no pointer to scf_vendor_write for mutations, and no note on sequencing (e.g. poll after triggers) despite such ordering existing in the schema.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so 'Deletes are destructive' largely restates structured data. The description does add one thing not in annotations: the editor+ role requirement, which tells the agent an authorization bar exists. It does not disclose what a delete removes, whether deletes cascade, or any confirmation/irreversibility detail for a mutation tool with a destructive flag.

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

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

Two short sentences, front-loaded with the resource and access level, followed by the destructive warning and the dispatch hint. Nothing is padded, though 'Pick with method' is slightly cryptic phrasing that assumes the reader will inspect the enum.

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 nine-method, 26-parameter multiplexed mutation tool with no output schema, the description is a thin wrapper that delegates almost everything to the schema. It conveys resource scope, role requirement, and destructiveness, but says nothing about what the create/update calls return or what happens to linked records on delete.

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; each of the 26 parameters is already documented with a 'Used by' mapping to specific methods. The description adds only the framing that 'method' selects among nine operations. It does not restate required field combinations per method, but it does not need to given 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 resource (vendor sub-records), enumerates the three record types (certification, compensating control, action item) and the operations (create/update/delete), and says the dispatch key is 'method'. That is far more specific than the tool name alone. It stops short of the top mark because it never names the sibling it is not, e.g. scf_vendor_write for the vendor record itself.

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 the access precondition '(editor+)' and warns that deletes are destructive, which is real usage context. 'Pick with method' only points at the dispatch mechanism rather than explaining when to choose each method or when to use this tool instead of its siblings. The substantive when-to-use detail (e.g. prefer status=expired over deleting, set status=completed with completed_date) lives in the schema enum descriptions, not here.

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 real behavioral context: an editor+ role gate on all operations, that research and assess are async, and that assess supersedes the deprecated DPSIA trigger. It stops short of noting that update is a partial/patch-style mutation or what the queued jobs entail, which the schema covers instead.

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

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

A single front-loaded sentence with no wasted words, listing operations before mechanics. It is arguably over-compressed for a four-in-one tool with 18 parameters, but nothing is padding.

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

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

For an 18-parameter, four-method multiplexed write tool with no output schema, the description is thin — it omits how method-specific requirements interact (vendor_id for update/research/assess, name for create) and relies entirely on schema text. The key facts an agent needs (role requirement, async behavior, polling siblings) are present, so it is minimally sufficient rather than complete.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including per-method applicability via 'Used by:' tags, which sets the baseline at 3. The description adds only 'Pick with method' and the async hint; it contributes no additional meaning about the 18 parameters.

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

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

The description names the resource (vendors) and enumerates the four concrete operations — create, update, AI research, DPSIA assessment — so an agent immediately knows what the tool does. It falls short of a 5 because it gives no differentiation from the closely-named sibling scf_vendor_record_write, leaving overlap ambiguous.

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?

'Pick with method' identifies the discriminator but gives no when-to-use guidance between the four operations, and no exclusions relative to scf_vendor_read or scf_vendor_record_write. The per-method context (async, polling targets) lives in the method enum's schema description rather than in the tool description, so usage is only implied here.

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