Create extraction

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

The description carries real behavioral weight beyond the annotations: discovery is async and returns no run (a common failure mode for an agent expecting a run handle), credits are charged and surfaced as `credits_charged`, and the estimate path charges nothing. It does not note that the call is non-idempotent (idempotentHint=false), so a retried request would silently create a second extraction — a meaningful omission for a create tool with no annotations covering duplication.

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 verb and the resource definition, then workflow, then example — a sensible ordering that lets an agent stop reading once it has what it needs. It loses a little to the redundant lowercase "create extraction" opener that merely restates the title and to the URL-fragment link syntax, which is noise in an agent-facing description.

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?

This is a 7-parameter, multi-step, credit-charging async operation with no output schema, so the description must do the work — and it largely does, covering the async contract, the charge, and the follow-up call. It is a bit thin on what the create response actually contains beyond `credits_charged` and `status` (field names an agent would poll on are only implied).

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 schema already documents all seven parameters (including the 422 credit_cap_exceeded behavior for max_credits); baseline is 3. The description goes past that by supplying a worked example that shows the relationship between starting_url, goal_description, output_record_json_schema and required_keys, and by restating estimate_cost as an actionable pricing switch.

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 and resource ("Create an extraction — a reusable recipe for scraping structured records from a website") and immediately bounds the scope: it creates the recipe, not the runs. It explicitly distinguishes the extraction (`ext_...`) from its runs (`run_...`) and names the siblings that operate on each, so an agent can separate it from run_extraction/get_extraction without opening a 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?

Gives the full lifecycle: create → poll `get_extraction` until status is `ready` → execute with `run_extraction`, plus the escape hatch of `estimate_cost: true` to price before committing. When-to-use, what to do next, and which sibling handles each step are all explicit; nothing is left to inference.

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