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

With no annotations, the description carries the full burden and does well: it discloses recompilation behavior for expr, 409 conflict on renaming, ownership restrictions, and plan availability. It stops short of describing response content, but the disclosed behaviors are valuable and non-obvious.

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?

Five succinct sentences, each adding distinct value: what it does, the editable fields, special behavior for expr, renaming conflict, ownership and plan. No filler or redundancy.

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 update tool with no output schema and no annotations, the description covers the essential constraints and edge cases. It could optionally mention return values, but the provided information is sufficient for 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% so baseline is 3. The description adds meaning beyond the schema by noting that expr is recompiled against the live whitelist, and that new_name can trigger a 409 if other signals reference the current name. This enhances understanding of the 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 opens with a clear verb+object: 'Edit one of the caller's custom signals'. It lists editable fields and immediately distinguishes itself from siblings like create_custom_signal and delete_custom_signal by focusing on modification of existing signals.

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?

Provides clear context: only custom signals the caller owns can be patched, built-in signals are read-only, and renaming is refused if referenced. It does not explicitly name alternative tools, but the constraints effectively tell the agent when to use and when not to use this tool.

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