Extend MCP

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

Annotations already convey write behavior and non-idempotency. The description adds meaningful behavioral context beyond annotations: it requires already-uploaded files, enforces a batch size limit, clarifies that items are ground-truth pairings, and instructs the agent to follow llmContext guidance in results. This is useful, non-redundant behavioral detail.

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 fluff. It front-loads the core action and batch constraint, then explains the item structure, and closes with an actionable instruction about llmContext. 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?

Given the detailed schema, output schema, and annotations, the description provides sufficient context for correct invocation. It covers batch limits, item composition, and response-related guidance. It could theoretically warn about environment pinning or duplicate handling, but those are already addressed or inferable from the schema.

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 100% coverage with detailed descriptions for every parameter, including nested expectedOutput formats. The description adds only general framing ('ground-truth examples', 'already-uploaded file') without introducing new parameter-level meaning, so a 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 clearly states the tool's function: bulk-add ground-truth examples to an evaluation set. It specifies the resource ('evaluation set'), the action ('bulk-add'), and the content of each item (file + expected output), making it easy to distinguish from sibling tools like run_evaluation or list_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 description establishes clear usage context: adding ground-truth examples in batches of 1-100, pairing uploaded files with expected outputs. It does not explicitly name alternatives or exclusions, but the purpose is clear enough that an agent can infer when to use it versus update_evaluation_item or delete_evaluation_item.

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 (destructive, idempotent, open-world), the description discloses best-effort cancellation behavior, the possibility that a finishing run may still complete, and the need to follow llmContext guidance in results. This adds meaningful behavioral context that annotations alone do not 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 two sentences long, front-loads the core action, and every sentence adds value: the scope, the best-effort caveat, and the llmContext instruction. There is no redundant or filler 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?

With a complete parameter schema, an output schema present, and annotations indicating destructive/idempotent behavior, the description covers the essential operational semantics: what can be canceled, the best-effort outcome, and the finishing-race caveat. Nothing critical is missing for making the call 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 documents all three parameters thoroughly, including source of runId, enum constraints on environment, and workspace restrictions. The description itself adds no additional parameter-level detail, 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 uses a specific verb ('Cancel') and resource ('classify run'), and further specifies the scope as 'queued or in-flight'. This clearly distinguishes it from siblings like cancel_extract_run or delete_classify_run, at least by domain and operation intent.

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 cancellation applies ('queued or in-flight') and a practical caveat ('a run already finishing may still complete'). It does not explicitly name alternatives such as delete_classify_run or other cancel_* tools, but the scope is clear enough for an agent to select this tool appropriately.

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, the description discloses best-effort cancellation behavior ('a run already finishing may still complete') and instructs the agent to follow dynamic llmContext guidance. This adds meaningful behavioral context that the annotations alone do not 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?

Three short sentences, each earning its place: purpose, behavioral caveat, and open-world guidance. 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?

The combination of annotations, full schema coverage, and the description's best-effort caveat makes this complete for an agent to call correctly. It could be even stronger by explicitly contrasting with delete_extract_run, but that is not a significant gap for this low-complexity cancellation 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 description coverage is 100%, so the parameters are already well-documented. The description adds no additional parameter-level semantics, which is acceptable because the schema carries the full 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?

The description states a specific verb ('Cancel'), a specific resource ('extract run'), and clarifies the scope ('queued or in-flight'). It also adds the useful alias 'extract group', which helps disambiguate from related run-management tools like 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 explicitly says the tool applies to queued or in-flight runs, giving clear conditions for when it is appropriate. It does not explicitly name alternatives like delete_extract_run or other cancel_* siblings, but the resource and state scoping make the intended usage 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 adds meaningful behavior beyond annotations: it says cancellation is best-effort and that a run already finishing may still complete, and it instructs the agent to follow llmContext guidance in results. This complements the destructiveHint and idempotentHint 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?

Two tight sentences deliver the core action, scope, caveat, and a follow-up instruction. No filler or redundant restatement 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 cancellation operation, the description covers the state eligibility, best-effort semantics, and result-related guidance. Output schema and parameter schema handle the remaining details, making this complete.

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 referencing workspace grants and the run ID source. The tool description does not need to add parameter details, so baseline 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?

Description uses a specific verb ('Cancel') and resource ('split run'), and clarifies scope with 'queued or in-flight' and 'split group'. This clearly distinguishes it from sibling cancel_* tools that target other resource types.

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 this applies to queued or in-flight runs and notes best-effort behavior. It does not explicitly name alternatives such as delete_split_run or state when not to use this tool, but the context is sufficient for most selection decisions.

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 carry the safety profile (destructiveHint=true, readOnlyHint=false, idempotentHint=true), and the description adds genuinely new behavioral context: the best-effort race condition where an already-finishing run may still complete, plus the instruction to follow llmContext guidance in results. No contradiction with annotations — the best-effort note is consistent with idempotentHint=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 sentences with the action and scope front-loaded, the sibling disambiguator in a tight parenthetical, and the best-effort caveat immediately after. The llmContext instruction is short and non-redundant with the schema or annotations; no filler survives.

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 output schema covers return values, annotations cover the destructive/idempotent profile, and the schema covers all three parameters, so the description only needed to handle applicability and edge behavior — which it does via the queued/in-flight scope and best-effort disclosure. Minor gap: it doesn't discuss downstream effects of canceling (e.g., dependent runs or webhook notifications), but nothing critical is missing for this complexity.

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 of 3 applies. All three parameters (runId, environment, workspaceId) are already documented with provenance ('The run ID from run_workflow') and validation rules ('Must match a granted target from get_me'), so the description need not add parameter detail.

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 ('Cancel') and a precise resource ('a queued or in-flight workflow run'). The parenthetical '(workflows group)' disambiguates it from sibling cancelers cancel_classify_run, cancel_extract_run, and cancel_split_run, and the cancel-vs-delete verb distinction separates it from delete_workflow_run without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'queued or in-flight' qualifier gives clear context for when this tool applies, and the best-effort caveat ('a run already finishing may still complete') marks the applicability boundary. However, it never explicitly names alternatives (e.g., delete_workflow_run for finished runs) or states when not to cancel, so some routing 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?

The description discloses the key side effect beyond what annotations provide: 'Creates a classify run' and the async contract — 'may return status: "running" with a runId — normal, not an error; poll it with get_classify_run.' It also states the return essence (winning type with confidence) and instructs the agent to follow llmContext guidance, which is valuable operational context not present in the 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 four dense sentences with no filler: purpose, input selection, config constraints, and async behavior each earn their place. It is front-loaded with the primary purpose and then adds only high-value operational details, making it appropriately sized for a complex 9-parameter tool.

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 input schema, output schema, and annotations, the description covers the remaining essentials: document input via examples, classifier vs config choice, fallback rules, async status and polling, and llmContext handling. Nothing needed to invoke the tool or follow up on the created run 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, which establishes a baseline of 3. The description reinforces important constraints like exactly-one-of classifier/config and inline config fallback rules, but these same constraints already appear in the schema property descriptions, so the description adds little new parameter-level meaning.

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 concrete verb and resource: 'Categorize a document into one of a set of types,' and gives concrete examples (MSA vs SOW vs NDA) that clearly differentiate classification from sibling operations like extract or parse. It also establishes the single-document action by describing a classify run and polling with get_classify_run, distinguishing it from batch, list, and get 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?

