Extend MCP

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

Annotations already mark this as non-read-only, non-idempotent, and non-destructive; the description adds useful context by stating the batch size limit and the prerequisite that files must already be uploaded. However, it does not clarify behavior on duplicate items, whether existing items are appended or replaced, or what side effects may occur. This leaves some behavioral ambiguity for a mutating operation.

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 description is two sentences with no redundant filler. The key information—bulk add, quantity range, target resource, item composition—is front-loaded and every sentence contributes meaning.

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?

Given the rich parameter schema, the prerequisite about already-uploaded files, and the presence of an output schema, the description is largely complete for an agent deciding whether and how to invoke the tool. A small gap remains around duplicate handling and append-vs-replace semantics, but this does not block correct invocation in the common bulk-add use case.

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 description coverage is 100%, so the schema already documents all four parameters in detail. The description adds no parameter-specific meaning beyond what the schema provides, which is acceptable but not additional value.

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 states a specific action (bulk-add ground-truth examples), a clear resource (evaluation set), and a defined scope (1-100 items per call). It also clarifies what each item consists of: an already-uploaded file paired with expected output. This clearly distinguishes it from related tools like update_evaluation_item or create_evaluation_set.

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 description gives clear context for when to use this tool: when adding multiple ground-truth examples in bulk to an evaluation set, with an explicit batch limit. It does not name alternatives or exclusions, but the bulk-addition framing and prerequisite that files must already be uploaded provide sufficient guidance for typical use.

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

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

Annotations already mark the operation destructive, non-read-only, and idempotent. The description adds meaningful behavioral context beyond that: it is best-effort and may not stop a run that is already finishing, which is useful for setting agent expectations.

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?

Two sentences with no filler. The main action and scope are front-loaded, and the best-effort caveat is appended compactly without repeating schema or annotation 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?

For a three-required-parameter cancel operation with an output schema and clear annotations, the description is largely complete. The only omission is an explicit statement of what happens if the run is already completed or not found, but the best-effort caveat and output schema mitigate this.

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 description coverage is 100% and each parameter, runId, environment, and workspaceId, already has a rich description including granted-target constraints. The tool description itself adds no parameter-specific semantics, so the baseline of 3 applies.

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 clearly identifies the verb (cancel) and resource (classify run), and adds the key scope 'queued or in-flight' and '(classify group)'. It is unambiguous from the sibling cancel_* tools, though it does not explicitly name a sibling alternative as a differentiator.

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 description gives a clear condition for use: cancel a queued or in-flight classify run, and warns that a run already finishing may still complete. It does not explicitly state when to prefer delete_classify_run or get_classify_run, but 'cancel' versus 'delete' and the queued/in-flight scope imply the boundary.

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

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

Annotations already declare destructiveHint and idempotentHint. The description adds valuable behavioral nuance beyond annotations with 'Best-effort: a run already finishing may still complete', which tells the agent that cancellation is not guaranteed. No contradiction with annotations exists.

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?

Two short sentences with no wasted words. The core action is front-loaded, and the critical best-effort caveat is included immediately. Every sentence earns its place.

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?

For a simple three-parameter tool with 100% schema coverage, a full output schema, and annotations covering destructive/idempotent behavior, the description is complete. It states the target state, the caveat, and the resource type. Nothing needed for correct invocation 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 description coverage is 100%, with each parameter already documented in detail, including environment pinning and get_me workspace grants. The description itself adds no additional parameter-level meaning, so the baseline of 3 is appropriate.

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: 'Cancel a queued or in-flight extract run', and adds clarifying scope with '(extract group)'. It clearly distinguishes this tool from sibling cancel_* tools by naming the resource type and target run state.

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 description gives a clear usage context: cancel only queued or in-flight runs, and expect best-effort behavior. It does not explicitly name alternatives like delete_extract_run or other cancel_* siblings, but the resource-specific wording makes the correct use case clear enough.

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

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

The description adds a meaningful behavioral caveat beyond the annotations: cancellation is best-effort and a run already finishing may still complete. The annotations already cover destructive and idempotent behavior, so this is appropriately supplemental rather than duplicative.

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?

Two short sentences deliver the core action, the scope, and the key caveat with zero redundant phrasing. The most important information is front-loaded.

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?

For a simple cancellation tool with full schema coverage, an output schema, and annotations covering destructiveness and idempotency, the description provides the remaining essential context: what states are cancellable and the best-effort nature of cancellation.

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?

All three parameters already have descriptions in the schema (100% coverage), including the environment pinning detail and runId provenance. The tool description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

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 names a specific verb ('Cancel'), a specific resource ('split run'), and narrows the scope to 'queued or in-flight' runs. It clearly distinguishes this from sibling cancel_* tools by focusing on the split-run resource type.

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 description communicates clear context: use this to cancel a split run that is either queued or currently in flight. It does not explicitly name alternatives like delete_split_run or cancel_classify_run, but the scope is clear enough for an agent to infer correct usage.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds a valuable, non-obvious behavioral caveat: 'Best-effort: a run already finishing may still complete.' This goes beyond what the annotations convey and does not contradict them.

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?

Two short sentences with no filler. The action and scope are front-loaded, and the best-effort caveat is a compact second sentence. Every word contributes to the agent's understanding.

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?

For a focused cancellation action, the description, full parameter documentation, and annotations together cover cancellation semantics, applicable run states, and best-effort behavior. It does not discuss delete_workflow_run as an alternative, but the output schema and annotations make the definition sufficient for correct invocation.

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%, with runId, environment, and workspaceId each already documented, including enum values and references to get_me and run_workflow. The tool description itself adds no parameter-specific meaning, but the schema carries the full burden, so baseline 3 is appropriate.

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 states a specific verb and resource: 'Cancel a queued or in-flight workflow run.' The parenthetical '(workflows group)' helps distinguish this from sibling cancel_classify_run, cancel_extract_run, and cancel_split_run, so the agent can select the right tool without inspecting other schemas.

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 description clearly indicates when to use the tool: for queued or in-flight workflow runs. It does not explicitly name alternatives like delete_workflow_run or the other cancel_* tools, so exclusions are implied rather than spelled out, but the state-based context is clear.

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

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

The description goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) by disclosing the async contract: a status 'running' result with a runId is not an error, the caller must poll with get_classify_run, and re-submission is forbidden. It also documents error-recovery behavior for UNAUTHORIZED/NOT_FOUND, which the schema and annotations do not convey.

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 description is dense but every sentence earns its place: purpose and modes, config constraint, async polling behavior, error recovery, and output documentation link. It front-loads the core purpose before the async protocol, and avoids filler or repetition of the title.

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?

For a complex 9-parameter, async mutation tool with nested inputs and an existing output schema, the description covers the essential invocation details: one-of classifier/config, config fallback requirements, async resumption, re-submission prohibition, auth failure handling, and where to find the output shape. Combined with 100% schema coverage, output schema, and annotations, nothing critical is left for an agent to guess.

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 description coverage is 100%, and the schema already documents the classifier/config exclusivity, the required 'other' fallback entry, unique ids, and environment constraints. The description restates these rules but adds little new parameter meaning beyond what the schema provides; the async and error-handling notes concern process behavior, not parameter semantics.

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 opens with a specific verb-and-resource statement: 'Categorize a document into one of a set of types, e.g. MSA vs SOW vs NDA.' This clearly distinguishes the tool from siblings like extract_data, parse_document, and split_document, and names the two modes of operation (saved classifier or inline config).

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 description gives clear usage context: 'Provide exactly one of classifier or config,' explains the async workflow with get_classify_run, warns never to re-submit the document, and specifies what to do on UNAUTHORIZED/NOT_FOUND. It does not explicitly name alternatives such as run_classify_batch for batch usage, so it stops short of full when-to-use versus when-not-to-use guidance.

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

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

