wafle_ai_jobs_accept

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

With no annotations, the description discloses concrete write behaviors: writing descriptions to catalog rows, category overrides to product rows, and caching reviews summaries. It also explains why other types have no side effect (translation already cached, segment_compile read-only). However, it doesn't mention job state changes, reversibility, or error handling.

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 compact and front-loaded with the main action, followed by a bulleted breakdown of job types and their side effects. Every sentence adds necessary information without 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?

The description covers the key complexity of varying behavior across job types and explicitly enumerates what gets written for each. It lacks details on job state transitions or return formats, but with no output schema, those are less critical. Overall, it gives sufficient context for an agent to decide when to use the 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?

The description does not explain any parameters. The schema provides a description for `slug` with an example but leaves `id` undescribed, and at 50% schema coverage, the description fails to compensate by clarifying that `id` is the AI job identifier. This is a significant gap for an agent selecting and invoking the tool.

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 clearly states 'Apply an AI job's output to the platform' and enumerates specific job types with their write targets (catalog, product rows, reviews aggregates). This makes it distinct from siblings like wafle_ai_jobs_reject and wafle_ai_jobs_get.

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 explains when to use accept by listing the job types that have platform side effects (product_description, categorize, review_summary) and explicitly notes that other types have no side effect, implying they don't need acceptance. It doesn't explicitly name alternative tools like reject, but the job-type breakdown provides effective usage context.

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