JustFill PDF Form Automation

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

Beyond the annotations, the description discloses immediate persistence in the active workspace, invalidation of prior visual review receipts for ML-detected layouts, and that saved account templates are not altered unless save_template is called. It also describes the created field ID convention and source/confidence 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?

The description is front-loaded with purpose, then coordinates, persistence impact, and usage routing. Despite its length, every section serves a clear function for a 10-parameter mutation 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 tool's complexity, 10 parameters, annotations, and output schema, the description provides enough context to invoke it correctly. It covers purpose, coordinate semantics, side effects, and alternatives without needing to explain the output schema in detail.

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, including coordinate ranges, field_type values, alignment options, page_index, and workspace_id. The description reinforces allowed values and adds that coordinates are read off render_preview, but it does not add much parameter meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb, resource, and condition: create a new fillable field on a page when detection missed an input. It clearly distinguishes the tool from sibling update/remove 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 'When to use' section explicitly says to use add_field only for missing fields, and it names update_field, update_fields, remove_field, and remove_fields for their respective cases. This leaves no ambiguity about 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 declare destructiveHint=true and idempotentHint=true, but the description goes further by enumerating what is destroyed (workspace record, source PDF, previews, output PDF), what survives (saved templates, downloaded files), and the 24-hour TTL context. It also explains idempotency semantics via already_closed=True, which is more concrete than the hint alone; only the return payload shape is left to the output 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?

Front-loaded with the action and destruction list, then a clearly separated usage block; every sentence carries information. Minor bloat from inline code formatting and parenthetical callouts (e.g. the doubled backticks around finally) that reads as documentation style rather than agent-facing 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 one-parameter destructive cleanup tool with annotations and an output schema, nothing essential is missing: destruction scope, retention exceptions, idempotency, TTL behavior, and call ordering are all covered, leaving only the return structure to the output 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?

With 100% schema description coverage and a single parameter, the schema already defines workspace_id and its origin in open_pdf's summary. The description reinforces this by tying the ID to lifecycle effects (closing invalidates download_url/preview_url), but adds no new syntax or format guidance, 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?

States a specific verb (delete/close) and resource (one temporary workspace plus its stored PDF, preview images and output PDF), and immediately delimits scope by noting saved templates and already-downloaded files are untouched. That negation distinguishes it from sibling mutation tools like remove_field or save_template without needing 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 explicit 'When to use' block gives an ordering prerequisite: only after the user has received the filled PDF from fill_pdf and, if applicable, after save_template. It also states the consequence of calling early (download_url and preview_url become invalid), which is exactly the when-not guidance an agent needs.

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 this is destructive, non-read-only, and non-idempotent; the description adds substantial behavioral context beyond that. It discloses download-link expiry, flatten/fillable precedence and entitlement effects, watermarking semantics, warning behavior, editable-widget meaning, and the ML-layout visual review gate.

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

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

The description is front-loaded with the core action and then structured into parameter behavior and workflow-routing sections. It is dense and somewhat repetitive of schema content, but the length is largely justified by the tool's complexity.

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 an output schema exists, the description need not explain return values, and it covers the critical workflow constraints, entitlement effects, preview prerequisites, and download lifecycle. An agent has enough context to invoke the tool correctly without needing external assumptions.

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 the parameters thoroughly, and the description adds only marginal semantics such as flatten=False not creating fields on scans and fillable precedence. The checkbox value syntax is repeated from the schema rather than adding new parameter 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 states a specific verb and resource: fill the PDF and return a download link. It also distinguishes the final generation step from preview and workspace-closing siblings by explicitly naming render_filled_preview and close_workspace.

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

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

It gives explicit workflow routing: use render_filled_preview first, call fill_pdf only when ready, and for ML-detected layouts require prior render_preview and render_filled_preview calls. It also names a when-not condition via the required_calls behavior and warns not to close the workspace before download.

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 and destructiveHint=false, yet the description still adds real context: it states that results reflect in-workspace edits made by add/update/remove/prune_field(s), and it describes the confidence and needs_name_review attributes. This tells the agent the output is live state, not a static snapshot.

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

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