Even with annotations present, the description adds meaningful behavioral detail: the created object is a draft, the draft is the only mutable surface, and it must be published before use. It also clarifies that cloneClassifierId copies another classifier's draft config, and that name alone creates an empty draft. This goes well beyond the raw annotations.

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 dense sentences cover purpose, initialization modes, the absence of generate mode, and the subsequent lifecycle, all without wasted words. The most important information is front-loaded and each clause earns its place.

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?

Given the tool's complexity with five parameters, nested config, and multiple initialization modes, the description is remarkably complete. It explains how to start, what not to attempt, and what to do next with the draft. The presence of an output schema also means return-value explanation is unnecessary here.

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 each parameter. The description adds relational and workflow semantics not present in the schema: config and cloneClassifierId are mutually exclusive, name alone yields an empty draft, and clone copies a draft config. This is a meaningful supplement even though the schema already carries the basic parameter descriptions.

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 opens with a specific verb and resource: 'Create a saved, reusable classifier (classify group).' It clearly distinguishes this from sibling tools like create_extractor and create_splitter, and further differentiates by stating 'There is no generate mode (extractors only).' The purpose is immediately unambiguous.

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 description gives explicit setup paths: start from config, clone an existing classifier via cloneClassifierId, or use name alone for an empty draft, and notes that config and cloneClassifierId are mutually exclusive. It also explains the lifecycle by naming the correct sibling tools for editing, publishing, and running, and explicitly warns against expecting a generate mode.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the agent already knows this is a non-read, non-destructive mutation without idempotency. The description adds context about the 'evaluations group' and the resource scoping via entityId, but does not explicitly state side effects beyond creation (e.g., whether creation is isolated until items are added, or whether the set is immediately usable). Since annotations carry the core safety profile, the additional context is useful but limited — a 3 is appropriate.

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 description is dense but efficient: the core definition and scope constraint are front-loaded in the first sentence, followed by the workflow loop and a conditional documentation pointer. The three sentences each earn their place. It loses one point only because the workflow enumeration is a touch long relative to the simple create action, though the detail is genuinely valuable for correct sequencing.

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?

For a create tool with a full 100%-coverage schema, an output schema, and annotations covering the safety profile, the description supplies what is missing: the scoping rule, the sequencing, and the newcomer pointer to docs. An agent has everything needed to call the tool correctly and understand its place in the evaluation workflow.

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 description coverage is 100%, so the schema already documents all five parameters. The description goes further by clarifying entityId as the scoping mechanism tying the set to a single extractor/classifier/splitter, and by framing workspaceId/environment as granted-target constraints (implying get_me validation). It names the resource types the entityId accepts, adding practical meaning beyond the raw schema text.

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 states a specific verb and resource ('Create an evaluation set'), immediately defines its scope constraint (scoped to ONE extractor, classifier, or splitter via entityId), and places it in the evaluations group. It distinguishes the tool from siblings like create_extractor/create_classifier and from list_evaluation_sets, so an agent can tell what this tool does and what it does not.

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 description explicitly walks through the end-to-end iteration loop (create set → add items with add_evaluation_items → publish a version → run_evaluation → read metrics with get_evaluation_run), naming the relevant sibling tools. It also gives a conditional usage guide for newcomers: call get_documentation first for the overview and set-authoring details, including specific URLs. This tells the agent when to use the tool and what precedes/follows it.

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

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

Beyond the annotations (readOnlyHint=false, etc.), the description discloses that the result is a draft, that the draft is the only mutable surface, and that it must be edited, published, and then run. It also warns about the schema dialect and the need to consult documentation, adding significant behavioral context.

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 description is four sentences that efficiently cover purpose, starting points, and lifecycle, with zero fluff. It front-loads the core purpose and packs all critical guidance into a compact, readable structure.

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?

Given the complexity (6 params, nested objects, output schema exists), the description covers all necessary guidance: starting points, mutual exclusivity, alternative tools, and the draft lifecycle. The output schema handles return values, so nothing an agent needs to call this correctly 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?

The description adds meaning beyond the schema by explaining that config, cloneExtractorId, and generate are mutually exclusive, and provides strategic guidance on choosing among them. It also clarifies the name-only case and references get_documentation for schema rules, which the schema alone does not convey.

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 clearly states the tool creates a saved, reusable extractor and distinguishes it from siblings like create_classifier and create_splitter by specifying 'extractor (extract group)'. The verb 'Create' plus the resource is specific and unambiguous.

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 explicitly lists three mutually exclusive starting points (config, cloneExtractorId, generate) and explains when to use each, including the recommendation to call get_documentation for hand-written schemas. It also describes the name-only case and the subsequent lifecycle steps (update_extractor, publish_extractor_version, extract_data), giving full context for tool selection.

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

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

Annotations already signal mutation (readOnlyHint=false) and non-idempotency, and the description adds meaningful behavioral context: the result is a saved, reusable draft; the draft is the only mutable surface; and the creation modes have mutually exclusive semantics. This goes beyond what annotations alone convey, though it does not describe response details—which is acceptable given an output schema exists.

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 dense sentences carry all essential information with no filler. The core purpose is front-loaded, and each sentence adds a distinct layer: what is created, how to start, and what happens next in the lifecycle.

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?

For a 5-parameter tool with nested objects and an output schema, the description covers the creation workflow, parameter relationships, documentation prerequisite, and downstream lifecycle. Combined with the fully described schema, nothing needed to invoke it correctly seems 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 100%, so the baseline is 3, but the description adds relationship semantics not present in the schema: config and cloneSplitterId are mutually exclusive and name alone creates an empty draft. It also restates the critical config constraint (must include a type: "other" entry) in prose, reinforcing the schema without fully duplicating 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 opens with a specific verb and resource: 'Create a saved, reusable splitter (split group)', which clearly distinguishes it from sibling creation tools like create_classifier or create_extractor. The lifecycle references to update_splitter, publish_splitter_version, and split_document further anchor its unique role.

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 explicitly explains the two starting modes (config vs cloneSplitterId) and that they are mutually exclusive, plus the fallback of name-only creating an empty draft. It also directs the agent to call get_documentation before hand-authoring config and names the exact downstream tools for editing, publishing, and running the splitter.

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

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

Annotations only signal that this is a mutating, non-idempotent call; the description adds substantial behavioral detail beyond that. It reveals that signingSecret is shown only once and cannot be retrieved later, explains receiver verification via HMAC-SHA256 with timestamp rejection, and clarifies global vs. resource-scoped event validity.

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 description is dense but every sentence earns its place: the one-time secret warning, verification mechanics, the global-vs-scoped event caveat, and the documentation pointer. The core action is front-loaded, and the critical constraints are prominently marked.

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?