The description gives explicit selection guidance for the main input modes: 'Provide exactly one of classifier or config,' plus clear rules for inline config (fallback type 'other' and unique ids). It does not explicitly name sibling alternatives such as run_classify_batch or create_classifier, so the guidance is clear for internal choices but not fully framed against sibling 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?

Annotations provide only readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description goes well beyond these: it reveals that the draft is the only mutable surface, that name alone yields an empty draft, that there is no generate-mode fallback, and that llmContext guidance in results should be followed. 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, creation modes with prerequisite, exclusion, lifecycle routing, and result guidance. It is front-loaded with the core purpose. It loses a point for density — the mutually exclusive modes and lifecycle routing are packed into long clauses that would be more scannable as bullets or separate sentences.

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, nested-object creation tool, the description covers the full decision space: how to start (config, clone, or name-only), what not to do (no generate mode), what happens next (update/publish/run), and where to get authoritative config docs. An output schema exists, so return-value explanation is unnecessary. 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?

Schema coverage is 100%, so the baseline is 3. The description adds real value on top: the mutual exclusivity of config vs cloneClassifierId (not stated in the schema), the 'name alone creates an empty draft' default that explains what happens when both optional params are omitted, and the confirmation that generate-mode is absent. This justifies a 4.

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+resource: 'Create a saved, reusable classifier (classify group)'. It distinguishes itself from sibling creation tools (create_extractor, create_splitter, create_workflow) by scoping to classifiers and further clarifies the creation step from lifecycle siblings: 'edit it with update_classifier, freeze it with publish_classifier_version, run it with classify_document'.

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 states the two valid creation modes and their exclusivity: 'Start from config ... or cloneClassifierId ... — mutually exclusive'. It gives a prerequisite ('call get_documentation ... before hand-authoring one'), an exclusion ('There is no generate mode (extractors only)'), and a default behavior ('name alone creates an empty draft'). An agent knows exactly when and how 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 provide readOnlyHint=false, idempotentHint=false, and destructiveHint=false, but the description adds meaningful behavioral context: the set is scoped to exactly one entity, belongs to the evaluations group, and participates in a multi-step iteration workflow. The instruction to follow llmContext guidance also signals behavior that is not encoded in the schema. It could go slightly deeper into side effects or lifecycle expectations, but this is strong coverage.

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 longer than average but every section earns its place: definition, iteration loop, onboarding pointer, and result-handling instruction. It is front-loaded with the core definition and then layers workflow context. A little trimming could improve scannability, but overall it is well-structured and not redundant.

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, the description is complete: it explains the tool's role in the evaluation workflow, documents prerequisites and next steps, and relies on a fully described schema and output schema for parameter and return details. An agent has everything needed to select and 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 schema already documents all parameters well. The description adds the meaningful scoping nuance that entityId must identify a single extractor, classifier, or splitter, but it mostly relies on the schema's rich parameter descriptions. This meets the baseline for fully covered schema 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: 'Create an evaluation set — a named collection of ground-truth examples scoped to ONE extractor, classifier, or splitter via entityId (evaluations group).' This precisely distinguishes the tool from related tools like add_evaluation_items, list_evaluation_sets, and run_evaluation. The resource scope and group context are immediately clear.

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 lays out the full iteration loop: create a set → add items with add_evaluation_items → publish a new version → run_evaluation → read metrics with get_evaluation_run. It also directs new users to call get_documentation first with a specific URL. This gives an agent clear when-to-use and next-step guidance beyond what the schema conveys.

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 general side-effect hints (not read-only, not idempotent, not destructive); the description adds the key behavioral model: creation always results in a draft, the draft is the only mutable surface, and the three starting points are mutually exclusive. It also introduces the custom llmContext guidance behavior, which is not visible in 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 but tightly written: the first sentence front-loads the three mutually exclusive modes, and later sentences cover the lifecycle and a non-obvious result behavior. Every sentence earns its place for a tool with six parameters and nested objects.

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 captures the creation modes, required prerequisites for hand-written schemas, and the follow-up workflow; with a rich input schema, output schema, and annotations already covering the rest, nothing critical is missing. It even mentions the unusual llmContext instruction behavior that an agent would otherwise miss.

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?

With 100% schema coverage, the schema already documents each parameter, so the baseline is 3. The description adds relational semantics not in the schema: config/cloneExtractorId/generate are mutually exclusive, name alone yields an empty draft, and generate requires no schema docs. This is genuinely useful supplementary meaning, but the description still leans on the schema for individual property details.

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 extractor (extract group).' It distinguishes this tool from sibling create_* tools by naming the extractor domain and the three creation modes, so an agent can tell create_extractor from create_classifier or create_splitter without opening 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 explicitly covers when to use each mode: config with get_documentation first, cloneExtractorId for copying, generate for sample documents, and name alone for an empty draft. It then routes the agent through the lifecycle (update_extractor, publish_extractor_version, extract_data), which prevents misuse and makes the tool's role in the workflow explicit.

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 declare write/non-idempotent/non-destructive/open-world traits; the description adds the substantive behavioral detail: creation produces a mutable draft ('the only mutable surface'), name-only yields an empty draft, and results may carry llmContext guidance that should be followed. All claims are consistent with annotations — readOnlyHint=false aligns with a create operation, so there is no contradiction.

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 tightly packed: the core purpose is front-loaded in the first clause, and every subsequent clause — init modes, mutual exclusivity, lifecycle, llmContext note — carries distinct operational value. There is no filler, no restatement of the title, and no repetition of schema content beyond the single cloneSplitterId overlap.

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 open-world creation tool with an output schema to cover return values, the description provides everything an agent needs: the three initialization paths, the decision rule between them, the full lifecycle of the created artifact, and the llmContext operational warning. The environment/workspaceId constraints are fully handled by the schema's own descriptions, 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?

With 100% schema coverage the baseline is 3, but the description adds real value: the mutual-exclusivity constraint between config and cloneSplitterId is absent from the schema, the pointer to get_documentation for hand-authoring configs gives construction guidance, and 'name alone creates an empty draft' ties the name parameter to a default behavior. Minor redundancy with cloneSplitterId's existing schema description keeps it one notch below perfect.

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 saved, reusable splitter (split group)', a specific verb+resource statement that clarifies both the action and what a splitter is (a saved, reusable split group). It also establishes the crucial draft-versus-published distinction, which differentiates this tool from siblings like publish_splitter_version and other create_* 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 gives explicit init-mode guidance: 'Start from config ... or cloneSplitterId ... — mutually exclusive; name alone creates an empty draft' tells the agent exactly how to choose between the three input paths. It then names the exact alternatives for the follow-on workflow: 'edit it with update_splitter, freeze it with publish_splitter_version, run it with split_document.'

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 far beyond the annotations, disclosing that signingSecret is only returned on this call and cannot be retrieved later, the exact HMAC-SHA256 verification scheme, and the 5-minute timestamp rejection window. It also warns that enabledEvents are workspace-global with a validation constraint. No contradiction with annotations — readOnlyHint=false, idempotentHint=false, and openWorldHint=true all align with a stateful create operation that has external side effects.

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?