Front-loaded with the core action, then return shape, filtering, and usage guidance in a scannable structure. The enumeration of every field-entry key partly duplicates the output schema, making it slightly longer than necessary.

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 annotations, a 100%-covered two-parameter schema, and an output schema present, the description covers everything an agent needs: scope, edit reflectivity, page filtering, and sibling routing. No gaps remain for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by framing page_index as the all-pages-vs-single-page toggle and tying workspace_id to an active, already-opened workspace. It largely reinforces rather than extends the schema text, which keeps it below a 5.

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 ('List the current working fields and workspace summary') plus the scope ('open PDF workspace'). It explicitly distinguishes itself from open_pdf and list_templates, so an agent can pick it without opening any schema.

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

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

A dedicated 'When to use' block names the exact scenarios (inspecting IDs/coords/labels in an already-open workspace, after edits, or narrowed to one page) and routes the agent to the two siblings for other cases. No inference is required.

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=true, destructive=false, and openWorld=false, but the description adds authentication scope, ordering behavior, default limit, return fields, and workspace independence. That is substantive behavioral context beyond annotations.

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

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

Front-loads the purpose, then tight sections for ordering/limit and when-to-use guidance. The list_fields contrast includes a bit of field detail, but it earns its place by preventing a likely sibling mix-up.

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

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

This is a low-complexity read tool with an output schema, rich annotations, and a complete description covering scope, ordering, limit, authentication context, and sibling differentiation. Nothing material 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%, and the only parameter, limit, is already fully documented with its default and meaning. The description repeats the default and adds ordering context but little parameter-level 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?

States a specific verb and resource: list saved, reusable form templates on the authenticated account. It explicitly contrasts with list_fields, so an agent can distinguish it from the sibling 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?

Gives explicit when-to-use guidance and a clear do-not-confuse rule with list_fields. It also states that no open workspace is required, which is a useful selection constraint.

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 mutability and open-world hints; the description adds the substantive traits: the deterministic -> AcroForm -> ML resolution order, that detection is page-limited with unprocessed_page_indices reported, and that the workspace_id expires in 24 hours. It also warns that rebuilt/compressed files break field detection and that large base64 gets truncated.

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

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

Front-loaded purpose followed by a bulleted source selector and a usage block, so the structure is easy to scan. It repeats the base64 size/truncation caveat from the schema and the max_pages behavior, which is mild redundancy but not damaging.

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

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

An output schema exists, so return values need no explanation, and the description still names the key return field (summary.workspace_id) and its lifetime. For an 8-parameter, nested, open-world ingestion tool, nothing an agent needs in order 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 coverage is already 88%, yet the description still adds value the schema cannot: the exactly-one-source constraint with a resolution-order rationale, the guidance that a file lacking download_url must use upload_token, and the ~200 KB base64 limit with the reason. This is meaningfully more than the field-level 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?

States a specific verb and resource ("Open a PDF ... and detect its fields") and immediately names the accepted variants (JPG/PNG/TIFF). It is clearly distinguishable from siblings like list_fields and request_file_upload, which are called out by name.

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 closing "When to use" block explicitly says to call it once to load a document and initialize a workspace, and routes to list_fields for re-reading and list_templates for browsing templates. It also names the re-invocation conditions (larger max_pages or force_detect=True).

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, but the description goes well beyond that: it explains the all-None rejection guard, the AND-semantics of criteria, strictly-less-than thresholds, the exclude_ids allowlist as a safety mechanism, the exact return payload for auditability, reversibility via add_field, and that saved templates are untouched unless save_template is called. That is exactly the extra context the annotation bar asks for.

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

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

Front-loaded with the destructive action and the guardrail, then structured into a semantics block and a 'When to use' block. Some threshold-range phrasing repeats the schema, so it is a touch longer than strictly needed, but nearly every sentence carries 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?

For a 7-parameter destructive bulk operation, the description covers the dangerous edge case (empty criteria), safety valves (exclude_ids), matching semantics, side effects on templates, and even the return shape despite an output schema existing. Nothing an agent needs before invoking it destructively is missing.

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

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