For an 8-parameter tool with an output schema and nested options, this description is complete: it covers the one-time secret, verification requirements, valid event scoping, the sibling subscription path, and a documentation fallback. An agent has everything needed to call it correctly.

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 description coverage is 100%, and each parameter already has a detailed description including the enabledEvents restriction, environment grant requirement, and advancedOptions shape. The description reinforces the enabledEvents constraint but does not define new parameter semantics beyond what the schema already provides, so the high-coverage baseline of 3 is appropriate.

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 opens with a specific verb and resource: 'Register an HTTPS URL to receive Extend events (webhooks group).' It also distinguishes itself from create_webhook_subscription by explaining that resource-run events belong on the subscription tool, so an agent can tell them apart without opening the 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 explicit when-not-to-use guidance: resource-run events such as workflow_run.completed are rejected here and must be scoped via create_webhook_subscription. It even prescribes the correct sequence (create endpoint with enabledEvents [] then subscribe) and suggests calling get_documentation first for manual setup.

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

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

Annotations already declare readOnly=false, destructive=false, and idempotent=false. The description adds useful behavior beyond that: deliveries for other resources are unaffected, and the endpoint must already exist. This helps the agent understand the operation's scoped side effects without repeating annotation fields.

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?

Two sentences with high information density. The core purpose and scoping constraint are front-loaded, the alternative is named, and the documentation requirement is appended without fluff.

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?

The tool has 6 required parameters, but 100% schema coverage and an output schema cover structured details. The description supplies the missing contextual layer: when to use it, what scope it affects, and where to get configuration rules and event catalogs. Nothing critical is left unaddressed.

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 description coverage is 100%, so the baseline is 3. The description adds meaning by clarifying that only one resource per subscription is allowed, defining the resource family (extractor/classifier/splitter/workflow), and linking to the event catalog that informs valid enabledEvents values.

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?

Description states a specific action ('Subscribe an existing webhook endpoint') and precisely scopes the resource to 'ONE specific extractor, classifier, splitter, or workflow'. It clearly distinguishes this from creating an endpoint and from the sibling create_webhook_endpoint tool.

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?

Explicitly says 'Use this instead of global enabledEvents when only some resources matter', giving a clear when-to-use condition and a named alternative. It also provides a prerequisite action by instructing the agent to call get_documentation with the configuration URL first.

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

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

Annotations already cover readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description does not need to repeat those. It adds useful behavioral context by stating that the created object is a draft and that the draft is the only mutable surface, which indirectly clarifies side effects. It could go further on failure/validation behavior when steps are invalid, but the schema and docs link mitigate that.

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 dense sentences cover purpose, usage modes, documentation pointer, and lifecycle routing without redundancy. The core action is front-loaded, and every clause earns its place.

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?

The tool is complex, but the description plus the highly detailed input schema plus the presence of an output schema leave no significant gap. It provides the high-level model, the key parameter split, the documentation link for step-graph authoring, and the lifecycle sibling tools. An agent has enough to call it correctly.

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 is 3, but the description adds value by explaining the semantic distinction between name (creates an empty draft) and steps (builds the graph up front). It also ties the steps parameter to a documentation URL for correct authoring. Environment and workspaceId are already well described in the schema.

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 opens with 'Create a workflow' and defines it as a multi-step document pipeline, which clearly distinguishes it from sibling create_* tools that create classifiers, extractors, splitters, etc. It also sketches the pipeline stages (parse → extract/classify/split → validations → human review), giving an agent an accurate mental model of the resource.

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 explicitly maps different usage patterns: name alone creates an empty draft while steps builds the graph up front, and it directs the agent to get_documentation before hand-authoring. It also names the lifecycle alternatives — update_workflow for editing, deploy_workflow_version for freezing, run_workflow for running — so the agent knows exactly when create_workflow is the right call.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, but the description adds meaningful context by naming what gets destroyed (stored outputs/classify group) and emphasizing irreversibility. This goes beyond the structured hints without contradicting them.

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?

One compact sentence delivers the action, scope, and consequence with no filler. The most important information ('Permanently delete') is front-loaded, and every word earns its place.

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?

Given the 100% schema parameter coverage, output schema presence, and annotations covering safety/destructiveness, the description is complete. It adds the critical deletion scope and irreversibility warning without omitting anything needed to invoke the tool correctly.

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 description coverage is 100%, so the parameters are fully documented in the schema. The description does not add per-parameter meaning beyond the already-rich schema descriptions, so the baseline of 3 applies.

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 states a specific verb ('Permanently delete') and resource ('a classify run') plus the exact scope ('and its stored outputs (classify group)'). This clearly distinguishes it from related deletion tools like delete_extract_run or delete_parse_run.

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?

'Cannot be undone' implies the tool should be used only when permanent deletion is intended, but the description never explicitly contrasts it with alternatives such as cancel_classify_run. The when-to-use vs alternatives is left to inference rather than stated.

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

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

Annotations already provide destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds valuable context by naming exactly what gets destroyed ('stored outputs (edit group)') and emphasizing irreversibility ('Cannot be undone'), which goes beyond the annotation labels. No contradiction with annotations.

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?

Two short sentences deliver the essential message with zero filler. The action, target, and key consequence (irreversibility) are front-loaded, making the description easy to parse quickly.

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?

Given the rich annotations, 100% schema coverage with per-parameter guidance, and an existing output schema, the description completes the picture: it fully explains what the tool does, what is destroyed, and the irreversible nature. Nothing needed for correct invocation 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 100% and each parameter has a clear description (runId from edit_pdf, environment pinned by API key, workspaceId from get_me). The tool description adds no additional parameter-level meaning beyond echoing the 'edit group' concept already implicit in the schema's runId reference. Baseline 3 is appropriate.

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 states a specific verb ('delete'), a precise resource ('edit run'), and its scope ('and its stored outputs (edit group)'). This clearly distinguishes it from sibling delete_*_run tools (e.g., delete_extract_run, delete_workflow_run) by naming the edit-run type.

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 description clearly indicates the tool's use case: permanently removing an edit run and its outputs. It does not explicitly name alternatives or exclusion conditions, but the phrasing 'permanently delete' and 'cannot be undone' signals the destructive decision point. Among the many delete_*_run siblings, the resource type is unambiguous.

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

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

Annotations already mark destructiveHint=true, and the description adds valuable behavioral context: the deletion is permanent, cannot be undone, and does not affect past run metrics. This goes beyond the annotation flags without contradicting them.

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?

Two concise sentences with no filler: the first states the action and resource, the second states permanence and non-impact on past runs. Important caveats are front-loaded.

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?

For a delete operation with a full input schema, output schema, and annotations covering destructive intent, the description covers the essential behavioral facts. Nothing an agent needs to call it correctly 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 description coverage is 100%, with clear descriptions for all four parameters including ID formats and environment constraints. The tool description itself adds no parameter-specific guidance, so the baseline score applies.

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 action (permanently remove), a precise resource (one ground-truth item from an evaluation set), and the scope of the effect. This clearly distinguishes it from sibling tools like update_evaluation_item or add_evaluation_items.

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 operation is unambiguous: use this when a specific evaluation item must be permanently removed. It doesn't explicitly name alternatives, but the resource and action are specific enough that an agent can determine when it is appropriate.

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

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

The description adds behavioral detail beyond the annotations: it specifies that the deletion is permanent ('Cannot be undone') and that stored outputs are also deleted. This is useful context even though destructiveHint=true already signals destructive intent. It does not contradict any annotation.

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 description is a single, well-structured sentence that front-loads the action and irreversibility. It contains no filler and earns its place.

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?