Long but earned — every sentence carries either a critical caveat (one-time secret), a security contract (HMAC verification), a routing rule (subscription vs endpoint), or a documentation pointer. The CRITICAL warning is front-loaded right after the purpose sentence. Minor deductions for the somewhat run-on enabledEvents sentence and the trailing llmContext advice, which could be tightened.

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 creation tool with nested objects and a close sibling, this is remarkably complete: the one-time secret, the verification contract, the event-scoping trap, and an escape hatch to documentation are all present. The output schema covers the response structure, so the description doesn't need to explain return values. 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 schema already covers all 8 parameters at 100%, so the baseline is 3. The description adds genuine meaning for the trickiest parameter, enabledEvents, by explaining the workspace-global vs resource-scoped distinction that the schema only gestures at, and by naming the subscription tool that handles the rejected event types. Other parameters need nothing more, but the description adds per-parameter value only for this one.

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?

Opens with a specific verb and resource — 'Register an HTTPS URL to receive Extend events' — and immediately names the webhooks group. It also distinguishes itself from its closest sibling, create_webhook_subscription, by explaining which event types each handles, so an agent can tell them apart without opening either 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?

Explicitly states when NOT to use this tool: resource-run events such as workflow_run.completed are rejected here and must go to create_webhook_subscription, including the exact two-step workflow (create endpoint with [], then subscribe). It also routes manual setup to get_documentation with a concrete URL. This is textbook when-to-use guidance with a named 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 establish readOnly=false, idempotent=false, and destructive=false, so the description only needs to add context beyond those. It adds the scoping guarantee that 'deliveries for other resources are unaffected' and points to external docs for event catalogs. It does not discuss duplicate-subscription behavior, but that is partially covered by the idempotentHint.

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 core action is front-loaded in the first sentence, and the alternative is clearly stated in the second. The configuration-rules sentence is longer but earns its place by providing the required documentation URLs and llmContext instruction.

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?

Despite six required parameters, the description covers scope, when to use it, and a mandatory documentation prerequisite. An output schema exists to describe return values, and the input schema fully covers parameter formats, so no critical calling 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 description coverage is 100%, so the baseline is 3. The description's mention of 'ONE specific extractor, classifier, splitter, or workflow' aligns with resourceType and resourceId, but it adds no syntax, format, or allowed-value detail beyond what the input 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 specific verb ('Subscribe') with a clear object: an existing webhook endpoint receiving events from ONE extractor, classifier, splitter, or workflow. It also distinguishes the tool from global enabledEvents behavior, so an agent can tell this apart from a global webhook configuration operation.

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 says 'Use this instead of global enabledEvents when only some resources matter,' giving both a condition and an alternative. It also instructs the agent to call get_documentation with a specific configuration URL first and to follow any llmContext guidance, which is concrete operational 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 communicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the description's value is additive. It discloses that the created draft is the only mutable surface, outlines the workflow lifecycle, and directs the agent to follow llmContext guidance in results. 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?

Each of the four sentences earns its place: definition, creation modes, lifecycle, and result-context instruction. The stage-flow shorthand (parse → extract/classify/split → validations → human review) is compact and informative, though the second sentence is dense enough that a slight split would improve readability.

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 high-complexity tool with an output schema, the description covers creation modes and lifecycle, and deliberately defers deep step-graph authoring rules to a linked documentation call. The steps-param routing rules live in the schema, and return values are covered by the output schema, so nothing critical for 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 baseline is 3 — the schema already documents all four parameters. The description adds cross-parameter semantics that isolated property descriptions cannot convey: name alone creates an empty draft, while steps builds the graph eagerly. This is meaningful supplemental meaning.

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 concrete verb-object pair ('Create a workflow') and clarifies what the resource is — a multi-step document pipeline with a specific stage flow (parse → extract/classify/split → validations → human review). It also distinguishes itself from lifecycle siblings like update_workflow, deploy_workflow_version, and run_workflow, so the agent can pick the right 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?

It explicitly contrasts the two creation modes — name alone yields an empty draft, while steps builds the graph eagerly — and instructs the agent to call get_documentation with a specific URL before hand-authoring a step graph. It also names the alternatives for subsequent operations (update_workflow, deploy_workflow_version, run_workflow), giving clear when-and-when-not context.

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 carry the safety profile (destructiveHint=true, readOnlyHint=false), and the description adds value beyond them by disclosing exactly what gets destroyed ('stored outputs (classify group)'), irreversibility ('Cannot be undone'), and an unusual operational instruction to follow llmContext guidance in results. No contradiction with annotations — idempotentHint=true is consistent with an irreversible delete, and openWorldHint=true aligns with the cascading deletion scope.

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 short sentences with zero filler: the core action is front-loaded, followed by the irreversibility warning, then the llmContext instruction. Each sentence carries distinct information 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?

With an output schema covering return values, rich parameter documentation, and annotations covering the safety profile, the description only needs to add behavioral facts — which it does (cascade scope, irreversibility, llmContext note). The one notable omission is the destructive-vs-cancel decision context, but an agent otherwise has what it needs 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 coverage is 100%, and the schema descriptions are rich: runId cites classify_document as provenance, environment explains the get_me API-key environment pinning, and workspaceId states the ws_... format plus the grant requirement. The tool description itself adds nothing parameter-specific, so the baseline 3 for high schema coverage 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+resource: 'Permanently delete a classify run and its stored outputs (classify group).' This clearly differentiates it from sibling delete_*_run tools (delete_extract_run, delete_split_run, delete_parse_run) by naming the exact resource type. The addition of the cascading 'classify group' scope makes the action precise with no ambiguity.

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 guidance is given on when to use this versus cancel_classify_run, which is the natural alternative for stopping or discarding a run without permanently destroying it and its outputs. The 'Cannot be undone' warning conveys stakes but not selection criteria, and the llmContext note concerns post-call behavior rather than tool choice. Given the sibling set contains both cancel_*_run and delete_*_run variants, the missing differentiation is a substantive gap.

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, and the description adds valuable behavioral context: deletion is permanent, stored outputs are included in the deletion scope, and llmContext guidance should be followed. 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?

