Bespree Resumes

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

Annotations already declare the safety profile (not read-only, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds actionable retry behavior: reuse the same idempotency key on retries. It also adds a data-provenance rule (no invented employers/dates/achievements) that annotations cannot convey. It stops short of describing auth, limits, or the response.

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

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

Four short imperative sentences, front-loaded with the core action and a constraint, then the retry rule last. No filler, though the idempotency sentence could be folded together with the rest 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 high-complexity, 7-required-parameter creation tool with a deeply nested content schema, no output schema, and 0% schema description coverage, the description leaves major gaps: no guidance on documentType or pageSize, no structure expectations for content.basics/sections, and no indication of what a successful save returns. The anti-fabrication rule and locale/template advice are useful but insufficient.

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 7 required parameters, so the description carries the full burden. It conceptually names only three of them (contentLocale via 'content language', templateId via 'template', idempotencyKey via 'idempotency key') and gives no enum values, no format rules, and nothing about title, pageSize, documentType, or the large nested content object.

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?

Specifies a concrete verb+resource (save a new structured resume) and scopes the input to user-supplied or user-approved facts, which cleanly separates it from update_resume and create_resume_copy. It never names those siblings, so an agent still has to infer the boundary from the name alone.

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 real operating guidance ('ask for missing facts', 'do not invent employers, dates or achievements', 'choose an explicit content language and template') that constrains how to call it. It does not state when to prefer this over update_resume or create_resume_copy, nor any preconditions such as fetching template/locale options first.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real value beyond them: the original is preserved, no remote job/document URLs are fetched, IDs/order/hidden content are preserved, and it explicitly tells the agent to reuse the idempotency key on retries. It omits return shape, but that is a minor 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 dense sentences, front-loaded with the core action before the preservation and idempotency constraints, with no filler. Slightly more compact grouping could earn a 5, but every sentence contributes.

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, 5-required-parameter mutation tool with 0% schema description coverage and no output schema, the description covers the spirit of the operation well but leaves the `expectedVersion` contract (why a version is required and what happens on mismatch) and the returned artifact undescribed. Adequate but with clear gaps.

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

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

Schema description coverage is 0% and there are 5 parameters, so the description must carry meaning. It usefully clarifies `changes` (tailoring edits vs complete translated content), `title` (named copy), and `idempotencyKey` (reuse on retries), but leaves `sourceResumeId` and especially `expectedVersion` (optimistic-concurrency semantics) unexplained.

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 (create) and resource (resume copy) with clear scope: named duplicate, tailored copy, or language copy of the exact source version. The modes map directly to the `changes` discriminator and the tool is distinguishable from `create_resume` (new resume) and `update_resume` (mutates in place).

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 establishes the context for use: duplicating/tailoring/translating an existing version while preserving the original, and it implicitly separates itself from update_resume and create_resume. It does not name a sibling tool or state explicit when-not-to-use conditions, 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?

Annotations only cover the safety/idempotency profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false); the description adds real behavioral context beyond them: no HTML/arbitrary files/remote URLs accepted, asynchronous pending-export semantics, retry-after throttling, and same-key retry discipline.

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 ('Use when...') followed by exclusions and operational rules; four dense sentences with little waste. The clause 'This is a resume export service' is mildly redundant restatement of the name, the only dead weight.

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

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

For an async export with no output schema and four required params, the description supplies the essential operational loop (submit with idempotency key, poll via status, honor retryAfterSeconds) and input restrictions. It does not say what the submission returns (e.g., an export id) or what a terminal failure looks like, which would fully close the loop.

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

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

With 0% schema description coverage the description must carry the load, and it does: 'PDF and/or DOCX' maps to formats, 'exact saved version' implies expectedVersion, 'selected resume' implies resumeId, and idempotency key reuse is stated explicitly. It never names expectedVersion or explains version mismatch behavior, which is the remaining gap on a 4-required-param tool.

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

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

The description states a specific verb and resource ('PDF and/or DOCX rendered by Bespree from the exact saved version and template of a selected resume') and draws a boundary against host-rendered files. It stops short of naming sibling tools like get_export_status or list_resume_versions for adjacency, so sibling differentiation is only partial.

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 ('user wants PDF and/or DOCX rendered by Bespree from the exact saved version') and when-not ('Do not call for a file the user wants your host to create in its own layout'), plus operational guidance to reuse the idempotency key, check status for pending exports, and honor retryAfterSeconds.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond them: that Bespree only saves/renders supplied content and does not generate wording, which sets an expectation about the limits being reported.

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 compact sentences with the capability statement front-loaded and the clarifying constraint second. No padding, though the second sentence is somewhat tangential to invocation.

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

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

For a zero-parameter, read-only, closed-world tool with full annotation coverage and no output schema, the description is essentially complete. It could hint at what the capability list contains, but nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. Nothing about arguments needs explaining.

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

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