Given the presence of a full output schema, detailed annotations, and complete parameter descriptions, the description covers the essential behavioral aspects: the permanent deletion of the run and its outputs. No critical information is missing for an agent to call this tool correctly.

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 description coverage is 100%, and each parameter (runId, environment, workspaceId) already has a thorough description in the schema. The tool description adds no additional parameter-specific semantics, so the baseline of 3 applies.

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 states a specific verb ('delete') and resource ('extract run'), and adds the scope of deletion ('stored outputs (extract group)'), which clearly distinguishes it from sibling delete_* tools like delete_classify_run or delete_parse_run. It is unambiguous and specific.

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?

There is no explicit guidance on when to use this tool versus alternatives, such as cancel_extract_run or other delete_* tools. The usage is implied by the resource name and the destructive nature, but no conditions or exclusions are given.

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

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

Discloses irreversibility, that run outputs persist, and that bytes and parsed contents are gone—detail beyond the destructiveHint annotation. This gives an agent a precise model of side effects without contradicting annotations.

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 with the core purpose and consequential side effects front-loaded. No filler; every clause contributes useful 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?

The description, schema, output schema, and annotations together cover what the tool does, when to use it, and its irreversible side effects. Nothing an agent needs to call it correctly 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 description coverage is 100%, so the description is not required to add parameter-level detail. It adds no extra semantics beyond the schema, which meets the baseline for high 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?

Clearly states the action (permanently delete) and the resource (uploaded file from Extend files group). It distinguishes from sibling delete tools by explicitly targeting a file rather than runs, webhooks, or other resources.

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?

Provides clear context that processed runs keep their outputs while the file's bytes and parsed contents are removed, helping an agent understand consequences. It does not explicitly name alternatives, but the file scope and deletion semantics make the appropriate use case unambiguous.

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

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

Annotations already declare destructiveHint=true, so the description adds value by specifying exactly what is destroyed (the parse run and its stored outputs) and emphasizing irreversibility with 'Cannot be undone.' This goes beyond the structured annotation without contradicting it.

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 description is a single, front-loaded sentence with no filler. Every word contributes: 'permanently delete' conveys irreversibility, 'parse run' identifies the target, and 'stored outputs (parse group)' explains the scope of deletion.

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?

Given the fully documented schema, the destructive and idempotent annotations, and the presence of an output schema, the description covers all essential behavioral and operational aspects. No critical information needed to call the tool correctly 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 description coverage is 100%, so all three parameters (runId, environment, workspaceId) are already documented in the input schema. The description adds no additional parameter meaning, matching the baseline of 3 for high-coverage schemas.

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 states a specific verb ('delete') and resource ('parse run'), and clarifies that it also removes the stored outputs (parse group). This clearly distinguishes it from sibling delete_* tools such as delete_classify_run or delete_extract_run.

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 description gives clear context: use this tool to permanently delete a parse run and its outputs. It does not explicitly mention alternatives or exclusion criteria, but the resource type is unambiguous enough to guide selection among the many sibling delete tools.

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

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

The description adds meaningful behavior beyond the destructiveHint annotation: it specifies that stored outputs (the split group) are also deleted and that the operation is irreversible. This gives the agent the key consequence of invoking the tool.

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?

One tightly packed sentence covers the operation, deletion scope, and irreversibility with zero filler. The most important qualifier ('Permanently delete') is front-loaded.

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?

A delete tool with a simple parameter set, full schema descriptions, and destructive/idempotent annotations is adequately covered. The description explains what is destroyed and that it cannot be undone, so no essential calling context 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 description coverage is 100%, so the parameters are already fully documented in the input schema. The tool description adds nothing parameter-specific, which is acceptable but not additive.

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 states a specific verb ('delete'), the resource ('split run'), and the scope of deletion ('and its stored outputs (split group)'). This clearly distinguishes it from other delete_*_run siblings and from cancel_split_run.

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 phrase 'Permanently delete' and 'Cannot be undone' imply this is the final-destruction option rather than a cancellation tool. However, it never explicitly names cancel_split_run as the alternative for non-permanent cancellation, leaving the routing partially implied.

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

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

Beyond the destructiveHint annotation, the description adds critical behavioral context: deletion cascades to all attached subscriptions, deliveries stop immediately, and the operation is irreversible. This meaningfully informs an agent about side effects and risk.

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 description is two sentences with no filler. It front-loads the core action and then packs the consequential side effects and permanence into a tight, readable format.

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?

For a destructive single-resource operation, the description captures what is deleted, what else is impacted, immediacy, and irreversibility. Combined with complete schema documentation, an output schema, and strong annotations, nothing essential 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?

The input schema already fully documents all three required parameters, including allowed values and usage notes, at 100% coverage. The description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

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 states a specific action ('Permanently delete'), a specific resource ('webhook endpoint'), and clarifies the scope ('webhooks group'). It also distinguishes this from deleting a mere subscription by noting that every attached subscription is removed as well.

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 description makes clear when this tool is appropriate: when a webhook endpoint must be permanently deleted. However, it does not explicitly name or contrast the sibling tool delete_webhook_subscription for cases where only a subscription should be removed, so the choice versus alternatives is only implied.

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

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

Annotations already mark destructiveHint=true and idempotentHint=true, but the description adds critical behavioral context: 'Permanently delete' and 'This cannot be undone' reinforce irreversibility, and the note that endpoint/global events are unaffected clarifies side effects. This goes beyond the annotations without contradicting them.

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 description is two concise sentences with no filler. The core action is front-loaded, and the irreversibility warning is placed immediately after. Every word adds value, and the structure is scannable for an agent.

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?

Given that the tool has an output schema, full parameter documentation, and annotations covering destructiveness and idempotency, the description is complete for an agent to call it correctly. The irreversibility and scope notes fill the key gap that structured fields do not capture. It could mention return format or confirmation behavior, but the output schema likely covers that, so nothing essential 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 description coverage is 100%, so all three parameters (id, environment, workspaceId) are fully documented in the input schema. The description adds no additional parameter-level detail or usage nuance, so it meets the baseline for high schema coverage but does not exceed 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 opens with a precise verb and resource: 'Permanently delete a webhook subscription.' It immediately specifies the scope ('webhooks group') and clarifies what is NOT affected (endpoint and global events), which differentiates it from sibling tools like delete_webhook_endpoint. This makes the tool's purpose unambiguous.

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 description does not explicitly name an alternative or give a 'when to use' directive, but it does explain that the endpoint and its global events are unaffected, implying that this tool is specifically for subscriptions rather than endpoints. This gives contextual guidance that helps an agent pick the right tool, though it stops short of an explicit 'use this instead of X when...' statement.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds value by specifying what gets destroyed ('stored outputs') and that the action 'Cannot be undone,' which is richer than the bare destructive flag. It is consistent with idempotentHint=true and openWorldHint=true.

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?

Two short sentences with zero filler; the scope ('workflow run and stored outputs') is front-loaded and the irreversibility warning comes second, before any parameter detail is needed. Every sentence earns its place.

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?

For a simple 3-param delete tool the combination is complete: the schema documents all parameters, annotations carry the safety profile, an output schema exists, and the description covers scope and irreversibility. The only notable omission is a pointer to cancel_workflow_run for in-flight runs, which is a usage-guidance nicety rather than a correctness gap.

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% — all three required parameters (runId, environment, workspaceId) carry their own descriptions, so the baseline is 3. The description adds no parameter-level detail, but it does not need to since the schema is fully documented.

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 ('permanently delete') and a precise resource ('a workflow run and its stored outputs'), and the qualifier '(workflows group)' positions it inside the workflow family. This lets an agent distinguish it from the many sibling delete_* run tools (delete_extract_run, delete_classify_run, delete_parse_run, delete_split_run) without opening their schemas.

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?