Three short, purposeful sentences: the first states the action and object, the second the key irreversible consequence, and the third an operational instruction. There is no filler or redundant restating of the title or annotations.

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 destructive tool with a rich input schema and an output schema, the description covers all essential behavioral caveats: permanence, scope of deletion, and the llmContext instruction. The output schema handles return-value expectations, so nothing critical is missing 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 description coverage is 100%, with all three parameters documented in detail, including the environment enum and granted workspace constraints. The description itself offers only minimal parameter-related context, but the schema carries the burden, so the baseline 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 uses a specific verb and resource: it 'permanently delete[s] an edit run and its stored outputs (edit group)'. This clearly distinguishes it from the many delete_* siblings that target other run types, 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 clearly establishes the use case: deleting an edit run. It also provides a caution ('Cannot be undone') that helps an agent confirm destructive intent. It does not explicitly name alternatives, but the sibling set shows no overlapping edit-run deletion tool, so the usage context is effectively 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 and readOnlyHint false, and the description adds important non-obvious behavior: deletion is permanent, cannot be undone, and past run metrics are unaffected. This goes beyond the structured hints and clarifies the side-effect profile for a destructive 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 short and front-loaded: the first sentence states the core purpose and the second states the key side effect. Minor redundancy exists between 'Permanently remove' and 'This cannot be undone,' and the final instruction about llmContext guidance is vague and less directly useful for tool invocation.

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 and annotations covering the destructive safety profile, the description adds the essential non-obvious facts: permanence, irreversibility, and metric preservation. The instruction to follow llmContext guidance hints at handling result-provided context, though it remains somewhat unclear.

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 repeats domain concepts like 'ground-truth item' and 'evaluation set' but does not add ID formats, environment constraints, or value semantics 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 first sentence names a specific action ('Permanently remove'), a specific resource ('one ground-truth item'), and the containing context ('evaluation set (evaluations group)'). This clearly distinguishes the tool from sibling delete_* tools and from update_evaluation_item by focusing on item-level removal.

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 alternatives such as update_evaluation_item or add_evaluation_items, but it supplies clear decision-relevant context: the operation is permanent and past run metrics remain unaffected. This lets an agent infer that the tool is for removing items without altering historical evaluation results.

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?

No annotations are provided, so the description carries the full burden, and it delivers the essential behavioral facts for a destructive operation: the deletion is permanent, it cascades to stored outputs (extract group), and it cannot be undone. The llmContext instruction adds procedural context. Minor gaps, such as permissions and whether a running run can be deleted, remain.

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 short sentences with no wasted words. The primary purpose and destructive scope are front-loaded, the irreversibility warning immediately follows, and the llmContext note is a single compact closing sentence. 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 destructive tool with no annotations and no output schema, the description discloses the critical facts (permanence, cascading deletion). However, it omits state prerequisites (e.g., whether a run must be canceled before deletion), what the response contains, and how this relates to the extract group lifecycle. Adequate but with clear gaps.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is effectively 100%: workspaceId, environment, and runId all have descriptions, including the runId provenance ('The run ID from extract_data') and the environment-API-key pinning constraint. Per the baseline rule, the description need not re-explain parameters, and it doesn't.

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 (delete) and resource (extract run), and expands scope by naming what else is affected ('stored outputs (extract group)'). The resource naming 'extract run' distinguishes it from the sibling delete_classify_run, delete_split_run, and delete_workflow_run tools without requiring schema inspection.

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 when-to-use, when-not-to-use, or alternative guidance is provided. Critically, the sibling cancel_extract_run exists and stops a run without deleting it; the description never clarifies when an agent should cancel versus permanently delete. 'Cannot be undone' is a caution, not usage direction.

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 by explaining that runs which already processed the file retain their outputs, while the file's bytes and parsed contents are destroyed, and that the operation cannot be undone. This discloses important irreversible consequences that annotations alone 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 compact, direct, and front-loaded with the core purpose. Every sentence adds value: the action, the preservation of run outputs, the irreversibility, and the operational instruction about llmContext guidance. No fluff 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 destructive single-resource operation with three fully documented required parameters and an output schema available, the description covers what an agent needs to know: scope, side effects, irreversibility, and a non-obvious follow-up instruction about llmContext. 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 provides 100% coverage with detailed descriptions for all three parameters (fileId, environment, workspaceId). The description adds no additional parameter-level meaning, so the baseline score 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 and resource: 'Permanently delete an uploaded file from Extend (files group).' This clearly distinguishes it from sibling tools that delete runs, webhooks, or subscriptions, and leaves no ambiguity about what action is performed.

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 the tool's purpose clear and implies it should be used when permanently removing an uploaded file is intended. It does not explicitly contrast with alternatives like get_file or list_files, but the file-specific deletion scope is enough to route an agent to the correct tool among the many delete_* siblings.

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 destructive and idempotent, and the description adds meaningful context beyond them: the deletion is permanent, cannot be undone, and removes stored outputs (the parse group). The instruction to follow any llmContext guidance in results is an additional behavioral detail. 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?

The description is three short sentences with no filler. It front-loads the core action and affected resources, then the key consequence, then the operational follow-up instruction. 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 destructive tool with a full input schema, an output schema, and annotation flags, the description is complete. It tells the agent what is deleted, that the action is irreversible, what exactly is destroyed, and that llmContext guidance in results should be followed. 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%, so the input schema fully documents runId, environment, and workspaceId, including the environment enum and granted-workspace requirements. The description adds no parameter-specific meaning, which is acceptable given the high schema coverage; 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, resource, and affected object: 'Permanently delete a parse run and its stored outputs (parse group).' It clearly distinguishes this tool from sibling delete_*_run tools by naming the parse-specific run and its associated parse group, and the 'Cannot be undone' warning reinforces the operation's 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?

No explicit guidance is given for when to choose this tool over alternatives or when not to use it. The 'Cannot be undone' warning implies caution, but it does not state conditions, prerequisites, or compare this with other run lifecycle tools like cancellation or listing. The instruction to follow llmContext guidance concerns post-call behavior, not 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 mark the tool as destructive, but the description adds meaningful specifics: deletion is permanent, stored outputs are removed, and any llmContext guidance in results should be followed. This goes beyond the generic destructiveHint and gives an agent actionable 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?

Three short sentences, each earning its place: the action and scope, the irreversibility warning, and the operational instruction about llmContext. 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?

For a simple irreversible delete operation with full schema coverage and annotations, the description is largely complete. A small gap: it does not explicitly mention cancel_split_run as the non-destructive alternative, which would make the decision context fully complete.

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 explains its meaning and constraints. The description does not need to repeat parameter details, 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 opens with a specific verb and resource: 'Permanently delete a split run and its stored outputs (split group).' This clearly distinguishes the tool from siblings like get_split_run, list_split_runs, and especially 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 wording 'Permanently delete' and 'Cannot be undone' implies the tool is for irreversible deletion, but the description never explicitly says when to use it versus cancel_split_run or when not to use it. Usage context is implied 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?