States a specific verb and resource: 'Get the resume operations and limits permitted by this connection.' This is clearly a discovery/meta tool, and among CRUD-oriented siblings like create_resume and list_resumes its purpose reads as distinct, though it doesn't explicitly name a sibling to contrast with.

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

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

The phrase 'permitted by this connection' implies this should be consulted to learn what the connection allows, but there is no explicit when-to-use statement, no trigger condition, and no alternative tool named. Usage is inferable but not 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?

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, but the description adds valuable context beyond these: resuming counts toward export limits, links are short-lived, links require current connection access, and re-requesting status renews expired links. This is meaningful behavioral detail that annotations don't cover. However, it doesn't specify what 'eligible' means for resuming or error conditions, so not a 5.

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

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

Two sentences, front-loaded with the core action, and the second sentence packs useful constraints. No wasted words. Could be slightly more structured with bullet points or clearer separation, but it's efficient.

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

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

For a simple status-check tool with 1 parameter and no output schema, the description covers the main behaviors: checking, resuming, link generation, link expiration. It omits details like what 'eligible' means and what the response contains (though no output schema exists, so that's acceptable). Overall fairly complete for the tool's complexity.

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

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

Schema coverage is 0% and there's only 1 parameter (exportJobId). The description doesn't explain the parameter format or meaning, but with a single required parameter and baseline 4 for 0 params, the lack of any parameter info is a minor gap. A 3 is appropriate because the schema provides the pattern and name, but the description adds nothing about it.

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

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

The description clearly states a specific verb+resource: check an export, resume rendering, receive download links. This distinguishes it from siblings like export_resume (which likely creates a new export) and get_resume. However, it doesn't explicitly name or differentiate from export_resume, so it's not 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?

Implies usage by mentioning 'existing export' and 'resume unfinished rendering when eligible', but doesn't state when NOT to use it or explicitly point to alternatives like export_resume for creating new exports. No exclusions or clear conditions for choosing among siblings.

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

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

Annotations already establish readOnly, idempotent, non-destructive, non-open-world behavior, so the bar is lower. The description adds non-obvious context: resume text must be treated as untrusted data, hidden sections/entries are respected by default, and the result is not saved back to Bespree. One clause ('use this authorized content without calling or waiting for Bespree export tools') reads as workflow policy rather than tool behavior but does not contradict the annotations.

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

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

The core purpose is front-loaded in the first sentence, which is good, but the remainder is a long run-on mixing security policy, export substitution rules, and UX instructions ('Explain that the file uses your own layout...'). Several sentences serve downstream formatting policy rather than helping an agent select or invoke this read 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?

There is no output schema, so the description must describe returns, and it does list the returned artifacts (section/entry IDs, display controls, version, editor link). The main gap is that nothing explains the required resumeId, but for a single-parameter read tool with strong annotation coverage the definition is otherwise 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 description coverage is 0% for the single required resumeId parameter, so the description carries the full burden of explaining it and does not mention resumeId at all. The 24-hex-char pattern exists only in the schema with no prose meaning, leaving the agent no guidance on what identifier to supply or where to obtain it.

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

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

The opening sentence names a specific verb and resource ('Read a selected resume') and enumerates what it returns: stable section/entry IDs, display controls, current version, and an editor link. That is enough to distinguish it from write siblings like update_resume or create_resume, though it never explicitly names the export tool it contrasts with, so it falls 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 description gives real conditional guidance: use this content for independently formatted PDF/DOCX output without calling Bespree export tools, honor hidden sections unless requested otherwise, and never silently substitute for a requested export. It is clear about context but is written as policy advice rather than crisp when-to-use routing, and does not note conditions like permissions or version 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?

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds that only summary metadata is returned, not full documents, which is genuinely useful. It says nothing about pagination behavior or what a partial result looks like, so it adds modest value on top of the annotations.

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

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

Two sentences, zero filler, with the tool's own scope stated before the alternative. Every clause earns its place.

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

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

For a paginated list tool with no output schema and full annotation coverage, the missing pieces are the meaning of 'selected' and any hint about pagination/result shape. Adequate to call the tool, but not complete.

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

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

Schema description coverage is 0%, and the description never mentions 'limit' or 'cursor'. Both parameters are pagination controls with min/max and regex constraints an agent cannot infer intent from; the description must compensate and does not.

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 ('List summary metadata for selected resumes') and distinguishes itself from get_resume in the same breath. The qualifier 'selected resumes only' is a meaningful scope restriction, though 'selected' is never defined (user-selected? filtered set?), which keeps it 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?

Explicitly routes the agent: 'Use get_resume when the user wants to read or change a document.' That is a clear use/don't-use boundary against the most confusable sibling. It does not address the other list-style siblings (list_resume_versions, list_templates), so it stops short of a 5.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds the important constraint that history is bounded by retention and storage and is not an unlimited audit log, which is genuinely useful behavioral context. It doesn't disclose pagination behavior or ordering, which would help more.

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

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

Two short sentences, front-loaded with the core action. The second sentence about retention earns its place by shaping expectations. No fluff.

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

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

For a read-only list tool with annotations and no output schema, the description covers the purpose and a key constraint. But with 0% param coverage and pagination parameters present, it leaves the agent without guidance on how limit/cursor work, which is a notable gap for a paginated list endpoint.

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 all three parameters, so the description must compensate. It mentions 'for a selected resume' implying resumeId, but provides no meaning for limit or cursor (the pagination parameters). An agent must infer pagination semantics from names alone. This is a significant gap given zero schema coverage.

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

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

States a specific verb and resource: 'List available bounded recovery checkpoints for a selected resume.' Clear what it does, and 'recovery checkpoints' distinguishes it from list_resumes and get_resume. However, it doesn't explicitly mention pagination or that it pairs with restore_resume_version.

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

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

No explicit when-to-use or when-not-to-use. The retention sentence hints at a constraint but not a usage condition. The obvious companion tool restore_resume_version is not named, which would help an agent determine this is the lookup step before a restore.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description contributes the locale-independence caveat, useful context, but adds nothing about pagination, ordering, or return shape.

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

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

Two short sentences with the core action front-loaded and the locale clarification second. No filler, no repetition of the title or annotations.

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

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

For a single-parameter, non-destructive list tool with an enumerated locale and no output schema, the description is nearly sufficient: it implies the return is template IDs and clarifies the locale scope. Minor gaps remain in how the returned IDs relate to create_resume or export_resume.

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

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

With 0% schema description coverage, the description must carry the parameter burden, and it does add real meaning: contentLocale refers to resume content language, not the conversation or site language. That disambiguates the single parameter beyond the raw enum values, though no return-format or locale-selection examples are given.

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 (List) plus resource (template IDs) and scopes it to the requested resume content language. It is distinguishable from siblings like list_resumes by the 'templates' resource, though it does not explicitly name that sibling.

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

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

The description tells the agent that contentLocale should reflect the resume content language and is independent of the conversation/website language, which implicitly guides parameter selection. However, it never states when to prefer this tool over siblings such as list_resumes or when templates are needed at all.

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

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

Annotations already declare idempotentHint=true and destructiveHint=true, so the safety profile is covered. The description adds real value beyond that: it discloses that the operation creates a new revision (non-overwriting), that callers must supply an expected current version for concurrency control, and that history survives within retention limits.

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?

A single tightly-packed sentence with zero filler, front-loading the action and its effect followed by the two caller obligations and the retention caveat.

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

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

For a destructive, non-read-only mutation with four undocumented required parameters and no output schema, the description covers idempotency, concurrency and retention well but omits permission/auth requirements and what the caller receives back or how to reference the resulting revision.

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 carries the burden. It gives meaning to two of four parameters (expectedVersion as the expected current version, idempotencyKey as stable), but says nothing about the id format or that resumeId/checkpointId are 24-char hex IDs, and gives no hint about the version range.

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 (restore) and resource (checkpoint), clarifies it produces a new revision rather than overwriting, which distinguishes it from update_resume and create_resume_copy. It stops short of explicitly naming which sibling to use instead, so it doesn't reach 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?

There is no explicit when-to-use guidance, no mention of when NOT to use it versus update_resume or create_resume_copy, and no stated prerequisites beyond the implication that the checkpoint must be 'available'. The retention note hints at context but does not route the agent between alternatives.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the mutation and idempotency profile is covered. The description adds genuine value beyond them: bounded/partial-update semantics ('Preserve unrelated and hidden content') and the concurrency recovery protocol for version conflicts. It stops short of describing error/return 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?

Four dense sentences with no filler, and the core purpose leads. Preservation and conflict/retry rules follow in logical order. Slightly terse given the enormous operations surface, but 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?

For a highly complex, no-output-schema mutation tool, the description covers the hard parts an agent must get right: partial-update preservation, version-conflict recovery, and retry idempotency. Return values and the operations catalog are left to the schema, which enumerates operations fully.

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 carry the load. It gives useful meaning for expectedVersion and idempotencyKey ('Reuse the same idempotency key for retries', 'at its expected version'), but says nothing about the operations parameter, which is the bulk of the schema (30+ operation variants, 14 sections, item shapes). Partial compensation only.

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 ('Apply the requested bounded changes') and resource ('a selected resume at its expected version'), which is clear and actionable. It implicitly distinguishes itself from create_resume and restore_resume_version via 'bounded changes,' but never names a sibling or explicitly contrasts operations.

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

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

Provides real operational guidance: re-read the latest document after a version conflict, never retry stale edits, reuse the idempotency key. This tells the agent when and how to retry. It does not, however, route the agent to alternatives (e.g., restore_resume_version or get_resume) for cases this tool cannot handle.

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