No explicit when/when-not statement, but the '(workflows group)' qualifier plus the run resource make the intended context clear among the run-deletion siblings. There is no exclusion note such as 'use cancel_workflow_run to stop an in-flight run instead,' so it stops short of a 5.

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

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

Annotations indicate this is a mutating operation but not destructive, and the description adds meaningful behavioral context: deployed versions are immutable, integer deploy numbers, and iteration continues on the draft. This goes beyond the annotations by clarifying the versioning model and permanence of deployments.

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 description is compact and front-loaded with the core purpose before moving to distinctions and usage nuance. Every sentence earns its place, including the caution that deployed versions never change and iteration should continue on the draft.

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?

The schema carries the heavy detail for the step graph and environment constraints, while the description fills in the workflow-specific versioning model and immutability. With annotations and an output schema present, the description is largely sufficient, though it could briefly mention relevant permissions or side effects given this is a mutating operation.

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 parameters extensively. The description adds useful param-level nuance, such as names being referenced at runtime and the optional 'steps' override that deploys a graph instead of the draft. This supplements the schema rather than merely repeating 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?

Description states a specific operation: deploy the workflow's current draft as a new immutable version in the workflows group. It clearly distinguishes itself from extractor/classifier/splitter publishing by noting the absence of releaseType and the integer deploy numbering. An agent can immediately understand what this tool uniquely does.

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 description provides clear context for when to use this tool, contrasting it with publishing in other tool groups and explaining workflow-specific behavior. It does not give an explicit 'use this instead of X when Y' conditional, but the distinction from sibling publish tools is strong and actionable.

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

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

Goes well beyond annotations. It discloses the async behavior (status 'running' with runId is not an error, resume with wait:true), the mapping-mode semantics, and the error handling for UNAUTHORIZED/NOT_FOUND. It also points to external documentation for the output shape. No contradiction with annotations; readOnlyHint=false is consistent with the read-like detection operation.

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 description is long but every sentence carries unique information—purpose, usage, async pattern, error handling, and doc links. It is front-loaded with the core purpose, then procedural details. Though dense, it avoids repetition and fluff, earning a high score for efficiency despite its length.

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?

For a complex tool with 7 parameters, nested objects, and an output schema, the description covers all essential aspects: what it returns, how to use it as a scaffold, the mapping mode, async resumption, error recovery, and links to authoritative docs for rules and output format. Nothing critical is missing for an agent to invoke it correctly.

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% with per-parameter descriptions. The description adds valuable context beyond the schema: the 'exactly one of id/url, never a bare string' constraint for file, the mapping mode for inputSchema, and the purpose of waitSeconds. AdvancedOptions and instructions are only named, but the schema already covers them. This is a solid improvement over the baseline 3.

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 ('Detect'), a concrete resource ('fillable fields in a PDF form'), and the output ('edit schema'). It clearly distinguishes from siblings like edit_pdf (filling) by defining detection as the scaffold. The return structure is explicitly enumerated (field type, page index, bounding box), leaving no ambiguity about what the tool does.

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?

Provides explicit when-to-use guidance: 'see what a form asks for' or 'scaffold for a structured fill' with a concrete follow-up (set extend_edit:value and pass to edit_pdf). It also covers the mapping mode (inputSchema) and the async resume pattern with get_form_detection_run, plus error recovery (re-call get_me). This is thorough and actionable.

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

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

The description discloses async behavior (running status, resume with get_edit_run), output URL expiry (~15 minutes, re-fetch with get_file), template override semantics, advancedOptions defaults (preserveSignatureValidity false), and error handling. It adds substantial context beyond annotations (readOnlyHint false, etc.) without any contradiction. Fully aware of mutation nature and idempotency implications.

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?

Though long, every sentence earns its place—covering input requirements, async flow, error handling, and advanced options. The text is organized logically, front-loading the core purpose and then addressing usage, async, and edge cases. No redundancy or filler; easily scannable by an agent.

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?

Given 8 parameters, nested objects, async behavior, and template support, the description covers every aspect needed for correct use: inputs, async polling, error recovery, output pointer structure, template override, and advanced options. It even directs to external documentation for response format, which is acceptable since an output schema exists. Nothing essential 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 description coverage is 100%, so baseline is 3, but the description adds critical meaning: file must be exactly one of id/url (never bare string), schema originates from detect_form_fields, waitSeconds is clamped, advancedOptions details (flattening, signature validity), and templateId override behavior. These constraints are not obvious from the schema alone and are essential for correct invocation.

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 the specific verb 'fill' with resource 'PDF form fields' and output 'edited file'. Clearly distinguishes from sibling tools like detect_form_fields (schema generation) and get_edit_run (async polling) by explaining inputs and flow. The purpose is unambiguous and directly usable by an agent.

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?

Provides explicit usage context: the target must be the form, not the source; parse/extract first; when to call get_documentation before hand-authoring a schema; templateId alternative; and error recovery via get_me. Names alternatives (detect_form_fields, get_edit_run) and gives conditions for their use. 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.

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

Annotations only set openWorldHint and a few flags, so the description carries the full burden of behavioral disclosure. It explicitly states that a status: 'running' result is not an error, dictates resuming via get_extract_run with wait: true, and warns never to re-submit the document. It also discloses that detail: 'full' provides provenance/citations, which parsing cannot offer, and points to external documentation for output shape.

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 description is long, but every sentence carries operational weight: mode selection, async behavior, error recovery, and documentations links. It is front-loaded with the core purpose and then layers conditions, though it is a dense continuous paragraph that could benefit from light structuring. Still, for a 10-parameter, multi-mode tool, the length is justified.

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?

Given high complexity, nested objects, async semantics, and multiple mutually exclusive modes, the description is remarkably complete. It covers what the tool does, when to use alternatives, how to handle async statuses, authentication errors, package constraints, schema dialect details, and even provenance semantics. The presence of an output schema and a documentation link further fills any remaining gap.

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%, which gives a baseline of 3, but the description adds substantial meaning beyond parameter names. It explains the exact JSON Schema dialect rules for config, gives the precise structure for currency fields, enforces mutual exclusivity of file/package/extractor, and links workspace/environment constraints to get_me. This is far more than the schema alone provides.

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 opens with a specific verb and resource: 'Extract specific structured values (totals, line items, dates, names, tables) from a document'. It also enumerates the three modes of operation (saved extractor, inline JSON Schema, or schema-less inference), making the tool's scope unmistakable. It distinguishes itself from parse_document by clarifying that raw page text belongs to parse_document, which is strong sibling differentiation.

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 description gives explicit when-to-use guidance: use extract_data when the user wants specific values, and parse_document for raw text/markdown. It also provides fallback behavior when a saved extractor does not exist, explains package vs. file selection for multi-document corpora, and gives precise async resume instructions with get_extract_run. Error handling for UNAUTHORIZED or NOT_FOUND is called out with a concrete next action (re-call get_me).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the tool returns 'draft config' or 'specific version's config,' clarifying the return semantics. It does not contradict annotations and adds meaningful behavioral context beyond what annotations provide.

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 description is a single, well-structured sentence that front-loads the main action, then adds the version capability and a practical pointer. There is no fluff or redundant wording; every word earns its place.

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?

