Get extraction

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds genuinely new behavioral content beyond them: the state machine of status values (discovering / ready / discovery_failed) and the condition under which execution becomes valid. It does not describe what the 'definition' payload contains.

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 payload statement comes first and the lifecycle/next-step guidance second, with no wasted clauses. The redundant 'get extraction' lead line is the only dead weight.

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, the description carries the burden of explaining the response, and it only sketches it as 'status and definition' without indicating what the definition object holds or how failure details appear. The lifecycle coverage is good; the return-value coverage is thin for a tool whose whole job is retrieving that payload.

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?

Only one parameter, and the schema fully documents it as 'The extraction id (ext_...)' with 100% coverage. The description adds no format, prefix, or lookup guidance beyond what the schema already gives, so it sits at the baseline for high schema coverage.

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 body states precisely what is returned: the extraction's status and definition, for a specific extraction id. The heading 'get extraction' merely restates the name/title and adds nothing, but the second sentence makes the resource and payload unambiguous, so an agent can distinguish it from create_extraction or run_extraction.

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 status lifecycle ('discovering' while the agent builds the plan, then 'ready') tells the agent this is the polling tool, and the closing sentence routes it to POST /extractions/{id}/runs once ready. It stops short of an explicit 'call this repeatedly while discovering' instruction or naming the sibling run_extraction by tool name.

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