scf_create_evidence

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

Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive. The description adds value by specifying the editor+ role requirement and the behavioral effect: it starts tracking an evidence item for the organization. This gives the agent useful context beyond the annotation flags.

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

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

The description is one tight sentence with the core action and role front-loaded. The second sentence adds a useful behavioral clarification without redundancy. No filler or unnecessary detail is present.

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

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

For a create operation with no output schema, the description covers the action, the role requirement, and the intended effect. All parameter meaning is fully handled by the schema, and annotations cover the safety profile. The only minor gap is that the description does not hint at what the tool returns, but this is acceptable for a straightforward create-with-2-required-params tool.

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

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

Schema description coverage is 100%, so the schema fully documents all 10 parameters. The description adds only that evidence comes from a catalog ID, which is already in the evidence_id parameter description. This is the baseline 3 case where the schema carries the parameter meaning.

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

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

The description states a specific verb ('Create'), a specific resource ('evidence tracking record'), and a clear source ('from a catalog evidence ID'). It also distinguishes this creation action from the many list/update tools in the sibling set, especially scf_list_evidence and scf_update_evidence.

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

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

The description clearly communicates that this tool is for creating or starting to track evidence, and even notes the editor+ role requirement. However, it does not explicitly say when to use this instead of alternatives like scf_update_evidence, scf_list_evidence, or scf_list_evidence_catalog, so the guidance is implied rather than explicit.

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