The description goes well beyond the destructiveHint annotation by disclosing the permanent nature, cascade deletion of subscriptions, immediate delivery stop, and irreversibility. It also includes an instruction to follow llmContext guidance. This adds meaningful behavioral context that annotations alone do not 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 compact and front-loaded with the core action, followed by essential warnings. The final instruction about llmContext is somewhat generic but not harmful. It avoids unnecessary elaboration while covering key behavioral 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 simple delete operation with an output schema, annotations, and detailed parameter documentation, the description covers all critical operational concerns: permanence, cascading effects, and immediate impact. Nothing essential 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 description coverage is 100%, and the schema already details each parameter including ID format, environment restrictions, and workspace constraints. The description adds no additional parameter-level meaning, so the baseline score 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 states a specific verb and resource: 'Permanently delete a webhook endpoint', which distinguishes it from related siblings like create_webhook_endpoint, update_webhook_endpoint, and delete_webhook_subscription. The 'webhooks group' qualifier adds context without ambiguity.

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 that deleting an endpoint also deletes all attached subscriptions, implying this tool should be used when the entire endpoint should be removed. It doesn't explicitly name alternatives like delete_webhook_subscription, but the cascade behavior makes the scope clear enough for an agent to choose correctly.

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 destructive, but the description adds important behavioral context: the deletion is permanent, cannot be undone, and does not affect the endpoint or its global events. It also instructs the agent to follow llmContext guidance included in results, which is useful operational direction.

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 short sentences with no filler. Each sentence earns its place: deleting the subscription, scoping the side effects, emphasizing irreversibility, and providing follow-up guidance.

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 operation with a fully documented input schema and an output schema present, the description covers the essential behavioral facts: irreversibility, side-effect scope, and result guidance. 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%, and the schema already documents all three required parameters, including IDs, environment enum meaning, and workspace constraints. The description adds no parameter-specific 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?

States a specific action and resource: 'Permanently delete a webhook subscription.' The parenthetical '(webhooks group)' and the note that the endpoint and its global events are unaffected clearly distinguish this from deleting a webhook endpoint or updating a subscription.

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: this tool removes only the subscription, not the endpoint or its events. It does not explicitly name an alternative sibling tool such as delete_webhook_endpoint, but the scoping statement effectively tells the agent when this tool is appropriate and when it is not.

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 (destructiveHint: true, readOnlyHint: false), the description adds meaningful behavioral context: deletion is permanent, cannot be undone, and also removes stored outputs. It also instructs the agent to follow any llmContext guidance in results, which is an operational behavior not captured by structured 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 two sentences with no filler. It front-loads the core action, states the consequential side effect, and includes a brief agent-relevant instruction about llmContext. 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-parameter destructive tool with a 100% described schema, strong annotations, and an output schema, the description is nearly complete. It covers purpose, scope, permanence, and side effects. The only notable gap is the lack of an explicit alternative comparison with cancel_workflow_run.

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 complete descriptions for all three parameters, including the runId source and environment pinning constraints. The description adds no parameter-specific semantics beyond the general statement about stored outputs, so the schema carries the load and the baseline score 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 uses a specific verb ('delete') and resource ('a workflow run'), and further defines the scope by saying it removes stored outputs specifically for the 'workflows group'. This distinguishes it from sibling delete_*_run tools (classify, extract, split, etc.) without needing to inspect each.

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 that this tool applies to workflow runs, but it does not explicitly state when to prefer deletion over cancellation or other operations. Given that cancel_workflow_run exists as a sibling, guidance on 'use cancel if you only need to stop a run' would improve this dimension, but the resource type is clearly 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 establish this is a mutating, non-idempotent operation (readOnlyHint=false, idempotentHint=false). The description adds meaningful behavioral context beyond that: versions are immutable, use integer deploy numbers, have no releaseType, and an optional display name referenced at run time. 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 sentences with zero waste, front-loaded with the core purpose and immediately followed by the key sibling distinction. Every sentence earns its place, including the irreversibility note and the llmContext reminder.

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 very rich parameter schema, existing output schema, and annotations, the description covers the essential deployment semantics (immutability, numbering, draft vs. steps, runtime reference). The main gap is routing the agent toward run_workflow for executing the deployed version, but the complex step-graph rules are already delegated to get_documentation in the schema.

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 the steps parameter description is exceptionally detailed, so the baseline is 3. The description adds value on top by explaining the steps/name semantics: 'Pass steps to deploy that graph instead of the draft' and 'optional display name referenced at run time', which clarify relationships not fully spelled out 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 verb and resource: 'Deploy the workflow's current draft as a new immutable version (workflows group)'. It explicitly distinguishes itself from the sibling publishing tools by stating 'Unlike extractor/classifier/splitter publishing there is NO releaseType', so an agent can tell it apart without opening 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 gives clear usage context: deploy makes an immutable run-time version, 'Deployed versions never change — keep iterating on the draft', and it contrasts the workflow deploy path with extractor/classifier/splitter publishing. It does not explicitly state when to use run_workflow instead of deploying, so the guidance stops short of a full when-to-use/when-not-to-use matrix.

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 behavior beyond annotations by explaining the returned schema structure, the mapping-mode behavior of inputSchema, the existence of inspectable runs via get_form_detection_run, and that llmContext guidance may appear in results. This meaningfully complements the sparse 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 not bloated: it front-loads the core purpose and return contract, then gives crisp workflow guidance, documentation pointers, and run inspection. Every sentence contributes actionable 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?

Despite having 7 parameters and nested objects, the description is complete enough: the schema handles parameter details, an output schema exists, and the description covers the main use cases, mapping mode, documentation lookup, run inspection, and result guidance. No critical behavioral 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 coverage is 100%, so the baseline is 3. The description adds extra value by explaining that inputSchema triggers mapping mode and by clarifying how detected fields and extend_edit values connect to edit_pdf. This goes beyond the schema's own 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 states a specific verb ('detect'), a clear resource ('fillable fields in a PDF form'), and the exact deliverable ('return an edit schema (edit group)'). It differentiates the tool from siblings by scoping it to form-field detection rather than extraction, splitting, or editing.

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 context: use it to see what a form asks for, as a scaffold for a structured fill, and in mapping mode with an existing inputSchema. It also names the relevant downstream/alternative tools: edit_pdf, get_form_detection_run, and get_documentation.

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 convey readOnlyHint=false, and the description adds valuable behavioral detail: output is a pointer { id, presignedUrl }, the URL expires in ~15 minutes, runs can be inspected via get_edit_run, and llmContext guidance should be followed. The target-vs-source warning also surfaces a common misuse.

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, value sources, target/source caveat, documentation prerequisite, output format, expiry, and follow-up inspection. It is front-loaded with the core purpose and avoids 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?

