Typebar (formerly SuperDocs)

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

With no annotations, the description carries the full burden and does so well: it discloses that approved changes apply atomically, denied changes are discarded, the AI may revise on feedback next turn, and the job resumes to status=completed. It does not explain the 'authorization' parameter or any permission requirements, so a small gap remains.

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 trigger condition and the core decision semantics, then adds workflow context. It is somewhat long and has mild redundancy (approved/denied restated), but every section addresses a distinct invocation concern rather than padding.

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

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

No output schema exists, and the description compensates by stating the downstream effect (changes apply/discard, job resumes and reaches status=completed). Combined with coverage of the single/batch modes and the regulated-workflow requirement, an agent has everything needed to call this 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 71%, so the schema already documents most parameters. The description still adds value by explaining the single-change path (approved + optional feedback) versus the batch path ('changes' array with per-change decisions), including the semantics of feedback as revision input. It does not clarify the undocumented 'authorization' parameter.

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+resource (approve/deny each proposed change) and ties it explicitly to the sibling chat_async under approval_mode='ask_every_time', so it is clearly distinguishable from the dozens of other session/job tools. An agent understands exactly what this does 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 triggers (approval_mode='ask_every_time', regulated workflows requiring every edit to be reviewed) and breaks down single-change vs batch-change invocation. The alternative paths (per-change vs 'changes' array) are named rather than 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?

With no annotations, the description carries the full burden and does so richly: it discloses soft-archive recoverability, the precise 409 conflict semantics with error code, open_in_sessions count and suggested_action, side effects under force (unlinks every session, notifies other sessions), and the invariant that a 2xx always means the archive happened. This is exactly the behavioral context an agent needs.

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 core action and the failure/recovery flow in a logical order. Some redundancy: the force/409 behavior is restated in the closing 'no-op never wears a success status' paragraph and duplicates the force parameter's schema description, though the emphasized lines still earn most of their space.

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 and no annotations, so the description must cover the full behavioral profile — and it does cover errors, side effects, and the force contract well. It falls short only on the uninstrumented document_id/authorization parameters and on clarifying the 'saved document' vs session-document distinction.

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?

Coverage is 50%. The description reinforces the force flow (which the schema already documents) and adds meaning to from_session via 'unlinks every session,' but says nothing about document_id or authorization, leaving two of four parameters undocumented in both schema and description.

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 precise verb+resource ('Soft-archive a saved document') and immediately distinguishes it from deletion semantics by noting the doc 'leaves the Files view but is recoverable server-side.' This differentiates it clearly from destructive siblings like delete_attachment and routes to unarchive_document conceptually.

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 strong operational guidance on the force flow — when the call fails (409), why, and how to re-call with force=true — but never names or contrasts an explicit alternative sibling (e.g., unarchive_document, close_session_document) or states when NOT to use 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?

No annotations are provided, so the description carries the full burden and does so well: it discloses what is destroyed (pending/staged changes), what survives (already-applied changes), the dual-mode response (stop_state stopped_here vs accepted), the required polling loop with a concrete termination condition (metadata.stopped_unwound or terminal status), and the 409 error 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?

Purpose is front-loaded in the first sentence, then behavior, then usage, then response semantics. Dense but nearly every clause adds operational value. Slightly long middle sentence about stop_state could be tightened, but nothing is 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 annotations and no output schema, the description still conveys the mutation semantics, the response shape, and the async polling protocol, which is the critical missing structured data. The main residual gap is the undocumented authorization parameter and how to obtain a valid job_id.

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 0% for both parameters. The description never explains job_id (format, where to obtain it — presumably list_jobs/get_session_jobs) nor the optional authorization parameter, which is entirely unaddressed. With zero schema coverage, this is a real gap the description should have filled.

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+resource — stops a running turn or ends a turn awaiting review by discarding staged changes — and clarifies the scope boundary (applied changes preserved, pending changes discarded). This is immediately distinguishable from siblings like get_job, list_jobs, or approve_change.

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 names the triggering conditions (user changed their mind, retry with different parameters or model_tier) and the negative case (a turn that already finished cannot be stopped and returns 409). It also routes the agent to the correct follow-up action by naming get_job as the polling tool for the accepted case.

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

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

With no annotations, the description carries the full behavioral burden and does so: it discloses cross-turn document persistence, the drift risk of describing content in `message`, billing granularity (one operation per modifying turn, per 25 sections for large edits), the response payload shape (reply text plus structural changes with chunk IDs), and the compact-mode token trade-off.

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 front-loaded: capability statement, then document_html handling, then billing, then alternatives, then optional params. Nearly every sentence adds operational value, though the compact-mode guidance is partly restated from the schema and the prose runs long for a single 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?

For a 19-parameter mutation tool with an output schema, the description covers what an agent needs: session/document handling, billing, async alternative, response shape, and optional tuning parameters. Nothing material to correct invocation is missing.

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

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

Schema coverage is 95%, so the schema already documents most parameters and the baseline is 3. The description adds real semantic value on top: when document_html must be sent versus omitted, the verbatim-vs-authored distinction, and why response_mode='compact' is recommended for agents — beyond what the enum and field docs state.

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 ('Synchronous AI chat') and enumerates concrete capabilities (rewrite paragraphs, add/remove table rows, restructure sections, generate content, transform document). It also explicitly distinguishes itself from the sibling chat_async, so an agent can route 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?

Gives explicit when-to-use rules: pass document_html only to load/replace and omit it on follow-ups, use upload_document_base64 or verbatim document_html for exact content, use chat_async for long-running or human-in-the-loop edits, and set response_mode='compact' for large documents. Alternatives and exclusions are both 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?

No annotations are provided, so the description carries the full burden and does so: it discloses that the call returns a job_id immediately rather than blocking, that job state is durable across server restarts, that polling happens via get_job and approval via approve_change, and that compact mode trades full HTML for per-section chunk_diffs. The verbatim-load vs AI-authored-content distinction is a non-obvious behavioral trap it proactively warns about.

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 routing decision, which is the highest-value sentence, and every later sentence covers a distinct concern (verbatim loading, polling, approval, compaction, HITL steps). It is a dense single block with no paragraph breaks, so it reads as a run-on and repeats the compact-mode explanation that also lives in the schema; a 20-parameter async tool justifies the length, but tighter structure would help.

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, yet the description still supplies the one thing an agent needs to act on the response — that it returns a job_id and must be polled via get_job. Combined with the approval loop, the durability guarantee, and the token-saving guidance for large documents, 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 coverage is 95%, so the baseline is 3, and the description earns above that by explaining the semantic difference between passing content in document_html (verbatim load, never re-typed) versus describing it in `message` (AI authors it, can drift) — a distinction the schema does not draw. It also motivates response_mode, approval_mode, model_tier, thinking_depth, and image_attachments, though it stays silent on cross_session_*, touched_chunk_ids, deleted_part_chunk_ids and cursor_context.

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 (async chat turn) and immediately distinguishes itself from its sibling: 'Use instead of chat when...'. The three qualifying conditions (large/multi-step edit, per-change approval, non-blocking need) let an agent route between chat and chat_async 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?

