create_risk

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

Goes well beyond the annotations by disclosing that a business rule always overwrites impact/likelihood/score regardless of client input — a behavior an agent could not infer from readOnlyHint=false or destructiveHint=false. It also surfaces the WRITE_ENABLED=true gate, which is exactly the kind of operational context the structured fields lack.

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?

Front-loads what the tool creates, then the critical caveat, then the write gate in a single compact block. Every clause earns its place; nothing is repeated from the schema or annotations.

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

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

For a mutation tool with no output schema, it covers the write gate, the surprising business-rule side effect, and the alternative for scoring. It doesn't say what the call returns (e.g. the new sys_id) or what defaults apply to optional fields like category, which would help an agent chain follow-up 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 coverage is 75%, so the schema already documents profile (including the auto-synced owner), statement (sys_id of sn_risk_definition) and owning_group. The description adds meaning only by naming fields that are NOT parameters, leaving all four actual parameters untouched — an appropriate baseline but no lift.

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 plus the underlying table ('Create a Risk (sn_risk_risk)'), which unambiguously separates it from list_risks, get_risk and update_risk in the sibling set. An agent knows exactly what object is being created.

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 redirects the agent away from direct field writes for scoring and names list_risk_criteria as the inspection path, plus implies the risk assessment workflow is the sanctioned route. It stops short of explicitly saying 'use update_risk to modify an existing risk' or listing prerequisites beyond the WRITE_ENABLED flag.

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