For a complex mutation tool with 7 parameters, the description covers the full workflow: what inputs to pass, how they are derived, what the output looks like, how to monitor it, and how to handle expiration. The output schema exists, and environment/workspace constraints are already in the schema, 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 coverage is 100%, so the baseline is 3, and the description adds meaningful semantics beyond the schema: file must be the target form rather than the source, schema should come from detect_form_fields with extend_edit keys, and instructions are free-form prose with a concrete example. This justifies a score above baseline.

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: fill form fields in a PDF and return the edited file. It also distinguishes itself from parse/extract siblings by explicitly requiring the TARGET form, not the source document, which removes ambiguity about its role in the pipeline.

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 workflow guidance: parse or extract the source first, use a schema from detect_form_fields, call get_documentation before hand-authoring a schema, inspect runs with get_edit_run, and re-fetch expired output with get_file. This tells the agent when to use this tool and which sibling tools support 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?

Discloses key runtime behavior beyond annotations: the call 'Creates an extract run' and may return status "running" with a runId — 'normal, not an error; poll it with get_extract_run'. It also flags that detail:"full" is 'the only way to prove where a value came from (provenance)' and instructs agents to follow any llmContext guidance. These traits are consistent with annotations (readOnlyHint=false, idempotentHint=false), so no contradiction 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?

Every sentence earns its place — there is no filler, and the core purpose and primary sibling distinction are front-loaded. However, the operational details (mode rules, package handling, detail/provenance, polling, llmContext) are packed into a dense single block without internal grouping, making it harder to scan; a 5 would require clearer structural organization.

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 highly complex tool (10 parameters, nested objects, three execution modes, async runs, an output schema), the description covers every operational decision an agent faces: mode selection, sibling routing, error recovery when an extractor is missing, polling on 'running' status, provenance via detail:"full", and llmContext handling. The output schema covers return-value structure, so no further documentation 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 baseline is 3. The description adds genuine relational meaning beyond the schema by stating cross-parameter constraints: 'exactly one of extractor or config, or omit both,' 'schema-less ... not usable with package,' and 'package instead of file' for 2-50 documents. These mode-selection semantics materially help an agent choose the right parameter combination, which justifies a 4.

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?

Opens with a specific verb+resource: 'Extract specific structured values (totals, line items, dates, names, tables) from a document,' and enumerates the three execution modes (saved extractor, inline JSON Schema, schema-less inference). It explicitly distinguishes itself from parse_document ('for the raw text/markdown of the pages use parse_document instead'), so an agent can tell the two apart immediately.

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 and names alternatives with conditions: 'If the user says "OCR" but wants specific values out, use this tool; ... use parse_document instead.' It also states the mode-selection rule ('Provide exactly one of extractor or config, or omit both'), the file-vs-package condition, and an error-recovery path ('rerun THIS tool without the extractor ... do not fall back to parse_document'). This is exemplary routing 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 cover readOnly, idempotent, non-destructive, and open-world behavior, so the bar is lower. The description adds meaningful behavioral context by explaining the draft-versus-version config behavior and instructing the agent to follow llmContext guidance in results, which is 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?

Three short sentences with no wasted words. The core behavior is front-loaded, discovery guidance is given, and the llmContext follow-up instruction is the final sentence. 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?

With a rich output schema and annotations covering safety, the description doesn't need to explain return values. It covers retrieval modes, discovery via list_classifiers, and post-result guidance. It could be slightly more explicit about the default behavior when version is omitted, though the draft-config phrasing implies it.

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 value by clarifying the version parameter's purpose ('one specific version's config via version') and by connecting the id parameter to list_classifiers for discovery.

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 ('Get') and resource ('classifier'), and clarifies the two distinct retrieval modes: draft config versus a specific version's config via the version parameter. It clearly distinguishes itself from list_classifiers by pointing to that sibling as the discovery tool for IDs.

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 directs the agent to use list_classifiers to discover IDs, which is key usage guidance. It also orients the agent to the 'classify group' family, but it doesn't spell out when not to use this tool versus close siblings like get_classify_run or list_classifier_versions.

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 read-only/idempotent/non-destructive behavior, so the description does not need to repeat safety. It adds genuinely useful behavior: wait: true polls until terminal, enumerates the possible statuses, and instructs the agent to follow llmContext guidance in results. This goes beyond 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?

Three short sentences front-load the core action, then add polling behavior, statuses, and the llmContext note. Every sentence earns its place and there is no filler or redundant schema 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 read-only status tool with a full input schema and an output schema, this is nearly complete: it identifies the batch source, status vocabulary, polling behavior, and a follow-up instruction about llmContext. It could be more explicit about default wait behavior or alternative tools, but 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 fully documents all five parameters. The description only reinforces the wait semantics and does not add meaning beyond the schema, so the baseline 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 names a specific resource (classify batch / classify group), a specific action (get aggregate status), and ties it to run_classify_batch. The 'aggregate' wording separates it from per-run tools like get_classify_run, and the status list removes ambiguity about what is being queried.

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 clearly implies when to use it: after submitting a classify batch via run_classify_batch, to check its aggregate status, with optional polling. However, it does not explicitly contrast it with get_classify_run or list_classify_runs, nor state when those alternatives should be preferred.

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 declare readOnly, idempotent, and non-destructive behavior, and the description adds meaningful non-obvious behavior: wait: true blocks until terminal or wait-budget expiry, repeated calls are needed to continue waiting, and llmContext guidance in results should be followed. 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?

Three sentences with no wasted words: the core purpose is front-loaded, then the wait behavior, then the llmContext follow-up instruction. 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?

Given the detailed input schema, the annotations, and an output schema, the description captures the essential runtime behaviors an agent needs: polling, non-terminal states, wait-budget behavior, and llmContext handling. Nothing critical 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%, and each parameter already has a rich description including defaults, enums, and constraints. The description adds useful behavioral framing for wait but does not meaningfully expand on parameter semantics beyond the schema, 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 states a specific verb and resource: 'Get the state and output of a classify run.' It also clarifies the operational purpose—resuming a running run or inspecting a failed one—which distinguishes it from list/cancel/batch siblings 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?

The description gives clear context for when to use this tool: resume a 'running' run or inspect a failed one, and use wait: true to block. It doesn't explicitly name alternatives or exclusion cases, but the context is strong enough for an agent to select it over listing or cancellation 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds meaningful context beyond annotations: the fetch is live from docs.extend.ai, accepts only docs.extend.ai pages, and requires no workspace targeting. This helps the agent understand external dependency and scope 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?

