scf_get_control_assessment_composite

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.