Run a workflow on a document

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

Annotations only supply openWorldHint=true, so the description carries most of the burden and delivers: blocking/wait semantics for Architect runs, return shape (ids of started jobs) for Classic runs, and a credit cost model (upload plus each step). Missing details are auth requirements and failure behavior, but the core behavioral profile is unusually well disclosed.

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 branching behavior is front-loaded in the first sentence, then the Classic-path routing, then cost, then resume — a sensible order with no filler. It is dense and slightly crammed (sibling names packed mid-sentence), but every clause carries information.

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?

With no output schema, describing returns for both workflow branches is the right call and is done. However, for a 6-parameter tool with a nested metadata object and no required fields, the unspecified dataset and metadata parameters and the undocumented source-parameter exclusivity leave real gaps.

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 only 33%, so the description must compensate; it clarifies workflow_run_job_id as the resume path and implies url/file_path as alternate source inputs, but says nothing about dataset, metadata, or that only one source parameter should be supplied. Partial compensation for a significant 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?

States a specific verb+resource ('upload a local file or URL with a workflow attached') and splits behavior by workflow type (Architect waits for outputs, Classic returns job ids), which is meaningful differentiation. It does not clearly separate itself from siblings like upload_document or standardize, leaving the agent to infer when the workflow wrapper is appropriate.

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 concrete follow-on routing: Classic workflows require wait_for_jobs then get_standardization, and Architect runs can be resumed via workflow_run_job_id. It lacks explicit when-not-to-use guidance relative to upload_document, but the conditional paths are clearly spelled out.

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