Create engine drafts (pending approval)

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

Beyond annotations, it discloses idempotency details (resends update still-pending drafts, never duplicates or resurrects decided ones), platform alias mappings, thread behavior for segments, link appending at approval, schedule_hint semantics, style constraints, and capability (`draft`). This is rich behavioral context that significantly exceeds what annotations alone provide.

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 dense but every sentence adds value: primary purpose, idempotency, alias, thread/link/schedule semantics, style guidelines, prerequisite reading, and capability. It is front-loaded with the core action and flows logically through behavior, parameters, and context without 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?

Given the tool's complexity (multi-platform, segments, media, schedule, idempotency, approval flow) and no output schema, the description covers all essential behavioral and usage aspects. It explains prerequisites, safety profile, style requirements, and what happens on resubmission, leaving little ambiguity for an agent.

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?

With schema coverage at 67%, the description compensates by explaining platform aliases, segments (1 = single post, 2+ on twitter = thread), link appended to final segment, and idempotency behavior for external_ref. These meanings go well beyond the schema's basic type descriptions.

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 the tool submits a batch of platform drafts for one engine artifact (e.g., a digest issue), using the specific verb 'submit' and identifying the resource. It also distinguishes itself from the alias `create_drafts` and clarifies the generic mechanism, so it is clearly differentiated from siblings like publish_post or schedule_post.

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 provides strong context: drafts are always pending approval and never auto-publish, the alias `create_drafts` is equivalent, and it instructs to read recent posts with list_posts before drafting to match voice. It doesn't explicitly state 'use this instead of X when Y', but the pending-approval behavior and mention of approve_draft make the intended use clear.

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