wafle_ai_jobs_edit

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

Annotations are empty, so the description carries the full burden. It does disclose the mutating nature ('Save... and apply them') and the specific write path for product_description, which adds value beyond the schema. However, it omits whether changes are reversible, what happens to the job status, and behavior for other job types.

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 sentences, approximately 30 words, with the primary action front-loaded. The second sentence adds one specific, useful detail without any redundant phrasing or filler.

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 empty annotations and no output schema, the description is too sparse. It covers only the product_description case, leaving unclear what happens for other AI job types, what the response contains, and what the id parameter semantically refers to. The core action is stated, but the operational edges are unexplored.

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 67% (slug and user_edits are described, id is not). The description adds meaning to user_edits by explaining it lands in data.descriptions.<lang> for product_description jobs. However, the id parameter remains undocumented in both the schema and the description, so the description doesn't fully compensate for the coverage gap.

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 uses a specific verb phrase 'Save user edits... and apply them' with a clear resource (AI job's output). The concrete detail about product_description writing to data.descriptions.<lang> adds specificity beyond the name, clearly distinguishing it from sibling accept/reject/get/list tools.

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 implies when to use this tool (when saving edits to AI job output) but doesn't explicitly name alternatives like wafle_ai_jobs_accept or wafle_ai_jobs_reject, nor does it state when not to use it. The product_description example provides partial context for one scenario but no broader guidance.

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