Explicit when-to-use conditions (a)(b)(c), a named alternative (chat), a recommendation keyed to document size (>20 pages → response_mode='compact'), and a numbered HITL workflow for approval_mode='ask_every_time'. This is as close to prescriptive routing as a description gets.

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?

With no annotations, the description carries the full burden and does well: it discloses the owner-scoping restriction (a caller can only clear its OWN note), the destructive nature of the operation, and idempotency semantics (removed=0 if it didn't exist). It omits any mention of authentication requirements despite an authorization parameter.

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 tight sentences, front-loaded with the action and scope, followed by the parameter modes and the idempotency caveat. 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?

No annotations and no output schema, so the description must cover behavior, and it covers deletion scope, ownership constraints, and the removed return value. The unexplained authorization parameter is the remaining gap for a delete 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 50%: memory_key is well documented in the schema and the description reinforces it with account-level vs per-customer framing. The authorization parameter is undocumented in both places, so the description does not fully compensate for the coverage gap.

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 (caller's cross-session memory note), and immediately clarifies scope: account-level vs a single end-customer's note. No sibling tool does anything comparable, so the agent can place it precisely 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 clear conditional guidance for the two invocation modes: omit memory_key to clear the account-level note, supply it to clear one end-customer's note. It does not name an alternative tool or state when not to use it, but the mode selection is unambiguous.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly: it discloses that the close is immediate and persisted, that persistence is best-effort with failures logged rather than fatal, how focus is transferred (next_focus if still open, else next remaining), and that closing the last document leaves the session empty. This is exactly the side-effect and failure-mode context an agent needs for a mutation with zero annotation 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?

Two tight paragraphs: behavior first, persistence caveat second, with the key action and the focus fallback chain front-loaded. Nearly every sentence earns its place, though the phrasing is dense enough that a small trim would still preserve all signal.

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 parameterized mutation with no output schema, the description explains side effects, focus behavior, and the returned roster + HTML, which is sufficient to call it correctly. The only material omission is any mention of the authorization parameter.

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 low (20%, only include_html documented), so the description must compensate. It usefully explains document_id's role and the otherwise-undocumented next_focus selection logic, and the return payload covers the output side. But it adds nothing about authorization or session_id, leaving part of the coverage gap unfilled.

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 ('Remove document_id from the session's open documents') and anchors it to a concrete UI metaphor ('the tab close button'), making the operation instantly recognizable. The contrast with siblings like archive_document or focus_session_document is implicit but unmistakable given the 'open documents' 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?

Usage is implied through the tab-close framing and the note that a later reconnect/restore won't restore the document, which signals intent. However, it never names an alternative (e.g., archive_document for durable removal) or states when-not to use this tool, leaving 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?

With no annotations, the description carries the full burden but discloses strong behavioral detail: continue=true resumes with a fresh time/step budget, continue=false stops while keeping everything applied so far, and the job reaches status=completed. It omits auth/permission requirements despite an authorization parameter being present.

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?

Information-dense but well front-loaded: the trigger condition comes first, then the action, then the exclusion. Every sentence carries operational weight, though the multi-line flow is slightly long for what is essentially a poll-then-post pattern.

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 resume/stop control on an async job with no output schema and no annotations, the description covers the full lifecycle (pause detection, resume, stop, terminal status). The remaining gap is the auth requirement and what session_id must reference.

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 only 50%, so the description must compensate. It clarifies continue's two outcomes ('fresh budget' vs 'work so far is kept') beyond the schema's own text, and ties job_id to the awaiting-decision state, but leaves session_id and authorization undocumented in both places.

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+resource (resume a paused async chat job awaiting a continue decision) and explicitly names the sibling it is not (approve_change). An agent can distinguish it from get_job, cancel_job, and approve_change 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?

Gives an explicit trigger condition to poll get_job until status=awaiting_approval AND metadata.awaiting_kind='continue_prompt', then act. It also names the alternative endpoint (approve_change) and states the exclusion that this tool 'can only act on a continue-prompt pause'.

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?

With no annotations, the description carries the burden and does well: it discloses the context effect, the job-cancellation side effect, and the dual-ID acceptance. It omits whether removal is reversible, whether the underlying stored file is destroyed, and what authorization is required despite an authorization parameter existing.

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 primary effect, then usage scenarios, then the parameter caveat. Every sentence adds distinct information with no padding.

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

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

For a mutation tool with no annotations and no output schema, the description covers the key behavioral effects and the tricky ID semantics. It is slightly incomplete on irreversibility/storage fate and the undocumented authorization parameter, but nothing critical to invoking 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 0% across 3 params, so the description must compensate. It adds real value for attachment_id (may be the final attachment ID or the job ID during processing), but says nothing about session_id or the authorization parameter, leaving part of the surface undocumented.

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 (Removes) and resource (the attachment from the session) and immediately clarifies the downstream effect on the AI's context. It also distinguishes itself from the job-oriented siblings by noting it cancels the underlying job when processing is still in progress.

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 three concrete use cases (free context, remove sensitive files mid-session, replace a stale reference document), which is clear guidance. It stops short of naming explicit alternatives/conditions such as when to call cancel_job or close_session_document instead, so it is not a full 5.

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

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

With no annotations present, the description carries the full burden and does disclose a lot: soft-delete semantics, the ownership authorization requirement, disappearance from list_user_templates, loss of AI referenceability, and that existing drafted documents are unaffected. It still omits reversibility/restore behavior and any response/error semantics.

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 core action and its soft-delete nature, then layers the authorization constraint and side-effect scope. Every clause adds distinct information with no 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 two-parameter mutation tool with no annotations and no output schema, the description covers the important behavioral surface (ownership, listing, AI reference, existing documents). The main residual gaps are parameter-level detail and success/error behavior.

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 0% for both parameters, so the description must compensate but largely does not. It supplies no format or meaning for template_id and does not explain the authorization parameter (anyOf string/null), beyond an indirect hint that owner authorization is required.

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 ('Soft-deletes the template') and goes beyond the name by marking it as a soft delete and naming the sibling it affects (list_user_templates). An agent can tell exactly what happens and how it differs from a hard delete.

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 clear usage context: only the owner (user or organization) may call it, and it removes the template from listing and AI reference. However it names no explicit alternative or when-not-to-use condition, so there is room beyond straightforward 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?

With no annotations, the description carries the full burden and does so well: it discloses the MCP return contract (binary formats yield a short-lived signed download_url in a JSON envelope; text formats return inline), the strict vs compat fidelity semantics, and the default docx behavior. It omits permissions/auth requirements and any note on side effects or rate limits, so it is strong but not exhaustive.

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 and front-loaded: fidelity/preservation claim first, then modes, then formats, then the MCP return behavior. Every sentence carries information, though the fidelity marketing line and the format enumeration make it longer than strictly 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?

For a complex 8-parameter tool with nested options and no output schema, the description compensates by explaining the return envelope and format-dependent output. It stops short of covering the upload_id large-payload flow or error behavior, which the schema alone carries, leaving a small 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 already 88%, so the schema documents most parameters. The description still adds value by explaining the mutual-exclusion relationship between html and session_id, clarifying that 'doc' is a legacy HTML alias (not stated in the enum description), and characterizing the docx default for downstream processing.

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 precise verb+resource (export a document) and goes further, naming the two input modes (html for ad-hoc content, session_id for session state) and the exact fidelity behaviors preserved (tables, borders, shading, headers, footers, images). It also positions itself against naive HTML-to-docx converters, so an agent can distinguish it from generic conversion utilities.

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 clear routing guidance for the two modes ('pass html directly... OR pass session_id') and per-format advice ('docx... best for programmatic processing or mail merge'). It does not name sibling alternatives such as request_download_url or get_document_detail, nor state when NOT to export, so it falls short of a 5.

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

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

No annotations are supplied, so the description carries the burden; it does disclose a real side effect (the outgoing focused document is persisted into the session's document map) plus the return content. However, it states unconditionally that the call 'returns the now-focused document's HTML', which conflicts with include_html defaulting to false (token-light ids/title/section count only). Auth requirements are also unaddressed.

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 with the core action stated first and the id semantics and side effect following. The parenthetical asides are dense but each carries information; nothing is padding.

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

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

For a mutation tool with no annotations and no output schema, the description does cover the state change and the return channel. It still leaves the HTML-vs-token-light return behavior ambiguous despite include_html existing, and says nothing about required authorization, so an agent could easily expect a payload it will not receive by default.

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

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

The description adds genuinely useful semantics for document_id — that either a session slot id or a durable_document_id UUID is valid — which the bare 'Document Id' schema title does not convey. But with only 25% schema coverage it leaves session_id and authorization unexplained, and its unconditional 'returns ... HTML' claim overrides rather than supports include_html's documented default of false.

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?

Names a specific verb+resource ('Make document_id the focused document') and immediately defines what 'focused' means in operational terms: the editor's active document and the default edit target. It is clearly separable from siblings such as open_documents, close_session_document, and list_session_documents.

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?

Explains which identifier forms are accepted and where to obtain them (the session slot id, or the permanent UUID surfaced by list_documents/Files and returned as `durable_document_id` by list_session_documents). This is concrete routing guidance, but it never states when to prefer this over open_documents or close_session_document, so no true alternatives/exclusions are given.

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

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

With no annotations, the description carries the burden well: it discloses that an `sk_` key is required, that the operation is a status check, and that human adoption preserves both work and the API key while enabling payment/upgrade. It does not explicitly state read-only/no-side-effects, but the 'check' framing and account-state descriptions are informative.

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 status-check purpose is front-loaded and concise. The subsequent upgrade/handoff instructions are longer and somewhat tangential to merely checking status, but they earn their place by explaining what to do when operations are low.

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 a simple one-parameter tool with an output schema, the description covers purpose, authentication, usage timing, and account-reuse/upgrade edge cases. Nothing essential for calling it correctly 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 description coverage is 0% for the single `authorization` parameter, but the description compensates by saying 'Call this with your `sk_` key,' which explains the required credential despite being technically optional in the schema. It does not add further format details, but for one parameter this is adequate.

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: 'Check your Typebar account status: tier, monthly operations used/remaining, and ... whether a human has adopted it.' It clearly distinguishes this informational account-status check from sibling tools like request_limit_increase or health.

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 clear usage contexts: use before doing work to confirm operations remain, and before signing up again to reuse the account. It also explains what to do when nearing the monthly cap, including handoff versus request-upgrade, though it frames these as HTTP endpoints rather than 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?

With no annotations, the description carries the full burden and does well: it discloses the polling interaction pattern, the exact state values, what becomes available once 'completed', and that errors are surfaced with actionable messages. It omits whether the call is read-only, any auth/permission requirements (despite an `authorization` parameter), and any rate-limit or polling-cost caveats.

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 tight sentences, front-loaded with the return contract before the usage instruction. No filler and every sentence adds distinct information (payload, polling trigger, error behavior).

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?

There is no output schema, and the description compensates by enumerating the returned fields and states, which is the right move for a status-polling tool. The gap is parameter documentation for `session_id`/`authorization`, leaving the description one step short of fully self-contained.

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 0% and there are two parameters, so the description must compensate — but it never mentions `session_id` or `authorization`. An agent gets no statement of which session's attachments are returned or how credentials are supplied. The word 'attachment' implies session scoping only indirectly.

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 ('Returns each attachment's processing state') and enumerates the exact payload (pending/processing/completed/failed, extracted text length, chunk count). This is clearly the attachment-status reader, distinct from upload_attachment_base64, delete_attachment, and the generic get_job/list_jobs siblings.

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 context: 'Poll this after upload_attachment_base64 to know when an attachment becomes queryable by the AI.' It names the predecessor tool and the goal state, which is strong routing guidance. It lacks any when-not guidance or mention of how often/when to stop polling.

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?

With no annotations, the description carries the burden well: it discloses owner-scoping (404 if not yours), cost behavior (token-light, NON-BILLABLE), and that structure is always included. It doesn't state permissions/rate limits explicitly or whether the read is side-effect free, leaving slight gaps.

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?

Purpose is front-loaded in the opening sentence, followed by scoped detail on structure and include_html. Every sentence carries information, though the structure-component enumeration is somewhat dense; nothing is wasted.

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

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

With no output schema and no annotations, the description still fully specifies the return shape (headings/section_count/block_count/media, prior-chats, and html/page_setup/version_id when include_html=true). An agent has everything needed to call it correctly.

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

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

Schema description coverage is only 33% — document_id and authorization are undocumented in both schema and description. The description clarifies include_html's purpose and default and explains the return is metadata+structure unless include_html=true, partially compensating, but the required document_id gets no elaboration.

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 resource (one saved document) and enumerates the exact payload: metadata, STRUCTURE outline, and chat sessions that have it open. It differentiates itself from siblings like list_documents and export_document by clearly being the by-id detail/verify call.

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 ('cheap verify step after any edit', 'did my edit land?') and an explicit when-not/alternative ('never export a whole document just to check its structure'). It also scopes include_html with a clear condition: use only when you need the body.

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?

With no annotations, the description carries the full burden and largely meets it: it discloses the status lifecycle, that intermediate responses are streamed, that pending changes carry chunk IDs and HTML diffs in metadata.pending_changes, and that headless/MCP clients receive typed progress events (documents_changed, continue_prompt, model_fallback, proposed_change_batch). It stops short of stating auth/permission requirements or rate-limiting expectations for polling, which is the main remaining gap.

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 response payload is front-loaded in the first sentence, followed by usage guidance and then the approval/streaming details. It is dense and runs long, but nearly every clause carries non-obvious behavioral information rather than restating structured fields.

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, yet it usefully ties the status values to the approval workflow and streaming events an agent must act on. Combined with the polling guidance and the cross-session alternative, an agent has everything needed to call and follow up on this tool correctly.

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

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

Schema coverage is only 33% — only 'compact' is documented, while job_id and authorization are undocumented in both schema and description. The description implies job_id via 'the job's current state' but adds no meaning for the authorization parameter, so it does not compensate for the low coverage; job_id is self-evident from the tool name, keeping this at a baseline 3.

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

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

The description states a specific verb and resource (returns the job's current state) and enumerates the exact status values (pending, in_progress, awaiting_approval, completed, failed, cancelled), plus the full payload. It clearly distinguishes get_job from siblings like list_jobs, get_session_jobs, and cancel_job by describing per-job result retrieval rather than listing or mutating.

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 routing: 'Poll this after chat_async to track progress and retrieve results,' and names the follow-up action when status is awaiting_approval (POST /v1/chat/{session_id}/approve). It also points to an alternative for a related need (GET /v1/sessions/{session_id}/doc-events for cross-session updates), so when-to-use and when-to-use-something-else are both covered.

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?

With no annotations, the description carries full disclosure burden and does much of it: it explains that the AI rehydrates with prior decisions/chunk IDs/attachments, and highlights the context-size trade-off of include_document_html. It says nothing about the authorization parameter, permission requirements, or failure modes, which is the remaining behavioral gap.

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, most of which earn their place, with the core return payload and the continuation use case front-loaded. 'The AI rehydrates with full context of all prior decisions, chunk IDs, and attachments' partially repeats the earlier return inventory, so it is slightly longer than needed.

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-value explanation is not strictly required, yet the description usefully characterizes what rehydration gives the agent. The main omission is any mention of the authorization parameter or access prerequisites for a session-history read.

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 50%: focus_document_id and include_document_html are already documented in the schema, and the description largely restates the include_document_html behavior rather than adding new meaning. session_id and authorization have no description anywhere, and the description does not compensate for those gaps — baseline 3.

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

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

Specific verb+resource ('get_session_history') with an explicit inventory of what is returned: message history, document HTML with chunk IDs, attachment list, and editor actions. It is clear what the tool retrieves, but it never contrasts itself with nearby siblings such as get_document_detail or list_sessions, so an agent must infer the boundary itself.

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?

States a clear usage context ('Use to continue editing a document you started in a prior session') and gives a conditional guideline for include_document_html=false when only the conversation is needed. It stops short of naming alternatives or exclusions, so it is clear context rather than full when/when-not routing.

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. It discloses scope (one session) and output shape parity with list_jobs, which is genuinely useful. However, it says nothing about permissions/auth requirements, pagination, or whether the full history is truncated by default limits — meaningful gaps for a history-listing read tool with zero annotation 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?

Three short sentences, front-loaded with the core behavior, then use cases, then the sibling contrast. Every sentence earns its place, though the final sentence slightly restates the scoping already implied by the opening.

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-value details need not be spelled out, and the description correctly covers purpose, scope, and routing. Missing pieces are secondary: auth expectations and pagination/limit behavior for a tool that can return unbounded history.

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 50%; the compact parameter is well documented in the schema itself, but limit and session_id carry only titles or a terse one-liner. The description reinforces that session_id scopes the call ('scoped to one session') but adds no format, default, or interaction details for limit/compact and says nothing about the authorization parameter. 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?

States a specific verb and resource: 'Returns the full job history of one document,' and immediately differentiates from the sibling list_jobs. Slight friction in naming a 'session' as a 'document' and back again, which could momentarily blur what the scoping key means, but the intent is unmistakable.

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 concrete use cases (auditing AI actions over time, finding a job awaiting HITL approval) and routes the agent relative to a named sibling: 'Same shape as list_jobs but scoped to one session.' No explicit when-not-to-use, but the alternative and its selection condition are both present.

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?

With no annotations, the description carries the burden and does well: it discloses the exact status code and payload and that no auth is needed. It does not mention timeouts, rate limits, or that it is a safe read-only probe, but for a trivial health endpoint the disclosure is largely sufficient.

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-loaded with the observable result, then the when, then the auth note. 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?

The description explains the return value even though no output schema exists, and with zero parameters and a trivial surface there is nothing else 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?

The tool takes zero parameters, so there is nothing the description needs to compensate for; schema coverage is 100% on an empty object. Baseline 4 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 concrete verb (returns) and the exact resource/response (200 with {"status":"healthy"}) plus the condition (when the API is up). No sibling tool performs a connectivity check, so this is unambiguously distinct.

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

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

Explicitly says to call it once after MCP install and before invoking other tools, which is exactly the when-to-use guidance an agent needs. It also pre-empts an auth concern by stating no authentication 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?

With no annotations, the description carries the full burden and does well: it discloses that documents are SHARED and never copied, that the first document is focused, the binding is durable, and a roster is returned. It is silent on the authorization parameter and on error/failure behavior, which are meaningful gaps for a session-creating mutation.

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 purpose is front-loaded, but the text repeats the 'one-call way to start a session with documents already open' idea and the '/documents/open' cross-reference twice. Some sentences could be consolidated without loss.

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 combined create-plus-open tool with no annotations and no output schema, the description covers the key behaviors an agent needs (sharing semantics, focus, empty-session case). It lacks only authorization and failure-mode detail to be 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 coverage is 75%, and the description reinforces session_id semantics (client-chosen vs server-minted) and the document_ids roles beyond the schema. It adds little for include_html (already fully documented) and leaves the authorization parameter unaddressed in both schema and description.

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+resource (create a session and open N documents) and precisely scopes it as a combined one-call operation. It implicitly separates this from the sibling open_documents by framing it as the way to start a session with documents already open.

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 usage context: the web UI passes its own session_id, while an MCP/API integrator omits it and the server mints one; with no document_ids it returns an empty session. It never names the sibling open_documents or states an explicit when-not-to-use, so it stops short of full 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?

With no annotations, the description carries the full burden and does so well: it discloses the one-time import of pre-Files-view chats on the FIRST call (a surprising side effect for a read-shaped tool), the soft-delete semantics of the archived view, the ordering, and that results are metadata-only. That is exactly the non-obvious behavior an agent needs.

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?

Purpose, ordering, and the metadata-only constraint are front-loaded in the first sentence; the remaining sentences each add a distinct operational fact (session_count, auto-durability, first-call import, archived filter). 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 5-param, no-annotation, no-output-schema tool, the description covers purpose, both boolean flags, the ordering, and the notable side effect. It stops short of describing the returned record shape beyond metadata-only and session_count, which matters slightly given there is no 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?

Schema coverage is already 80%, so baseline is 3, but the description adds meaning beyond the schema for two parameters: archived is framed as the Files 'Archived' filter over soft-deleted records, and include_preview is framed as token-light for agents. limit/offset are left entirely to the schema.

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

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

The description opens with a specific verb+resource+scope: 'List the authenticated user/org's saved documents, most-recently-updated first (metadata only — no document content)'. That ordering and metadata-only qualifier cleanly separates it from get_document_detail and the content-bearing siblings.

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 conditions: 'Pass archived=true to browse the soft-deleted set', and tells agents to leave include_preview off to stay token-light. It does not explicitly name alternative tools (e.g., get_document_detail, list_session_documents) for the case of fetching content, so routing is implied rather than complete.

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 behavioral burden. It discloses the ordering, the optional status filter, and what each job record contains (originating chat, changes, HITL decisions), but is silent on pagination behavior, the authorization requirement, and the compact-mode tradeoff beyond what the schema already states.

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 what the tool returns before moving to use cases and record contents. Every sentence carries information; only the final sentence about tracked fields is somewhat expendable given an output schema exists.

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-shape detail is optional, and the description still conveys the record contents. For a zero-annotation, four-param list tool it covers purpose, use cases, and ordering, but leaves auth requirements and the relationship to get_job/get_session_jobs unaddressed.

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

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

Schema coverage is 75%, near the threshold where the schema does the heavy lifting. The description adds the sort order ('most recent') and confirms status filtering, but says nothing about limit, compact, or authorization; the compact param is documented only 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 and resource ('Returns jobs'), plus ordering ('sorted by most recent') and optional status filtering. This clearly separates it from get_job (single job) and cancel_job, though it never names those siblings explicitly, so it falls short of full differentiation.

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

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

Gives three concrete when-to-use scenarios: monitoring chat_async edits, spotting jobs paused for human approval, and auditing completed work. Strong contextual guidance, but no explicit exclusions or named alternatives (get_job, get_session_jobs) for narrower lookups.

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 does substantial work: it warns that the body can be hundreds of KB per document and is omitted by default, explains the focused-first ordering, and flags that `durable_document_id` is null until the first save. It does not cover auth requirements or rate/refresh caveats.

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 core behavior in the first sentence and uses a labeled ID MAPPING block to organize the denser id-semantics content. Some of the mapping prose is verbose (multiple sibling names in a single clause), but no sentence is wasted.

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

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

With no output schema and no annotations, the description must describe returns itself — and it does, listing id, chunk count, focused flag, and changed_since_seen. The inclusion of the id-mapping rules is essential context that a bare schema would hide, though session_id semantics and error behavior remain unaddressed.

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

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

Schema description coverage is 50%: `include_html` and `report_changed` are already well documented in the schema, while `session_id` and `authorization` are undocumented in both places. The description reinforces when to set include_html=true but adds no syntax or constraints for the required `session_id`, so it only partially compensates.

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+resource+scope: returns the editable documents open in *this session*, focused first, with named fields. It also explicitly distinguishes itself from `list_documents` (Files) via the ID MAPPING section, so an agent can tell session-scoped from durable-document listing 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?

Gives clear context for use (render document tabs; enumerate/switch tabs token-light) and names the alternative form of the id accepted by `focus_session_document`, `close_session_document`, and `chat`. It does not explicitly state when *not* to use this versus `list_documents`, but the id mapping effectively routes the agent between them.

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. It discloses ordering, output contents, and that history/conversation is persisted server-side, but says nothing about auth/permission requirements or pagination beyond the limit default. The deprecation note about user_id vs auth scope lives only in the schema, not here.

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 tight sentences: output shape first, then the resource definition, then usage. Front-loaded and waste-free, though the middle sentence could be slightly trimmed.

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 covers purpose, usage, and session semantics well. The remaining gap is auth/scope behavior and the undocumented authorization parameter, which is minor but not negligible for a listing 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?

Schema description coverage is 67%, with 'authorization' carrying no description anywhere, yet the description adds no parameter-level meaning at all. It neither clarifies the deprecated user_id behavior nor explains limit/pagination semantics, so it fails to compensate for the coverage gap.

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 ('Returns sessions') plus the sort order and the fields returned (message counts, last-updated timestamps). It also defines what a session is ('one document with full edit history and AI conversation persisted server-side'), which cleanly separates it from list_documents and list_jobs without needing to name them.

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 use cases ('find a previous editing context to resume', 'audit your workspace') and even names the follow-up call (get_session_history). It lacks an exclusion statement (e.g., when to use list_documents or list_session_documents instead), which keeps it short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses the filtering criterion (active, non-deleted), the return payload fields (name, format, size, creation date), and the critical auth scoping rule (users via web app or sk_ key see only their own; organizations via lce_ key see theirs). Gaps remain: pagination, ordering, size limits, and error behavior are not described.

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 return value, then usage guidance, then scoping detail. No wasted words, and each sentence adds relevant information, though it could be slightly tighter.

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 1 optional parameter, no output schema, and no annotations, the description is nearly complete: it covers return fields, scoping, and usage. The main omission is pagination/result-size behavior and the authorization parameter's expected form.

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?

One optional parameter 'authorization' has 0% schema description coverage. The description partially compensates by explaining how the authenticated entity (web app/sk_ key vs lce_ key) scopes results—effectively the parameter's impact—but does not explain its expected format or how to supply it.

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

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

States a specific verb ('Returns') and resource ('active (non-deleted) templates'), enumerates the returned metadata fields, and implicitly distinguishes from siblings like delete_user_template by describing a read/list operation. It also separates templates from documents, which are covered by list_documents.

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

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

Explicitly says 'Use to show the AI what reusable document structures are available for drafting new documents,' giving clear context for when to call it. It does not name alternative tools or when-not-to-use conditions (e.g., use delete_user_template for removal).

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?

With no annotations, the description carries the full behavioral burden and mostly does: it discloses that the same durable row is attached rather than copied, that edits propagate back to a shared row, that this creates cross-session soft-collaboration, and that the first listed document is the one focused. It omits auth/permission requirements and error behavior, which keeps it out of 5 territory.

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?

Purpose is front-loaded in the first sentence, followed by attachment semantics and the return contract, so the structure is easy to scan. It is slightly padded ('cross-session soft-collaboration') but every sentence still carries distinct 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 tool with no output schema and no annotations, the description does the heavy lifting: it explains the return value ('refreshed document roster so the client can render tabs immediately') and the token-light behavior of include_html. What remains missing is any mention of authorization requirements or prerequisites such as session initialization.

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 only 50%, and the description's 'The first listed document is focused' adds genuinely non-obvious ordering semantics for document_ids that the schema does not convey. However, session_id and the anyOf string/null 'authorization' parameter are undocumented in both places, so the description only partially compensates for the coverage gap.

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 ('Load ... SAVED documents into a session as editable tabs') and pins down that only durable/saved documents are eligible, contrasting implicitly with the many upload_* and process_uploaded_document siblings. It does not explicitly name a sibling it differs from (e.g. get_document_detail or list_session_documents), so it stops short of a 5.

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 'Load one or more SAVED documents' framing implies the use case, and include_html's schema text touches on agent workflows ('enumerating or switching tabs'), but the description never states when to prefer this over list_documents, get_document_detail, or focus_session_document, nor any precondition like whether an init_session must come first. Usage must be inferred from 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?

With no annotations, the description carries the full burden and does so well: it discloses the non-billable upload/parse model (charged only on AI edits), the compact-by-default response to protect context, that the document is loaded into the session and edited via chat, and that attachment mode processes asynchronously returning a job_id to poll. These are non-obvious, high-value behavioral facts an agent could not infer from 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?

Content is dense and front-loaded, leading with the verb and pipeline rather than burying it, and every sentence carries information. However, it is delivered as one long run-on paragraph with several em-dash asides, which hurts scannability for a definition this content-rich.

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 explained, and the description covers the workflow prerequisite (request_upload_url), both parse modes, the async job_id path, the default response shape, and the billing model. For a 6-parameter parsing/ingestion tool with no annotations, nothing essential to calling 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 83%, so the schema already documents filename, upload_id, session_id, parse_mode, and return_html in detail, and the description largely restates the parse_mode and return_html semantics rather than adding new syntax or constraints. The added framing (edit-via-chat, context-size tradeoff) is useful but not parameter-level detail, so the baseline 3 holds.

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+resource ('fetches the file uploaded via request_upload_url and runs the same parsing pipeline as upload_document_base64') and immediately positions itself relative to two named siblings, making the distinction from upload_document_base64 explicit. The scope of what gets parsed (paragraphs, headings, tables, rows, cells) further sharpens what the tool actually produces.

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?

Clearly conditions usage on the preceding request_upload_url call and explains the parse_mode='document' vs 'attachment' choice and the return_html default. It does not explicitly state when to prefer this over upload_document_base64/upload_attachment_base64, leaving the routing between upload paths 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?

With no annotations, the description carries full burden and does well: it declares the operation non-destructive, explains conflict merging ('keeping both where they conflict'), and specifies exactly what is un-archived. It omits any authorization/permission requirements, which is the main remaining gap.

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 key trait ('Revert is non-destructive') is front-loaded and the sentences are dense and purposeful. The trailing intended-use sentence is valuable but the overall block is slightly overloaded for a single 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?

An output schema exists, so return values need not be explained, and the description covers the state-change semantics, the temporal usage window, and the checkpoint provenance. For a revert tool with annotations absent, this is complete enough to 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?

Schema coverage is 60%, so the schema already documents turn_index and redo_checkpoint_id. The description reinforces that redo_checkpoint_id comes from the revert response and that turn_index marks the rewind point, but adds little syntax or format meaning, and says nothing about window_id or authorization.

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+resource (revert forward / redo a revert) and precisely describes the resulting state change (restores session, document, un-archives chat turns). It does not name the sibling revert_session_to_message, so an agent must infer the pairing, keeping this below 5.

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 when-to-use ('intended for use immediately after a revert') and when-not ('once a new message is sent the timeline diverges and the web app stops offering it'). The temporal constraint that selects this tool over any alternative is fully spelled out.

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?

With no annotations, the description carries the full burden and does so richly: server-side sanitization of every fragment, versioned writes that are safe under concurrent editors, parts reverting with the document, newest-write-wins semantics, and the `parts_conflicts` reporting behavior. It even documents the specific error code for the legacy payload, which is exactly the behavioral context an agent needs.

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 operation in the first sentence, then layered behavior. It is dense and slightly repetitive with the schema on parts semantics, but every sentence carries real 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 complex mutation tool with no annotations, no output schema, and 60% param coverage, the description covers error paths, concurrency, sanitization, revert behavior, and conflict reporting well. The remaining gap is the undocumented identity/authorization parameters and the shape of a successful parts response.

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 60%, and the description adds mostly conceptual routing rather than parameter-level meaning. The two fully documented params (`parts`, `base_parts`) already carry the important semantics in the schema, while `document_id` and `authorization` are left undocumented in both places. Baseline 3 is appropriate given the schema does most of the heavy lifting.

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+resource ('Rename one of your saved documents') and extends it to out-of-flow parts, and it names an alternative path (chat / document write endpoints) for editing part content. It is clear what the tool does, though it does not directly name a sibling tool by name for the rename-vs-update distinction.

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

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

Explicitly says a title-only call is equivalent to the old rename, routes part-content editing elsewhere, and warns that a legacy `parts` payload returns 400 `parts_moved_to_chunks`. That is clear when-to-use and when-not guidance, though it stops short of naming the successor write endpoint.

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?

With no annotations, the description carries the full burden and does well: it discloses the 15-minute URL lifetime, that the URL is signed and time-limited, that the bytes can bypass the context window via curl_example, and the accepted formats. It omits auth/permission requirements despite an authorization parameter, and says nothing about error cases or regenerating an expired link.

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 return value and the curl_example, and the format list comes last where it belongs. One sentence is partly redundant - 'Generates the document in the requested format and returns a time-limited signed download URL' restates the opening claim, costing a little length without adding 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?

An output schema exists, so return values need not be re-explained, and the description covers the critical operational facts (link lifetime, curl path, format set). It stops short of documenting the nested options object, the authorization parameter, or what happens on expiry, which leaves a small gap for a 5-param 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?

Schema description coverage is already ~80%, so baseline is 3. The description adds genuine value beyond the schema by calling out the legacy 'doc' format (the schema's own format description omits it) and by naming the ready-to-run curl_example that the schema does not document. It does not touch options, filename, or authorization.

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: generates the document in the requested format and returns a short-lived signed GET URL, plus a curl_example. This clearly distinguishes it from request_upload_url (the inverse direction) and export_document, and the colour on the 15-minute lifetime makes the resource concrete.

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?

Explains the two consumption modes explicitly: shell-capable agents should run the curl_example to save bytes to the working directory, while clients without shell execution use the signed URL directly. That is clear context for how to use it, but it never states when to choose this tool over the sibling export_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?

With no annotations, the description carries the full burden and does well: it discloses that the Typebar team is notified with account identity and submitted numbers, that turnaround is typically within a day, and that the account email is contacted. It stops short of explaining the authorization parameter or whether repeated requests are rate-limited, so it is strong but not exhaustive.

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 core promise ('in ONE call'), then uses labeled WHEN TO USE / WHAT HAPPENS / ALTERNATIVES sections. Every sentence carries actionable content 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 request tool with no output schema and no annotations, the description supplies trigger conditions, effect and timeline, contact channel, and waiting-period alternatives. An agent has everything needed to decide and call it correctly.

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

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

Schema coverage is 83%, so the schema does most of the work; the description only loosely alludes to 'the numbers you send' without adding format or meaning. It does not compensate for the undocumented 'authorization' parameter, 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?

States a specific action (request a higher scale limit for your account) and emphasizes 'ONE call', immediately distinguishing it from any retry/upload sibling. The trigger (413 with DOCUMENT_TOO_COMPLEX or SESSION_TOO_FULL) makes the intent 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?

Explicit WHEN TO USE gated on two specific error codes, plus a named set of ALTERNATIVES with sibling tools (init_session, close_session_document, upload as attachment). Leaves nothing about timing or fallback 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?

With no annotations, the description carries the full burden and does well: it discloses the 5-minute URL expiry, the 100 MB cap, supported formats, and the side benefit that bytes never enter the agent's context. It omits auth/credential requirements for the PUT and what happens if the URL expires mid-upload, which are real gaps for a write-flow tool.

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

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

Front-loaded with the return value and the primary workflow, and each sentence adds routing or constraint information rather than restating the name. It is dense and long-ish for a single paragraph, but no sentence is 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?

An output schema exists, so return structure needn't be explained; the description instead covers the full multi-step flow (request URL, PUT, then `process_uploaded_document` with `upload_id`), limits, and format support. An agent has everything needed to execute the flow 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 ~80%, so the schema already documents `purpose`, `filename`, `size_bytes` and `content_type`. The description adds the supported-extension list, which helps validate `filename`/`content_type`, but says nothing about the optional `authorization` parameter or enum semantics beyond what the schema states. Baseline 3 is right.

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 with scope: returns a short-lived (5-minute) PUT URL plus a ready-to-run `curl_example`. It is immediately distinguishable from `request_download_url` (direction) and the `upload_*_base64` siblings (inline bytes vs. direct PUT).

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 routing: shell-access agents run the `curl_example`, non-shell clients surface the URL/command, files under 100KB should use `upload_document_base64`, and the follow-up call to `process_uploaded_document` is named. When-to-use and named alternatives are all present.

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?

With no annotations present, the description carries the full behavioral burden and does so richly: it discloses soft-archive semantics (hidden from active reads, retained for audit), that the original conversation is preserved server-side, which timeline becomes active, and two specific failure modes (409 in-progress job, 422 'turn_has_no_restore_point' with a revertable_turns payload).

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 and its effects, then failure handling; every sentence carries information. It is dense but slightly over-long, and the error-code detail could be compressed without losing meaning.

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

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

An output schema exists, so return values need not be described, and the description still covers mutation side effects, timeline state, and both error paths with remediation hints. For a destructive rewind tool with no annotations, 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 only 60%, so the description must compensate; it explains turn_index's downstream effect (message text returned in compose_text, all rows at that turn or later archived) and surfaces the revertable_turns field returned on error. However, session_id and authorization are left entirely undocumented, so the gap is not fully closed.

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 precise verb+resource+scope: 'Rewinds a chat session to the state immediately before a specific user message,' and enumerates exactly what snaps back (document, history, context). An agent can distinguish this rewind operation from siblings like redo_revert without opening a schema.

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

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

Gives clear triggering context ('rewind to the point before a user message') and precondition states (wait for a chat job to settle before reverting; job-in-progress yields 409). It does not explicitly name the inverse sibling redo_revert or say when to undo a revert, so alternative-routing guidance is incomplete.

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?

With no annotations present, the description carries the full burden and does well: it discloses the state transition (document re-enters Files view, becomes editable), idempotency semantics (already-active or unknown ids are a no-op), and cost ('Non-billable'). It stops short of noting permission/authorization requirements, which matters given the undocumented `authorization` parameter.

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 building outward to effect, id linkage, idempotency, and billing. Every clause adds decision-relevant information; nothing is padding.

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

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

For a two-parameter mutation tool with no annotations and no output schema, the description covers state effects, idempotency, cross-tool id consistency, and billing. The remaining gap is the unexplained `authorization` parameter and any indication of what is returned after restore.

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 0%, so the description must compensate. It does explain `document_id` meaningfully by anchoring it to the same id used by list_documents/archive_document, but it says nothing about the `authorization` parameter or the id's expected format. Half the parameters remain undocumented in both places.

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 ('Restore (un-archive) a saved document by its id') and explicitly positions itself against a named sibling ('the mirror of archive_document'). An agent can distinguish this from archive_document, delete_document-style tools, and open_documents 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?

Establishes the context for use (re-entering a document into the Files view) and routes the agent to related tools: archive_document as the inverse, list_documents/archive_document as the id source, and open_documents for the follow-up action. It lacks an explicit 'when-not' clause, but the idempotency note effectively tells the agent not to pre-check state.

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, so the description carries the full burden and does so richly: asynchronous processing, AI-searchable once ready, multimodal vision for images, a gateway-level 32 MB request-body cap that fails with an HTML (not JSON) error, and base64 ~33% inflation. This is exactly the behavioral context a caller needs.

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 async behavior and the sibling distinction before formats and transport limits, and every sentence carries information. It is dense and long, but the length is justified by the number of real constraints it must convey.

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-param, no-output-schema upload tool, it covers async semantics, polling, size/transport limits, and the return_html tradeoff is handled by the schema. Only minor gaps remain, such as the session_id ambiguity and lack of explicit error-handling guidance beyond the gateway cap.

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 80%, so the baseline is 3; the description adds the 50 MB validation limit, the base64 encoding context, and the filename-driven type detection. Slight tension: it states 'Requires session_id' while the schema says session_id is auto-generated if not provided.

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+resource (upload attachment) and explicitly differentiates from the sibling upload_document_base64, explaining attachments are read-only AI context rather than the editable working document. An agent can pick it correctly 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?

Gives clear conditions: poll get_attachment_status for readiness, and use request_upload_url beyond ~20 MB of file bytes. It names the alternative and its trigger. Lacks an explicit 'when not to use attachments at all', so a 4 rather than 5.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses compact-by-default responses when session_id is passed, the verbatim (never paraphrased) load semantics, the 50 MB validation cap, the ~32 MB transport body cap with a non-JSON HTML error at the gateway, and the ~33% base64 inflation. It also explains the convert-only path 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 core purpose is front-loaded in the first sentence, and each later clause adds distinct value (editing, seeding, verbatim replace, size limits). It is dense and slightly repetitive on size thresholds, but no sentence is pure 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 5-parameter tool lacking an output schema and annotations, the description supplies everything needed: response shape (compact metadata vs full HTML), session behavior, supported formats, and layered size limits with the correct fallback. Nothing required 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 80%, so baseline is 3, but the description meaningfully adds to it: it explains that return_html is only meaningful with session_id and ignored otherwise, and that session_id loads the doc for chat-based editing. It does not add much on filename/base64/authorization, hence not 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?

The opening sentence states a specific verb and resource (parses an uploaded file into structured HTML with unique chunk IDs) and immediately contrasts with alternatives like request_upload_url and the chat-editing workflow. An agent can distinguish this from sibling upload tools (upload_attachment_base64, upload_image_base64, upload_template_base64) 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?

Explicit routing rules are given: use request_upload_url for files >100KB or beyond ~20 MB inline, use chat to make targeted edits once loaded, use this tool to verbatim-replace a session document, and use it to seed AI-drafted content. Conditions and alternatives are named, not 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?

With no annotations, the description carries the full burden and does well: it discloses accepted formats (PNG/JPEG/WebP/GIF/SVG), a 10 MB decoded size limit, and the crucial lifetime distinction between the permanent `url` and the expiring `view_url`. It omits auth/permission requirements (the schema exposes an `authorization` field that is never explained) and any rate-limit or failure 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?

Three tight paragraphs, front-loaded with the core action and return value, then input constraints, then the embed-vs-view warning. The parenthetical asides add length but each carries a real constraint; nothing is pure 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 compensates well by explaining both returned fields (`url` vs `view_url`) and which one to embed. It is nearly complete for an upload tool; the only real gap is the unexplained `authorization` parameter and any error/failure semantics.

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 75%, so the baseline is 3. The description reinforces `image_base64` (raw base64 or data: URL) and adds genuine constraints the schema lacks (10 MB decoded, accepted formats), but it says nothing about `authorization`, `filename`, or `content_type` 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?

States a specific verb+resource ('upload an image (base64-encoded)') plus the outcome ('get a stable URL to reference in a document'). It also distinguishes itself from the browser multipart upload path, so an agent can place it against siblings like upload_attachment_base64 without opening a schema.

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

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

Explicitly gives the use case ('save a generated or fetched image so a document can embed it') and names the browser multipart upload as the alternative it replaces. It does not, however, explain when to prefer it over the sibling upload_attachment_base64 or upload_document_base64 tools, which are the closest neighbors in the list.

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?

With no annotations, the description carries the full burden and delivers unusually rich operational detail: 50 MB validated cap, ~32 MB gateway body limit, ~33% base64 inflation, ~20 MB practical inline ceiling, and the failure mode (HTML, not JSON, error from the gateway). It does not cover permission/auth requirements or collision/overwrite behavior for existing templates.

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 template concept and use cases, then formats, then the size/transport caveat; every sentence carries weight. The single dense paragraph with multiple em-dash clauses is heavier to parse than it needs to be, but nothing is 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?

For a no-annotation, no-output-schema, 5-param mutation tool, the description covers formats, persistence, size limits, error shape, and the large-file alternative. Gaps remain around how user-vs-organization scope is chosen (no scope parameter exists) and what authorization is required.

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 80%, so the baseline is 3, but the description adds real meaning for file_base64 (effective inline size ceiling and inflation math) and for filename (supported extensions drive type detection). The undocumented authorization parameter and the unclear mechanism for selecting user vs organization scope are not compensated for.

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 explains the resource (templates persisted across sessions, user/org scoped) and its intended AI use case, and differentiates from document upload by noting shared formats and from request_upload_url as the escalation path. The verb itself is only implied via the tool name; the text never literally says 'uploads a template,' so it stops short of a full 5.

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?

Names concrete use cases ('boilerplate, branded letterheads, recurring document structures, compliance-required templates') and an explicit alternative with a threshold: use request_upload_url for pre-signed flow beyond ~20 MB of file bytes. Scope (user vs organization) is also stated.

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