Schema coverage is 100% and already documents each parameter's units and ranges, so the baseline is 3. The description adds value the schema does not: that criteria are conjunctive (ALL non-None filters must match), that at least one must be supplied, and how exclude_ids overrides matching. Marginal duplication of the percent/threshold semantics keeps it at 4 rather than 5.

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 line states a specific verb+resource+scope: bulk-delete fields matching ALL criteria in the active workspace, framed as detection-noise cleanup. It is immediately distinguishable from remove_fields/remove_field, which the description names explicitly.

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?

A dedicated 'When to use' block names both alternatives (remove_fields for explicit ID lists, remove_field for a single ID) and the condition that selects each. It also flags the scenario class (tiny table cells, low-confidence boxes) where this tool is the right choice.

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

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

Goes well beyond destructiveHint=true by disclosing exact return payloads for both the success and unknown-id cases, stating deletion is permanent within the active workspace, specifying recovery paths (add_field, open_pdf), and noting the scope boundary that saved templates are unaffected unless save_template is called.

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

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

Front-loaded with the destructive action and its permanence before any conditional detail, and the bulleted alternative routing is easy to scan. The inline JSON return snippets are somewhat verbose given an output schema exists, which keeps it just under top marks.

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 two-parameter destructive tool with full annotation coverage and an output schema, nothing an agent needs is missing: scope, permanence, recovery, error behavior, and sibling routing are all present. Return-value detail is technically redundant with the output schema but does not detract.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds value: it ties field_id to a single false-positive box, defines the unknown-id outcome, and clarifies that removal is scoped to workspace_id's active workspace. It stops short of syntax examples, which the schema already supplies ('p0_f3').

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 ('Permanently delete a single false-positive field') and bounds it by workspace and field_id. The singular scope is explicitly contrasted with the plural and rule-based siblings, so an agent can distinguish it from remove_fields and prune_fields 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 an explicit 'When to use' block: remove_field for one specific field, remove_fields for 2+ known ids in a batch, prune_fields for rule-based filtering by named criteria. Each alternative is named with the condition that selects it, leaving nothing to inference.

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

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

Annotations only declare destructiveHint=true; the description goes well beyond that by disclosing irreversibility, the recovery paths (`add_field`, `open_pdf`), that saved templates are unaffected unless `save_template` is called, and the partial-failure rule that unknown IDs are silently skipped rather than erroring. It also states the returned counts and sorted `unknown_field_ids`, which is exactly the behavioral detail an agent needs before a destructive batch call.

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

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

Front-loaded with the destructive action and scoped alternative routing, then grouped into a labeled semantics paragraph and a bulleted 'When to use' list. Slightly dense in the middle block, but every sentence carries operational information; 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 destructive two-parameter batch tool with an output schema present, the definition covers safety, irreversibility, recovery, partial-failure behavior, and sibling routing. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds batch-level meaning the schema does not — that valid IDs are still committed when some IDs are unknown (no error raised for the batch), and where `workspace_id` comes from. Some overlap with the schema's dedup/unknown-ID notes, but the partial-failure framing is genuinely new.

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 ('permanently delete multiple fields by ID'), plus scope ('from the active workspace in a single batch mutation'). It explicitly distinguishes itself from both `remove_field` (single) and `prune_fields` (criteria-based), so an agent can select it without opening any schema.

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

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

The 'When to use' block gives an explicit selection rule (2+ known false-positive IDs), names both alternatives by name, and describes the condition that routes to each (`remove_field` for one ID, `prune_fields` for confidence/size/type/page criteria). Nothing is left to inference.

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

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

Goes well beyond the annotations: discloses zero cost, that rendering uses the same code path and flatten/fillable flags as the export, and crucially what is NOT simulated (watermarks, account limits). Also notes client-side image rendering limits (ChatGPT) and restricted-data rejection, which annotations do not cover.

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

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

Front-loaded with the core purpose and cost in the first two lines, then structured bullets for usage. Every sentence carries operational information (flags, return keys, restricted data, client rendering) 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?