Two sentences with no filler. The main action and format are front-loaded, and the remaining sentence provides exactly the practical guidance needed for invocation.

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 simple: one parameter, output schema exists, and annotations cover safety and idempotency. The description fully explains what the tool does, where URLs come from, and its availability. Nothing essential is missing for an agent to select and 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 description coverage is 100%, and the single 'url' parameter is already well-documented in the schema with the same source examples. The description reinforces the parameter's purpose but does not add significant semantic information beyond what the schema 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 ('Fetch'), resource ('an Extend docs page'), and format ('as markdown, live from docs.extend.ai'). It distinguishes itself from search_documentation by focusing on retrieving a known page rather than discovering pages.

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 input sources: 'a URL from a tool description, an error's docUrl, or a search_documentation result.' It also notes availability constraints ('Always available, no workspace targeting'). It does not explicitly name an alternative for when no URL is available, but the mention of search_documentation results implies the search tool handles discovery.

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 establish read-only, idempotent, non-destructive behavior. The description adds genuinely useful behavioral detail: wait blocking semantics, wait-budget expiry, calling again to continue waiting, and following llmContext guidance in results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core purpose, then the key behavioral details. No filler; every clause adds decision-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a full output schema, annotations, and this description, an agent has everything needed to invoke correctly: run lifecycle, wait behavior, no-list constraint, and output guidance. 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 structured schema already documents all five parameters. The description reinforces wait and runId semantics but does not significantly extend parameter meaning beyond the schema, so the 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 operation—'Get the state and output of an edit run'—and identifies the exact resource ('edit run (edit group)'). It also names the intended scenarios (resume a running run, inspect a failed one), making it easy to distinguish from other get_*_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 provides clear use context: use it to poll a running run or inspect a failed one, and wait:true to block. It also warns that edit runs have no list endpoint so the run ID must be retained. It stops short of naming an alternative tool for edge cases, but the guidance is sufficient.

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 behavior: async processing with PROCESSING status, terminal statuses, wait semantics, and metric aggregation rules. Also notes llmContext guidance should be followed. No contradictions.

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 structured description, front-loaded with purpose and exclusivity. The metric breakdown by resource type is long but useful for the agent to know what to expect; 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?

Complete for a read-only retrieval tool: describes statuses, metrics by resource, wait behavior, terminal states, and post-processing guidance. Output schema further covers return shape.

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 baseline is 3. The description adds meaning beyond the schema by explaining wait:true as a blocking alternative to polling, and clarifies metrics are aggregated across items rather than per-item. This enriches the parameter's purpose, though most param details remain 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?

