Wait for Quick Schema Creation

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

Annotations declare safe/idempotent read behavior, but the description adds substantial context beyond them: terminal failure is returned in result, so a successful tool call doesn't imply success; the agent must inspect status and failed_documents. It also discloses SDK polling defaults (5s/300 attempts) and the timeout/resume behavior.

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 wait condition and terminal states, then progressively adds the failure caveat, return values, and polling guidance. Every sentence carries actionable information with no 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?

An output schema exists, yet the description still usefully notes the return of template IDs and document IDs. Combined with the polling and timeout guidance, nothing an agent needs to call and correctly interpret this tool is missing.

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 75%, so the schema already documents run_id and poll_interval formats. The description nonetheless adds real meaning for max_poll_attempts (set lower to fit client tool timeout, resume with same run_id), which goes beyond the schema's terse wording.

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?

Specific verb+resource: waits on an existing quick-schema run_id until a terminal status. It clearly distinguishes itself from sibling start_quick_schema_creation and get_quick_schema_creation by naming the run_id produced by the starter.

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?

Explicit when-to-use conditions plus failure-handling guidance: choose a smaller max_poll_attempts for short client timeouts, and on timeout re-check or wait on the same run_id rather than starting a new run. It routes the agent away from the wrong alternative action (starting another run).

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