No output schema exists, but the description fully documents the return payload (fit, warnings, preview_url) and the cost/safety model, so an agent has everything needed to call and interpret the result.

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 real value: it restates the checkbox convention and stresses that flatten/fillable must match the later fill_pdf call, a cross-tool constraint not evident from the schema alone. It does not explain page_index or workspace_id beyond the schema, so it falls just short of 5.

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 states a specific verb and resource ('Preview how the filled page will look') and anchors it relative to a named sibling ('before fill_pdf'). An agent can immediately distinguish it from render_preview and fill_pdf.

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 'When to use' block explicitly names the three relevant siblings and the condition selecting each: render_filled_preview for values/placement, render_preview for empty bounding boxes, fill_pdf for the final download. It also states the preview is required for populated pages on ML-detected layouts.

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

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

Goes well beyond the annotations by disclosing a side effect they don't cover: it records a field-layout visual review receipt for page_index that gates fill_pdf/save_template on ML layouts. It also explains the color-band legend and the client limitation where tool images aren't displayed, so the agent knows to surface preview_url.

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

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

Front-loaded with the core action, then legend, then return-value caveat, then a clearly delimited 'When to use' block. Every sentence carries operational information 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?

With no output schema, the description still explains the return (image plus preview_url) and its client-display caveat. The gating side effect, alternatives, and trigger conditions are all covered, leaving nothing an agent needs 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 baseline is 3, but the description adds meaning: page_index is not just a render target, it is the page whose visual review receipt gets recorded and required downstream. workspace_id is left to the schema, which documents it adequately.

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 (render a page with field boxes drawn) and immediately frames the goal (verify placement). It explicitly distinguishes itself from the sibling render_filled_preview, so an agent can route between the two 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?

Provides an explicit 'When to use' section: inspect empty boxes before filling or after geometry edits via add_field/update_field/remove_field/prune_fields, and a named alternative (render_filled_preview) for value/overflow checks. The prerequisite for fill_pdf and save_template is also 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?

Goes well beyond the annotations: discloses that the slot is single-use, expires in 30 minutes, rejects payment-card data, PHI, government IDs, passwords, API keys and MFA/OTP codes, and warns that re-encoded bytes (base64, shrunk files) break detection. Its three return artifacts (upload_url, post_url with a concrete curl example, upload_token) are explained in operational terms. Only gap is that permission/auth requirements for creating the slot are unstated.

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

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

Front-loaded with the purpose and the fallback condition, then organized into returns and a when-to-use list. It's long, but for a multi-step fallback flow most sentences carry real information. Minor deductions for the awkward mid-sentence line breaks and for restating return values that the output schema already covers.

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?

Annotations cover the safety profile and an output schema exists, yet the description still supplies the failure modes (stale bytes, expired slot, sensitive content) and the exact wiring into open_pdf that an agent needs to complete the flow without trial and error.

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?

Zero parameters, so the schema has nothing to document and the baseline is 4. The description doesn't invent redundant parameter talk and instead spends its words on outputs and gating conditions, which is the right allocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — "Create a one-time upload slot for a PDF (or form photo)" — plus the precise condition that gates it: "when direct file input is unavailable." That condition alone separates it from open_pdf and every other sibling in the list.

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?

An explicit "When to use" block names the two preferred paths (open_pdf(file=...) with a download_url, open_pdf(url=...) for a public link) and restricts this tool to the fallback case, then closes the loop by telling the agent to feed the returned upload_token back into open_pdf. Both the when and the when-not are stated, with the alternative tool named.

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 a safe non-destructive write; the description adds the real behavioral payload: templates capture field names so later sessions map by meaning rather than coordinates, false positives present at save time get baked in, and unreviewed pages are a documented precondition. It also discloses the downstream consequence (confidence 1.0, no ML pass), which is exactly the context annotations cannot 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?