Given the presence of an output schema and annotations covering safety, the description is largely complete. It explains the core behavior (draft vs. specific version) and tells the agent how to find IDs. The only minor gap is not mentioning list_classifier_versions for discovering version identifiers, and the default version behavior is implied rather than explicit, but this is a small omission.

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 description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning: it implies the default version is 'draft' and that version selects a config, but this is largely redundant with the schema's version description. No new parameter-level insights are provided beyond what the schema already documents.

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 states a clear verb ('get'), a specific resource ('classifier'), and distinguishes between retrieving the draft config or a specific version's config. It also names the sibling for ID discovery, which differentiates it from list_classifiers. The only minor ambiguity is the phrase 'classify group,' but the core purpose is unambiguous.

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 description explicitly instructs to use list_classifiers for discovering IDs, which is a direct usage pointer. However, it does not contrast with list_classifier_versions for version listing, nor does it state when not to use this tool (e.g., when only IDs are needed). This is a useful hint but not a full usage guide.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: polling semantics, terminal statuses, the non-terminal re-call behavior, and where to find per-run failure reasons. No contradiction with annotations.

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?

Every sentence earns its place: purpose, polling behavior, terminal statuses, re-call guidance, per-run result routing, and a documentation link. It is dense but not bloated, and the core purpose is front-loaded.

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?

The description covers what the agent needs to safely and correctly invoke the tool: how to poll, what statuses to expect, what not to do (re-submit), and where to get individual results. The output schema handles return-value details, so nothing critical 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 description coverage is 100%, so the schema already documents batchId, workspaceId, environment, wait, and waitSeconds. The description does not add new parameter-level meaning beyond clarifying the wait behavior, which the schema already covers. Baseline 3 is appropriate.

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 states a specific verb ('Get the aggregate status') and resource ('classify batch'), clarifies the related submission tool (run_classify_batch), and distinguishes aggregate status from individual results, which are routed to list_classify_runs. This clearly separates it from sibling tools like get_classify_run and list_classify_runs.

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?

Explicitly says when to re-poll with wait: true, warns not to re-submit the batch, and directs users to list_classify_runs filtered by batchId for per-run failures. This is strong when-to-use/alternative guidance.

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

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

The description discloses the blocking/wait behavior, the repeat-call pattern, and the error-handling strategy—all beyond what the annotations (readOnlyHint, idempotentHint) provide. It also references external documentation for the output shape, clarifying what will be returned. These are meaningful additions that help an agent predict the tool's runtime behavior accurately.

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 description is dense but efficient: it front-loads the primary purpose, then systematically covers wait semantics, polling instructions, error recovery, and output documentation. Every sentence earns its place; there is no fluff or repetition. The structure makes critical usage rules immediately visible.

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?

Given that the tool has an output schema (so return values need not be explained) and a complex set of behaviors (waiting, polling, error recovery), the description covers all essential aspects: the state transition pattern, the need for consistent workspaceId/environment, and the guidance to re-fetch targets on auth errors. It even points to external docs for the full response format, leaving no critical gap for an agent to call it correctly.

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?

The input schema already provides detailed descriptions for all six parameters, including the meaning of 'wait' and 'waitSeconds'. The description adds little about individual parameters; it reiterates the wait:true behavior (already in the schema) and frames the repeat-call pattern, which is more usage guidance than parameter semantics. With 100% schema coverage, this is an adequate but not exceptional score.

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 clearly states the tool's purpose: 'Get the state and output of a classify run.' It further specifies the exact use cases ('resume a running run or inspect a failed one'), which distinguishes it from sibling operations like cancel or delete. The phrase 'classify group' adds specificity about the resource type.

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 description gives explicit usage instructions: it explains the polling pattern ('While status is "running", call again with wait: true...until it is terminal'), and the error-recovery step ('On UNAUTHORIZED or NOT_FOUND, re-call get_me'). It also warns against re-submitting the document, preventing a common mistake. These are concrete, actionable guidelines that clearly separate when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable context: that the tool always works without workspace targeting, and explains the 'truncated' flag behavior (page cut at section boundary, full page available via returned url). This goes beyond annotations.

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 description is concise, with three sentences that are all information-dense. It front-loads the core action and then adds usage guidance and a behavioral note. No redundant or filler language.

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?

For a simple single-parameter tool with an output schema available, the description covers all necessary aspects: how to obtain the URL, the behavior of truncated responses, and the always-available nature. The output schema likely explains the returned structure, so no further detail is needed.

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 description coverage is 100%, so the schema already explains the url parameter well. However, the description reinforces the valid sources for the URL and adds the constraint that only docs.extend.ai URLs are fetchable, which is not fully explicit in the schema. This adds meaning beyond the schema.

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 clearly states the verb ('Fetch') and resource ('Extend docs page') and specifies the output format (markdown) and source (docs.extend.ai). It distinguishes itself from siblings like search_documentation by indicating it fetches a specific page rather than searching.

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 description explicitly tells when to use this tool: pass a URL from a tool description, an error's docUrl, or a search_documentation result. This provides clear context and implicitly differentiates from search_documentation, which is for searching rather than fetching a known URL.

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

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

Annotations already declare readOnly and idempotent hints, and the description adds substantial operational context: the wait/polling mechanism, the 'no list endpoint' constraint, error recovery steps, and the ~15-minute presigned URL expiry. It enhances transparency without contradicting any annotations.

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?

Every sentence carries actionable information: purpose, wait behavior, list limitation, polling pattern, error handling, and URL expiry. It is front-loaded with the core purpose and structured logically, with no filler or repetition.

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?

For a 5-parameter tool with an output schema, the description covers all critical usage aspects: how to wait, when to re-call, how to handle errors, and where to find the output format. It also notes the presigned URL expiry, which is essential for correct follow-up actions. Nothing an agent needs 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 description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining how wait and waitSeconds interact in polling, emphasizing that environment must match a granted target, and tying runId to the 'no list endpoint' workflow. This is a modest but real increment over the schema.

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 clearly states the tool retrieves the state and output of an edit run, distinguishes it from sibling run-getters by specifying 'edit run (edit group)', and notes the absence of a list endpoint, which clarifies its unique role.

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?

Provides explicit when-to-use guidance: keep the run ID because there's no list endpoint, poll with wait:true while running, never re-submit the document, and handle UNAUTHORIZED/NOT_FOUND by re-calling get_me. It also directs re-fetching expired URLs via get_file, leaving no ambiguity about the correct workflow.

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

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

Annotations already indicate read-only, idempotent, nondestructive behavior, so the description adds meaningful behavioral context beyond that: fresh runs report PROCESSING, wait: true blocks until terminal, non-terminal runs should be re-polled, and terminal statuses are PROCESSED, FAILED, CANCELLED. It even clarifies aggregation semantics of accuracy metrics across items, which is not visible from annotations or the schema.

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 description is dense and front-loaded with the core purpose and its unique value, and every sentence adds operational value. It is fairly long and packed into one paragraph, but it earns its length by covering async semantics, terminal statuses, and metric shapes. Slight structural improvement would come from breaking it into bulleted sections.

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?

