trigger_draft

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

Goes well past the annotations by describing the actual pipeline: the engine validates the definition, saves the probe code, and runs the probe exactly once. It discloses what is returned (draft id, trial run result, warnings, plain-language description) and the key safety property that nothing is scheduled until activation, which the destructiveHint/readOnlyHint flags alone would not convey.

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-loaded with the core action, then the side effects, then the return values, then the alternatives and authoring reference. Four tight sentences with no filler, though the return-value enumeration and the skill pointer could be trimmed slightly without loss.

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 nested-object, no-output-schema mutation tool, the description supplies everything an agent needs: what it writes, that the probe executes once against the live user permission context (echoed in the code param), the returned artifacts, and the activation gate. The absence of an output schema is compensated by the explicit return list.

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 baseline is 3, but the description adds the mutual-exclusivity rule the schema only implies piecemeal: pass either code you wrote or a recipe, not both. That is a genuine constraint that helps the agent construct a valid call, though it does not elaborate on definition sub-fields beyond pointing at the skill.

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 ('Submit a new trigger, or a new version of one, as a draft') and immediately scopes it against the sibling that actually runs things ('Nothing runs on a schedule until trigger_activate'). An agent can separate this from trigger_activate and trigger_recipes without opening any 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?

Gives clear context for when to use it: drafting rather than activating, and choosing between hand-written code and a ready-made recipe from trigger_recipes. It also points at the self-starter:triggers skill for authoring the definition. The one missing distinction is against the sibling trigger_update, which is not mentioned even though the 'replace' parameter overlaps with it.

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