scf_create_custom_risk

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.