States a specific verb ('Get') and resource ('evaluation run's status and accuracy metrics'), and explicitly distinguishes itself from sibling get-batch tools in the evaluations group, saying it is the ONLY tool that returns these. This makes selection 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?

Explicitly tells the agent when to use it (to obtain status/metrics), how to handle async runs (pass wait:true instead of polling), and references terminal statuses and llmContext guidance. Also implies this is for evaluation runs, vs batch tools for other groups.

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 safety profile is covered. The description goes beyond that by disclosing polling behavior ('wait: true polls until terminal'), enumerating the full status set (PENDING, PROCESSING, PROCESSED, FAILED, CANCELLED), and instructing the agent to follow llmContext guidance in results — all meaningful behavioral context not available from annotations alone.

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: the core purpose is in the first sentence, followed by focused behavioral notes. Every sentence earns its place, though the status enumeration overlaps somewhat with what an output schema likely already specifies. Slightly tighter than ideal, but very efficient overall.

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 batch-status polling tool with 5 well-documented parameters and a rich annotation set, the description is complete: it covers purpose, originating tool, polling semantics, terminal statuses, and result guidance. The output schema handles return-value details, and annotations handle the safety profile, so 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 schema fully documents all five parameters (wait, batchId, environment, waitSeconds, workspaceId), including enum constraints and format hints like bpr_... IDs. The description adds only the 'wait: true polls until terminal' usage hint, which is a minor complement rather than substantial new meaning. 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 uses a specific verb and resource: 'Get the aggregate status of an extract batch (extract group) submitted by run_extract_batch.' This precisely distinguishes it from sibling tools like get_extract_run (single-run status) and list_extract_runs (listing runs). An agent can tell what this tool is for 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?

The description clearly ties the tool to its companion producer, run_extract_batch, and gives concrete usage guidance for the wait parameter ('wait: true polls until terminal'). However, it does not explicitly name alternatives such as get_extract_run or cancel_extract_run, nor state when not to use this tool, leaving some routing 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 establish that this is read-only, idempotent, and non-destructive. The description adds useful behavioral context: results may include llmContext guidance to follow, and the tool can return either draft or version-specific configs. It does not cover permission or not-found behavior, but the safety profile is already handled by 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 three short sentences with the core behavior front-loaded, followed by discovery and result-handling guidance. The parenthetical '(extract group)' is slightly awkward and adds little clarity, but overall the text is compact and free of 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?

For a read-only getter with full parameter schema and an output schema, the description covers the main access patterns: draft configs, versioned configs, ID discovery via list_extractors, and following llmContext guidance. It does not mention list_extractor_versions for discovering version IDs, but the version parameter schema already documents the accepted version identifiers, so this is a minor 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%, so the schema already documents all four parameters, including the version forms and environment enum. The description adds a little meaning by mapping 'draft' to the draft config and suggesting list_extractors for IDs, but it does not substantially expand on the parameters.

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-resource pair and clearly distinguishes the two main cases: fetching an extractor's draft config or fetching a specific version's config. It also points to list_extractors for ID discovery, which helps differentiate this getter from the listing sibling.

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 concrete routing guidance: use list_extractors to discover IDs, and use this tool to get draft or versioned extractor configs. It does not explicitly state when not to use the tool, such as using list_extractor_versions to enumerate available versions, so it falls just short of full 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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral detail beyond annotations: wait blocks until terminal or budget expiry, repeated calls are required, and llmContext guidance in results should be followed.

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, followed by the most important behavioral nuance (waiting). Every sentence contributes value, and there is no redundant restatement of the title or schema.

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 input schema, annotations, and output schema, the description covers the essential operational details: what the tool does, how waiting works, and how to handle results. It could be slightly more explicit about when to choose this over related sibling tools, but it is otherwise complete for a read-only polling 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 all parameters are already documented in the input schema. The description adds useful context for the wait parameter and the overall polling pattern, but does not materially expand on runId, detail, environment, or workspaceId beyond what the schema 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 clearly states the tool retrieves the state and output of a specific extract run, with the added nuance of waiting on running runs or inspecting failed ones. This distinguishes it from list_extract_runs (listing), cancel_extract_run (canceling), and delete_extract_run (deleting).

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 on when to use this tool: to resume waiting on a running run or to inspect a failed one. It also explains the wait behavior and that repeated calls are needed to continue waiting, though it does not explicitly name alternative tools for list/cancel/delete scenarios.

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 substantial behavioral context beyond the annotations: the presigned URL expires in about 15 minutes and requires a re-call to refresh, null contents means 'not parsed yet' rather than an error, split-produced children carry parentSplit metadata, and llmContext guidance should be followed. This goes well beyond the readOnly/idempotent hints and meaningfully informs agent 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 compact and front-loaded with the core purpose, then adds only high-value caveats: expiry, parsed-content semantics, parentSplit metadata, and llmContext. Every sentence earns its place, and there is no filler or repetition of the schema.

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 file retrieval tool with a rich output schema and strong annotations, the description covers the important behavioral nuances an agent needs: URL expiry and refresh, contents semantics, parentSplit metadata, and following llmContext. Nothing critical for correct invocation or interpretation appears to be 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 meaning by clarifying that contents: null is a state, not an error, and explaining the freshness/expiry semantics of the returned URL. This supplements the schema's enum and descriptions without duplicating 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 names a specific verb and resource: get a file's metadata, presigned download URL, and optionally parsed contents. It also scopes itself to the files group, distinguishing it from related tools like list_files and get_file_upload. The purpose is immediately clear and distinct from 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?

The description gives clear context on when to set contents and explicitly tells the agent to run parse_document first when contents are null, which is useful routing guidance. It does not enumerate exclusions against every file-related sibling, but it provides enough direction for correct 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 mark it read-only/idempotent, and the description adds behavioral context beyond that: default is one instant status check, wait:true blocks until completion or budget expiry, and results may carry llmContext guidance to follow. This meaningfully informs agent expectations for polling and continuation.

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 no filler: the first states what it does, the second mandates when not to call it, the third explains the wait modes and result guidance. Every sentence carries operational value and the most critical info appears first.

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 a full output schema present, the description correctly focuses on invocation context rather than return fields. It covers the prerequisite (request_file_upload), the correct timing relative to the user message, wait semantics, and how to handle llmContext — everything an agent needs 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 the description repeats rather than extends the wait parameter's meaning ('true = block until the user completes...'). It adds no new parameter semantics beyond what the schema already provides, 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 names a specific verb ('Check'), the exact resource ('an upload link created by request_file_upload'), and the result ('uploaded file ids (files group)'). This clearly distinguishes it from siblings like request_file_upload (which creates the link) and get_file (which fetches an existing file).

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 states when to call ('on the user's message after they were shown the link'), includes a hard exclusion ('never in the same turn that shared it'), and explains the wait/default behavior and retry pattern ('call again to keep waiting'). This gives the agent a precise invocation rule.

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 important runtime behavior beyond the annotations: wait mode blocks until terminal state or budget expiry, repeated calls are needed to continue waiting, and results may include llmContext guidance. This is genuinely useful and not already captured by readOnly/openWorld/idempotent hints.

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: purpose first, then wait behavior, then operational constraints, then output guidance. Every sentence adds actionable information without waste.

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 input schema and the existence of an output schema, the description covers the important gaps: it tells the agent that there is no list endpoint, that run IDs must be retained, how waiting works, and that llmContext should be followed. This is complete for safe and 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 value by explaining the waiting loop ('call again to keep waiting') and framing wait behavior around terminal states and budgets, which enriches the wait/waitSeconds parameter semantics beyond the 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 clearly states a specific action ('Get the state and output of a form detection run') and names the exact resource type. It also distinguishes this tool from the broader sibling set by noting that form detection runs have no list endpoint, so this is the run-specific retrieval path.

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 operational guidance: use it to resume a running run, inspect a failed one, and call again to keep waiting when wait budget expires. It does not explicitly name alternative tools or state when not to use it, but the context is sufficient for an agent to pick it for form detection run status/output.

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 establish read-only, idempotent, non-destructive behavior. The description adds beyond those by explaining wait polling, terminal status names, and the instruction to follow llmContext guidance within results. This is meaningful behavioral context not encoded in the 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 short, dense sentences with no filler. The core purpose is front-loaded, and the status list plus llmContext note each earn their place as operationally useful details.

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 tool with a fully documented input schema and an output schema present, the description is complete. It covers the batch scope, polling behavior, statuses, and result-side guidance without over-explaining.

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 a small amount of semantic value by interpreting wait ('true polls until terminal') and naming the statuses, but it does not substantially expand on what each parameter means 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?

States a specific verb ('Get'), a specific resource ('parse batch'), and the aggregate nature of the status, while naming the submitting sibling tool run_parse_batch. This clearly distinguishes it from get_parse_run and other batch getters.

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 explains when this applies (batches submitted by run_parse_batch) and how the wait parameter changes behavior. It does not explicitly exclude alternatives like get_parse_run, but the aggregate batch framing plus the wait/polling semantics gives solid usage context.

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, non-destructive behavior, so the description's added details about wait-budget expiry, repeated calls to keep waiting, and following llmContext guidance provide genuine extra value. There is no contradiction with the 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 compact and front-loaded, with four sentences that each carry distinct information: purpose, wait behavior, output slicing, and result guidance. There is no filler or redundant restating of the tool name.

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 safety annotations, the description covers the key behaviors an agent needs: state retrieval, waiting, slicing, and follow-up guidance. A minor gap is that it does not explicitly differentiate from get_parse_batch, but the output schema and annotations fill most of the remaining context.

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. The description adds meaning by explaining the wait semantics, tying runId to parse_document/list_parse_runs, and referencing pageRange/maxChars/rawBlocks output slicing as in parse_document, which enriches parameter understanding 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 states a specific verb and resource: 'Get the state and output of a parse run (parse group).' It goes beyond a generic label by specifying the two typical goals — resuming a running run or inspecting a failed one — which makes the tool's purpose clear and distinct from listing or batch 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 clear usage context: runId comes from parse_document or list_parse_runs, wait: true blocks until terminal or budget expiry, and output slicing works as in parse_document. It does not explicitly name alternatives like get_parse_batch or state when not to use this tool, so it stops short of full exclusion 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?

It discloses polling behavior via wait, enumerates terminal/non-terminal statuses, and instructs the agent to follow llmContext guidance in results. Annotations already mark the tool readOnly and idempotent, so these additions build on rather than repeat structured metadata.

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 compact sentences deliver the core purpose, polling option, status vocabulary, and result guidance without wasted words. The most important info 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?

Given the annotations, output schema, and fully documented parameters, the description covers everything essential: what the batch status represents, optional polling, terminal statuses, and llmContext handling. Nothing critical for invoking 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 baseline is 3. The description mostly restates the wait parameter's meaning and adds mild context for batchId by referencing run_split_batch, but it does not substantially enrich parameter understanding 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?

Description clearly identifies the action (get aggregate status), the resource (split batch), and ties it to run_split_batch. It distinguishes an aggregate batch-level view from the singleton get_split_run by using 'aggregate status' and 'split group', though it does not explicitly name the sibling.

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 says this tool is for the batch submitted by run_split_batch and explains the wait polling option. It does not explicitly say when to prefer this over get_split_run, but the batch/run distinction is implied through 'aggregate status' and the referenced submission 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 readOnly, idempotent, and non-destructive behavior, and the description adds valuable extra context: wait blocks until terminal or budget expiry, repeated calls continue waiting, and llmContext guidance in results should be followed. 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 three short sentences with the core action front-loaded, followed by targeted wait behavior and a notable open-world instruction. Every sentence earns its place with 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?

For a polling-style read tool, the description clearly covers the wait loop, terminal/budget timeout, and result-related guidance. The rich schema and output schema carry most parameter and return-value detail, leaving only minor ambiguity about what 'terminal' means in this context.

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