Given the async nature of evaluations, the presence of an output schema, and the complexity of different metric shapes per resource type, the description is complete. It tells the agent how to handle polling, what statuses to expect, and what metrics are returned for extractors, classifiers, and splitters. Nothing needed to invoke the tool correctly 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 description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds important context for 'wait' behavior and the relationship between evaluationRunId and run_evaluation, plus metric names per resource type. This elevates it slightly above the baseline but does not need to carry the parameter documentation burden.

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: 'Get an evaluation run's status and accuracy metrics.' It also explicitly differentiates itself from get-batch tools by saying it is the ONLY tool that returns these metrics, making its purpose unambiguous among a large group of sibling tools.

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?

Provides explicit guidance for the async job scenario: pass wait: true to block, and call again with wait: true rather than re-submitting if still non-terminal. It also names the alternative category (get-batch tool) and distinguishes the evaluation-run use case, so the agent knows when to use this tool vs alternatives.

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

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

Annotations already cover readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds genuine value by disclosing the polling contract, the set of terminal statuses, and links to batch-processing documentation. Slight gap: the wait budget and clamping behavior are only hinted at via waitSeconds, but the terminal-state semantics are 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?

Dense but well-organized — the core purpose and polling behavior come first, followed by statuses, per-run failure routing, and a doc link. Every sentence carries operational value with no filler or repetition of schema content.

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?

Given the output schema exists and annotations carry the safety profile, the description fully covers what an agent needs: how to poll, what terminal states look like, how to avoid re-submission, and where to get per-run details. No critical operational gap remains for correct invocation.

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 is 3. The description adds cross-parameter semantics beyond the schema: it ties batchId to the bpr_... ID produced by run_extract_batch, explains which polling parameter to use and when, and connects statuses to the wait flag. This meaningfully enriches what the schema alone provides.

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 ('get the aggregate status of an extract batch') and names the submitting tool (run_extract_batch). It also differentiates from per-run tools by pointing to list_extract_runs for individual results, so an agent can distinguish it from get_extract_run and get_classify_batch.

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 explicit polling instructions ('wait: true polls until terminal... While non-terminal, call again with wait: true') and a clear negative directive ('do not re-submit the batch'). It also routes per-run failure investigation to list_extract_runs with a status filter, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds useful context beyond annotations by explaining that omitting version returns the draft config, which clarifies default behavior. No contradictions exist.

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 description is two sentences with no filler. It front-loads the primary purpose, then immediately provides the critical discovery pointer. Every word earns its place.

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?

For a read-only, idempotent get operation with full schema coverage and an output schema present, the description covers the essential usage context: what it returns, how version selection works, and how to find IDs. Nothing required for correct invocation 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 description coverage is 100%, so the schema already documents all four parameters with meaningful descriptions and an enum for environment. The description adds the high-level distinction between draft config and version-specific config, but no additional parameter-level semantics beyond that. Baseline 3 is appropriate.

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 states a specific verb and resource: 'Get an extractor with its draft config, or one specific version's config via version'. It clearly distinguishes the tool from siblings like get_extract_run and list_extractors by naming the discovery tool and focusing on extractor config retrieval. The versioning nuance is explicit and immediately meaningful.

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 description explicitly routes the agent to list_extractors for finding IDs, giving clear guidance for a key prerequisite. However, it does not mention list_extractor_versions as the way to discover available version IDs, even though the version parameter accepts version IDs. This is a minor gap in when-to-use guidance for the version-specific use case.

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

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

Annotations already mark this readOnlyHint, idempotentHint, and destructiveHint=false. The description adds non-obvious behavioral context: wait blocks until terminal or budget expiry, polls may need repeated calls, and the caller must reuse the same workspaceId and environment. It also links to output format documentation, which is useful beyond structured fields.

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 description is front-loaded with the primary purpose, then covers the polling behavior, error handling, and documentation link in a compact set of sentences. Every clause earns its place and no content is wasted.

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?

For a read-only polling tool, the description covers state retrieval, wait semantics, repeated polling, error recovery, and points to detailed output documentation. With a full output schema present and annotations already declaring safety, nothing essential 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 description coverage is 100%, so the baseline is 3. The description adds extra parameter-related nuance by saying the caller must reuse the same workspaceId and environment when resuming, and warns against re-submitting the document. It does not repeat the schema text, which is appropriate.

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 states a specific verb and resource: 'Get the state and output of an extract run (extract group)' and immediately clarifies the two main use cases: resuming a running run or inspecting a failed one. This clearly differentiates it from extraction-related siblings like run_extract_batch or cancel_extract_run.

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 description gives explicit when-to and when-not-to guidance: call again with wait: true while status is 'running', never re-submit the document, and on UNAUTHORIZED or NOT_FOUND call get_me. It also names get_me as a recovery path, which counts as an alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description correctly avoids repeating those. It adds valuable behavior beyond annotations: the presigned URL expires in ~15 minutes and requires re-calling to refresh, the 'contents: null' means 'not parsed yet' rather than an error, and split-produced child files carry parentSplit metadata. These are non-obvious behaviors that help the agent use the tool correctly.

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 description is two sentences, front-loaded with the primary purpose (metadata and presigned URL), then efficiently covers the expiry, contents semantics, and parentSplit metadata. Every sentence earns its place without redundancy. It is well-structured and scannable.

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 an output schema present, the description doesn't need to explain return values. It covers the essential operational details: URL expiry, refresh behavior, contents null semantics, and parentSplit metadata. The only minor gap is that it doesn't mention any limits on file size or number of requests, but these are not critical for a single-file fetch operation. Overall it is complete for its purpose.

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 description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying the 'contents' parameter semantics (null means not parsed yet, not an error) and implying that re-calling refreshes the URL. This enriches the parameter understanding beyond the enum and default value in the schema.

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 states a specific action: 'Get a file's metadata and a fresh presigned download URL', and optionally parsed contents. It clearly identifies the resource (a file) and the outputs (metadata, URL, contents). It distinguishes from siblings like list_files (which lists files) and parse_document (which parses) by focusing on a single file's details. The title reinforces the purpose with a clear verb and resource.

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 description gives practical context: the URL expires in ~15 minutes and should be re-fetched, and it notes that parsed contents require running parse_document first (a sibling tool). This provides guidance on when to use this tool and prerequisites. It does not explicitly name alternative tools for fetching metadata, but the purpose is clear enough that an agent would select it when needing a single file's metadata or download URL.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: wait-budget blocking, status transitions, and that completed file ids are usable as file_ inputs in other tools. No contradiction with annotations.

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 description is dense but well-organized: purpose first, then wait behavior, then statuses with follow-up actions. Every sentence contributes necessary information without padding.

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?

Given the annotations, full parameter schema, and output schema, the description covers all the behavior an agent needs to decide when to call this tool and how to interpret its result. Status semantics and next steps are fully specified.

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 is 3. The description adds extra operational meaning beyond the schema: what pending means in practice, when to retry with wait:true, and that completed ids become valid file_ references. This pushes it above baseline, though it does not fundamentally compensate for missing schema documentation.

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 names a specific verb and resource: get status and uploaded file ids of an upload link created by upload_file. It clearly distinguishes this from upload_file (which creates the link) and get_file (which retrieves file content).

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 explicit guidance on the wait parameter, explains what each status means, and prescribes the next action: call again with wait:true while pending, use the file ids once completed, or call upload_file for a fresh link when expired/cancelled. This is actionable and resolves ambiguity.

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

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint, covering safety. The description adds valuable context: waiting semantics, absence of a list endpoint, and error handling (re-calling get_me). It does not contradict annotations and enriches understanding of runtime 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?