Front-loaded with the effect and its consequence, then a clearly separated 'When to use' list. Slightly long and heavy on backticked identifiers, but every sentence carries operational information rather than 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 two-parameter persistence tool with an output schema already defined, the description covers the effect, the preconditions, the ordering against sibling mutation tools, and the alternative for inspection. Nothing needed 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% and both parameters are well documented in-schema, including the pointer to open_pdf's summary.workspace_id. The description's use of 'name=...' refers to field names set via update_fields rather than the template `name` parameter, so it adds no extra semantics about the two arguments themselves. 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 opening sentence states a specific verb and resource ('Persist the reviewed field layout') and immediately defines the observable effect: a future open_pdf of the exact file returns these fields with confidence 1.0 and no ML pass. That distinguishes it cleanly from siblings like update_fields (in-session edit) and list_templates (read-only listing).

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?

An explicit 'When to use' block states the trigger (after filling, only when the user confirms), the class of edits persisted (add_field, update_field, remove_field), and names the alternative for viewing saved templates (list_templates). It also gives ordering prerequisites: remove false positives with remove_fields/prune_fields first, and review every page via render_preview for ML-detected layouts.

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, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered structurally, and the description adds real context: patch semantics for non-None params, ML-to-agent source promotion with confidence=1.0, immediate persistence, review-receipt invalidation on geometry changes, and template isolation unless save_template is called. It also discloses the error return shape for a missing field_id. However the destructiveHint=true annotation is never reconciled in prose -- the description presents this as a routine patch without warning that a field's geometry or type can be irreversibly altered, which is the one behavior an agent most needs spelled out 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?

Front-loaded with the core action, then organized under labeled blocks (Overwrite/merge, Persistence & review impact, When to use) that let an agent scan to the relevant concern. It runs long for a single-field update, and the parameter list is enumerated twice (in the header sentence and again in the patch paragraph), which is mild redundancy.

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

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

An output schema exists, so return values needn't be described, yet the description still notes the updated-field dict and the error variant. With ten parameters, a destructive mutation, and cross-cutting effects on review receipts and templates, every consequence an agent needs before calling is present.

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 already documents its range and None semantics, so the baseline is 3. The description earns above baseline by stating the unifying rule that ties all eight optional params together -- only non-None values overwrite, everything else is preserved -- which is a cross-parameter contract the per-field schema text cannot express, plus the conditional side effect on source/confidence tied to field_type edits.

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 plus the full attribute set that can be modified ('position, size, semantic name, type, or alignment'), and scopes it to 'the active workspace'. It is immediately distinguishable from add_field, remove_field, and update_fields, all of which are named with their own trigger conditions.

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?

A dedicated 'When to use' block states the single-field case explicitly and routes three alternatives: update_fields for 2+ fields in one call, add_field for missing fields, remove_field for false positives. Both the inclusion condition and the exclusion conditions are given, leaving nothing to inference.

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

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

Beyond the annotations (destructiveHint=true, openWorldHint=false), the description discloses partial-failure semantics: unknown field_ids are skipped and reported while valid updates apply, but an invalid field_type/align/vertical_align aborts the whole batch with no partial save. It also explains ML-to-agent promotion with confidence=1.0 and that edits persist to the workspace but not to templates unless save_template is called.

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

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

Front-loaded with purpose, then semantics, then a scannable 'When to use' list — well organized. The literal dict sketch of update keys duplicates the schema's list of the same fields, costing a line of 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 destructive batch mutation, the description covers atomicity, skip-vs-abort behavior, persistence scope, and template interaction; an output schema exists so return-shape detail is unnecessary, and it still names the key result keys (updated, unknown_field_ids).

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 already 100%, so baseline is 3; the description adds the non-obvious semantic that omitted keys preserve existing values and that editing an ML field flips source to agent. The inline item-shape sketch largely repeats the schema's own enumeration of allowed values, so it earns 4 rather than 5.

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 gives a specific verb and resource ('Batch-update multiple existing fields in the active workspace') plus the batching scope, and later text explicitly distinguishes it from update_field and add_field. An agent can route between the three 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?

A dedicated 'When to use' block states the selection rule ('prefer update_fields ... whenever ... 2 or more fields at once') and names the alternatives for the single-field and create cases. Exclusions and alternatives are explicit, not inferred.

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