Submit parse job

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the side-effect profile is partly covered, but the description goes well beyond that: each call creates a new job, consumes the API key's parse quota, uploads the file to the Basis API, and webhook_url triggers an HMAC-signed POST on completion. These quota, non-idempotency and callback details are exactly the operational facts an agent needs before calling.

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?

Three sentences, front-loaded with purpose and return shape, then usage routing, then operational caveats — a logical order with no filler. It is dense with parenthetical asides and an inline JSON fragment, which costs a little readability 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?

There is no output schema, and the description compensates by specifying the immediate response fields and where to go next for records. For a four-parameter async job tool with oneOf-style input constraints, the description covers everything needed to call it correctly and avoid duplicate quota spend.

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 100%, so the baseline would be 3, but the description adds a genuine constraint the schema does not encode: exactly one of path, url or base64 must be supplied, plus a 20 MB size cap. It also explains the practical payoff of webhook_url (skip polling), which clarifies why an agent would set it.

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 and resource ("Start an async parse of an .xlsx workbook") and states the immediate return value with concrete fields {job_id, status, status_url, stream_url}. It explicitly distinguishes itself from both parse_workbook (the synchronous alternative) and stream_job (the follow-up), so an agent can pick it without opening any schema.

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?

It gives an explicit selection rule: use this instead of parse_workbook for large files or when you don't want to wait, and then name stream_job with wait_seconds or status_only as the next step. It also states a negative condition, warning against resubmitting a file whose job is still running.

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