The description is information-dense yet well organized: primary purpose first, then waiting behavior, then workflow-specific caveats, then error handling, then doc reference. Every sentence earns its place without 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?

For a read-only, idempotent operation with full schema coverage and annotations, the description covers all necessary aspects: what to do, when to use it, waiting semantics, error recovery, and where to find output shape. No critical information 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 100%, so parameters are fully documented. The description adds practical meaning: 'keep the run ID' because no list endpoint exists, and 'must match a granted target from get_me' for environment and workspace. This goes beyond schema descriptions.

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 clearly states it retrieves the state and output of a form detection run, with specific verbs 'Get' and options to 'wait'. It distinguishes from siblings by noting there's no list endpoint and that it's the companion to detect_form_fields, so an agent can easily differentiate it.

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?

Provides explicit when-to-use guidance: resume running runs, inspect failed ones, use wait:true to block, and re-call until terminal. It also warns against re-submitting the document and instructs to re-call get_me on errors, giving clear decision rules.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond that: an availability guarantee ('Always available'), ordering guidance, troubleshooting scenarios tied to error codes, and the cross-tool contract that its return values are exactly what targeted tools' workspaceId/environment arguments accept.

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?

Two dense sentences with zero filler. The first sentence front-loads the return contract, and the second delivers all usage guidance. Every clause earns its place, including the parenthetical enum values and the per-workspace rationale.

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?

Given zero parameters, rich annotations, and an existing output schema (which relieves the description of explaining return shapes), nothing is missing. The description covers what it returns, the values' meaning for other tools, when to call it, and why its results can go stale. An agent has everything needed to invoke and trust this tool.

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?

There are zero parameters, so the baseline is 4; there is nothing for the description to clarify about inputs. It instead adds cross-tool semantic value by explaining that the returned targets are precisely the values other tools' required arguments accept, which is more useful than parameter documentation for this introspection tool.

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 opens with a specific verb and resource ('Return the connected organization, the credential in use, and the granted workspace + environment targets') and names the exact values returned. It clearly distinguishes itself from the large get_*/list_* sibling cluster, which all retrieve domain resources, whereas this tool returns the caller's own identity and granted scope.

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 operational guidance is given: 'Always available; call this first,' plus two concrete re-call triggers — unexpected UNAUTHORIZED/NOT_FOUND errors and access changes — with the rationale that 'resources live per-workspace.' This is stronger than merely stating context; it tells the agent exactly when to invoke this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: the polling behavior ('wait: true polls until terminal'), the set of statuses (PENDING, PROCESSING, PROCESSED, FAILED, CANCELLED), and the instruction not to re-submit. This goes beyond what annotations state, though the polling semantics are also echoed in the wait parameter description.

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 description is compact and information-dense. Each sentence serves a purpose: purpose, statuses, polling guidance, alternative for individual runs, and a documentation reference. It is front-loaded with the core function and immediately gives actionable instructions, with zero filler.

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?

Given the tool's complexity (5 parameters, output schema present), the description covers everything an agent needs: how to poll, what statuses to expect, what to do on non-terminal results, and where to find per-run errors. The output schema handles return-value structure, so nothing critical 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 description coverage is 100%, so the schema already documents every parameter (batchId, environment, workspaceId, wait, waitSeconds). The description mentions 'batchId' coming from run_parse_batch and 'wait: true' behavior, but these are also present in the schema descriptions. No additional parameter semantics are added beyond the schema, so a baseline 3 is appropriate.

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 states a specific verb and resource: 'Get the aggregate status of a parse batch (parse group)'. It explicitly differentiates from siblings by pointing to list_parse_runs for individual results and references run_parse_batch as the submission counterpart, so an agent can immediately tell it apart from get_parse_run or list_parse_runs.

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 description gives explicit usage instructions: 'wait: true polls until terminal' and 'While non-terminal, call again with wait: true; do not re-submit the batch.' It also names the alternative for per-run failures (list_parse_runs filtered by batchId) and links to external docs for batch semantics, leaving no ambiguity about when to use this tool versus others.

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

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

Annotations already mark this as read-only and idempotent; the description adds substantial behavioral context: wait semantics, budget expiry, the need to reuse the same workspaceId/environment when polling, error recovery, and the non-persistence of pageRange/maxChars/rawBlocks between calls. No contradiction with annotations.

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 description is dense but every sentence earns its place: it covers purpose, wait behavior, error handling, output slicing, state behavior, and a doc link. The most important operational guidance is front-loaded, and there is no filler.

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?

Given the complexity (8 parameters, nested objects, output schema, many siblings), the description is complete: it explains how to poll, what to do on errors, how to handle truncation, that slicing state is not remembered, and where to find the output shape. Nothing an agent needs to invoke it correctly 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?

Although schema coverage is 100%, the description adds meaning beyond the schema: it clarifies what wait: true does, that waitSeconds is clamped, that slicing parameters must be re-passed when resuming, and how pageRange/rawBlocks address truncated output. This is valuable operational semantics, not schema repetition.

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 states a specific action: 'Get the state and output of a parse run (parse group)' and clearly differentiates the use cases: resuming a running run or inspecting a failed one. It is specific to get_parse_run and not confused with batch or list operations.

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 description gives explicit behavioral instructions: call again with wait: true until terminal, never re-submit the document, re-call get_me on UNAUTHORIZED/NOT_FOUND, and pass slicing parameters again because they are not remembered. It also explains the truncated output case with a concrete recovery path.

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

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

The annotations already indicate read-only and idempotent behavior, and the description adds meaningful behavioral detail beyond that: the polling semantics of wait, the exact status set, the terminal versus non-terminal distinction, and where to find per-run failures. This gives the agent an accurate model of how the call behaves over time.

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 description is compact: four sentences that front-load the core purpose, then cover statuses, retry behavior, per-run results, and documentation. Every sentence adds usable information and there is no filler or repetition of schema field descriptions.

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?

Given the rich annotations, full schema coverage, and presence of an output schema, the description covers the remaining context an agent needs: polling loop, status semantics, prohibition on resubmission, and how to obtain individual run results. The documentation link is an additional fallback for batch-processing details.

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 description coverage is 100%, so the baseline is 3. The description adds extra meaning by clarifying that wait: true polls until terminal status and that callers should re-invoke with wait: true while non-terminal. It also ties batchId to run_split_batch, though the schema already captures that. The description does not need to restate environment or workspace constraints because the schema covers them.

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 states a specific verb and resource: get the aggregate status of a split batch submitted by run_split_batch. It also differentiates batch-level status from individual results by pointing to list_split_runs filtered by batchId, so it is clear how this tool differs from sibling get_*_batch and get_split_run tools.

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 description explicitly explains when to call the tool again: while status is non-terminal, call again with wait: true. It also provides an exclusion by telling the agent not to re-submit the batch, and routes per-run failure details to list_split_runs, which is concrete alternative guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive, and the description adds meaningful context beyond them: wait-budget expiry, repeated polling advice, workspace/environment consistency, the 'never re-submit' rule, and error-recovery behavior. No contradiction with annotations.

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?

Four dense sentences, front-loaded with purpose and status scope. Every sentence earns its place: polling behavior, resubmission warning, error handling, and documentation link. No filler or 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 is declared, so return values need no explanation. The description covers retrieval, blocking semantics, polling protocol, error handling, and a documentation reference — everything an agent needs to call this tool correctly is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.