docx

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

Annotations already signal that this is a mutating, non-idempotent operation. The description adds useful context by stating it writes the same shared profile as the invoice server's business_set, which warns of cross-tool side effects. It does not explain partial-update vs full-replace behavior, but the annotation coverage lowers the burden.

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, no filler. The first sentence front-loads the primary purpose and scope; the second adds the crucial shared-profile side effect. Every sentence earns its place.

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

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

For a 17-parameter configuration tool, the description is fairly complete at the conceptual level: it identifies what is stored, where it appears, and that it is shared with another system. The schema covers parameter-level detail, and no output schema exists, so the description does not need to describe return values. A small gap is the lack of explicit overwrite/merge semantics, but the shared-profile note mitigates that.

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

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

Schema description coverage is 100%, so the parameter details are already well documented. The description adds a useful high-level grouping ('currency, VAT, terms and prefix defaults') and the shared-profile relationship, but it does not need to repeat the schema's per-field explanations. Baseline 3 is appropriate.

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

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

The description names a specific action ('Store') and a specific resource ('sender details printed on every proposal, contract and letter, plus currency, VAT, terms and prefix defaults'). It also differentiates the tool by noting it writes the same shared profile as the invoice server's business_set, which separates it from the document-generation sibling tools.

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

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

The description implies when to use the tool: before generating proposals, contracts, or letters, to set sender details and defaults. However, it does not explicitly state when not to use it or name alternative tools for similar tasks, so usage guidance is mostly implicit rather than direct.

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

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

The description discloses return behavior ('Returns the reference, the fee and the file path'), the nature of the output ('template skeleton for a lawyer to review, not legal advice'), and a rate limit ('Free tier: 3 agreements per month'). These add substantial context beyond the spartan annotations.

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

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

Three sentences, each earning its place: the first states the operation, the second lists return values, and the third covers the legal-review caveat and quota. No filler or redundant repetition of schema details.

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

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

For a create operation with no output schema, the description adequately covers return values and the draft nature of the document. Yet given the large sibling set and 9 parameters, a short note on why contract_create should be chosen over proposal_create or doc_create would make it more 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 89%, so most parameters are already documented in the schema. The description does not add meaning to any specific parameter; it only mentions 'fee' as part of the return value. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('produce') and a clear resource ('freelance service agreement .docx'), making the tool's function immediately understandable. It does not explicitly name or contrast with sibling tools like proposal_create or doc_create, but the resource type is specific enough to be distinguished in most cases.

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 an explicit call-to-action: 'Call this tool to produce a freelance service agreement .docx.' It adds context about the template being for lawyer review and the free-tier limit, but it does not state when not to use it or mention 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 are mostly negative hints (not read-only, not idempotent, not destructive), so the description carries the burden of explaining behavior. It adds useful details: the file path, block count, layout used, and an availability claim ('Free and unlimited'). It does not contradict the annotations and describes the return behavior without an output schema.

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

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

The description is three short sentences, front-loaded with the action ('Call this tool to write...') and quickly covering return values and availability. Every sentence earns its place with no filler or redundancy.

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

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

Given a 7-parameter tool with a fully described schema and no output schema, the description provides the necessary return-value context. It is complete enough for an agent to invoke the tool correctly, though explicit routing among sibling document tools would make it stronger.

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

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

Schema description coverage is 100%, so parameter descriptions already explain every input. The tool description adds little to param semantics beyond the phrase 'structured sections', which reflects the existing sections parameter. Therefore a baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'write a real .docx file from structured sections.' This is precise enough to distinguish the tool from siblings like doc_from_markdown or doc_fill_template, even without naming them. It also identifies key return values, further clarifying the tool's role.

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

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

'Call this tool to write a real .docx file from structured sections' gives a direct and clear instruction on the intended use case. However, it does not explicitly state when not to use the tool or point to an alternative for markdown input, templates, or proposals.

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 of behavioral disclosure, and it does well: it explains the 'without .docx' naming requirement, scopes deletion to the user's token, and explicitly states that unknown names are refused with nothing deleted. It does not mention whether deletion is permanent or what the success response looks like, but overall it is transparent.

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 deliver the action, parameter semantics, and failure behavior with no filler. The most important usage constraint (no .docx) is front-loaded.

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

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

For a single-parameter delete operation with no output schema, the description is complete: it explains what is deleted, how to identify it, where to find valid names, and what happens on failure. No critical information is missing.

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

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

Schema coverage is 0%, so the description must fully explain the sole parameter. It does: 'name is the name it was uploaded under, without .docx' and 'doc_files lists them.' This adds crucial formatting and sourcing context beyond the raw schema.

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

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

The description states a specific action ('Delete one document uploaded for your token') and identifies the target resource precisely. It also clarifies the naming convention (without .docx), which distinguishes it from sibling upload/create tools.

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

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

The description clearly indicates when to use this tool—to delete an uploaded document—and points to doc_files as the way to list uploadable names. It does not explicitly state when not to use it or name alternatives, so it falls just short of 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, the description carries the burden. 'List' implies a read-only operation with no side effects, which is transparent enough for a list function.

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

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

The description is one concise sentence that fully conveys the purpose without unnecessary detail.

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 no parameters and no output schema, the description fully covers what an agent needs to know to invoke 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?

There are zero parameters, so the baseline of 4 applies. No additional parameter context is needed.

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

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

The description clearly states the verb 'list' and the resource 'documents' with sizes, distinguishing it from sibling tools like doc_upload and doc_delete_upload.

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 is implicitly clear that this tool should be used when the user needs to see uploaded documents, though no explicit alternatives are mentioned. The simplicity of the operation makes this adequate.

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

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

It discloses that the tool reports filled, unfilled, and ignored placeholders, and that calling with no values lists them. It also mentions the free-tier placeholder limit. Annotations provide no safety hints, so the description carries the behavioral disclosure burden and does so well, though it does not discuss overwrite side effects beyond 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?

Three short sentences, each adding distinct value: the core action, the no-values special behavior, and the free-tier limit. The most important information is front-loaded with no redundant 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 covers the essential behavior, special no-values call mode, and output reporting, while the schema documents all five parameters. It lacks explicit guidance on choosing between template_path and docx_base64, but the schema hints at that distinction, so the overall picture is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the parameters are fully documented in structured fields. The description adds the useful behavior 'call with no values to list them', but does not add further parameter-specific semantics beyond what the schema already provides.

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

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

The description states a specific verb ('replace'), a specific resource ({{placeholders}} in a .docx), and the resulting action ('write a new file'). It clearly distinguishes this tool from siblings like doc_create, doc_read, and doc_to_html by focusing on template filling.

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

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

The description gives clear usage context: call it to fill a template and call it with no values to list placeholders. It does not explicitly name alternative tools or state when not to use it, but the purpose is specific enough that the intended usage is clear.

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

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

It discloses meaningful behavior beyond the annotations: empty markdown is refused, overwriting without the flag is refused, and the response includes a file plus block-count breakdown. Since the annotations are sparse, these details carry real weight.

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

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

Three sentences with no filler: purpose and return value first, supported features second, and constraints third. Every sentence earns its place.

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

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

For a tool with no output schema, the description covers the response shape, accepted input constraints, and error/overwrite behavior. Remaining details like output path defaults are already in the schema, so nothing critical is missing.

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

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

The schema already covers markdown, title, out_path, and overwrite in detail, so the baseline is 3. The description adds a useful validation constraint—empty markdown is refused—and reinforces markdown features, but it does not clarify the style parameter, keeping it just above baseline.

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

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

The description clearly states the tool converts markdown into a .docx, names the return value (the file and block count), and is distinct from siblings like doc_to_html or doc_create. The verb+resource pairing is specific and actionable.

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 opens with 'Call this tool to turn markdown into a .docx,' giving an explicit use case. It does not explicitly name alternatives or say when not to use it, 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?

Annotations already mark the tool as read-only, idempotent, and non-destructive; the description adds concrete output behavior (document-order text plus outline, or block structure) and a 'free and unlimited' note. No contradiction with annotations.

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

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

Three short sentences with the action and result front-loaded; no filler or restatement of schema details. 'Free and unlimited' is brief and adds useful context.

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 read-only tool with no output schema, the description adequately explains what is returned (outline, full text, block structure) and the usage context. The schema handles parameter details, so nothing essential is missing.

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

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

The input schema already describes all three parameters at 100% coverage, including the format enum, so the description adds little parameter-specific meaning. The 'block structure' phrase only loosely maps to format=json.

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

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

States a specific action and resource: 'extract the text of an existing .docx,' and describes the returned content (outline, full text, block structure). This clearly distinguishes it from sibling create/delete/upload/convert tools.

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

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

Gives clear context for when to call the tool: to read and extract text from an already-existing .docx. It does not explicitly name alternatives or exclusions, such as using doc_to_html for HTML conversion, 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?

Annotations are sparse (all hints false), so the description carries an added burden. It discloses return behavior (returns the path of the .html file), output characteristics ('semantic HTML'), and the negative behavior that no PDF is rendered. The 'Free and unlimited' note adds practical context beyond the annotations.

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

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

Three tight sentences front-load the core purpose and usage, then state return behavior and a key limitation. Every sentence earns its place; no filler or repetition.

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

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

For a tool with one required parameter, no output schema, and no nested objects, the description covers the essential context: what it converts, what it returns, why to use it, and what it does not do. The schema covers parameter specifics, making the overall definition complete.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (path, out_path, overwrite). The description adds high-level context such as .docx input and .html output but does not add parameter-level meaning beyond the schema.

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

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

The description states a specific action ('convert a .docx to semantic HTML'), names the output format, and clarifies the purpose ('open in a browser and print to PDF'). It clearly distinguishes this tool from siblings like doc_read and doc_from_markdown by identifying this as the HTML conversion/PDF route.

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

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

The description explicitly states when to call the tool: to produce HTML from a .docx for browser viewing and PDF printing. It also clarifies what the tool does not do ('no PDF is rendered here'), giving helpful context for routing, though it does not name specific sibling alternatives or exclusion conditions.

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 full burden. It states that files are stored under a given name and can be removed via doc_delete_upload, which gives some behavioral info. However, it does not mention potential side effects like overwriting an existing name, authentication requirements, or rate limits. It is average 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?

The description is detailed but not excessively verbose. It repeats the url explanation (once in the description and once in the schema), which adds a little redundancy, but overall it is well-structured and conveys necessary info efficiently.

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

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

Given the tool's simplicity and no output schema, the description covers what happens after upload (stored under name, removable) and the lifetime (kept for token). It lacks explicit mention of error cases or return values, but for this scope it is sufficiently complete.

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

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

Schema description coverage is 100%: all three parameters (url, name, docx_base64) have meaningful descriptions. The description also clarifies the 'name' parameter's format and purpose. This fully explains how to use each parameter without ambiguity.

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

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

The description clearly states the tool uploads a .docx file to the endpoint for later use, distinguishing it from sibling tools like doc_delete_upload and doc_read. It explicitly says 'Send an existing Word document to this hosted endpoint', which is a specific verb and resource.

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

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

It explains when to use it (to get a document ready for other tools) and provides guidance on choosing between base64 and url, including a recommendation for large files. It also mentions that uploads are kept for the token, implying a session context. No explicit comparison to alternatives, but the context is clear enough.

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

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

Annotations already indicate this is not read-only and not destructive, and the description adds useful behavioral detail: existing data under the token stays, and a wrong or expired key changes nothing. This goes beyond the annotation hints by explaining failure semantics and safety of the operation.

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

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

The description is two sentences with no filler. It front-loads the core action, then gives the key format and safety guarantees, and closes with the verification tool. Every sentence contributes essential 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 single-parameter activation tool with annotations covering the safety profile, the description is complete: it states what the tool does, what input is needed, what happens on failure, and how to confirm success. There is no missing critical information for an agent to call it correctly.

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

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

The schema already documents the key parameter and its format with 100% coverage. The description adds meaning by specifying that the key must be issued at checkout for this server or the bundle, which clarifies validity requirements not present in the schema.

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

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

The description uses a specific verb and resource: it 'turns Pro on' for the connection using a license key. It also distinguishes itself from the sibling license_status tool by saying license_status confirms the activation. This leaves no ambiguity about what the tool accomplishes.

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

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

The description provides clear context for use: the key must be an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. It does not explicitly list exclusions or alternative tools, but it does reference license_status as the confirmation path, giving the agent a sense of the workflow.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context beyond annotations by specifying the JSON response contents and stating 'nothing changes,' reinforcing the read-only nature of the call.

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

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

Two dense sentences cover output, purpose, usage context, and side-effect guarantee. Every sentence earns its place and the most important information is front-loaded.

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

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

With no output schema, the description sufficiently describes the return value. With no parameters, annotations covering safety, and a clear use case, nothing essential is missing for an agent to invoke 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?

There are zero parameters and the schema already fully documents that fact. The description explicitly says 'No arguments,' which is accurate and reinforces the schema without needing further 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?

The description begins with a specific verb ('Report') and a precise resource ('this endpoint's licence state for your token'), and enumerates the exact output fields: product, tier, reason, and checkout URL. This clearly distinguishes it from sibling tools like license_activate.

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

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

The description explicitly states when to call it: 'Call it to explain a free-tier refusal.' This is clear contextual guidance, though it does not name alternatives or explicitly state when not to use it.

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

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

Annotations are all false, offering no safety or behavioral hints, so the description carries the burden. It adds useful behavioral context beyond the schema: the free-tier cap of 3 per month and the return values (reference, total, file path). It does not disclose side effects like overwriting, but that is covered in the schema's overwrite parameter, so this is not a significant 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?

Three sentences, each earning its place: the first states purpose and inputs, the second return values, and the third a usage limitation. Purpose is front-loaded and there is no vague, redundant, or promotional wording.

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 10-parameter tool with nested objects and no output schema, the description covers the key aspects an agent needs: purpose, input categories, return values, and a limitation. The schema covers parameter details. It does not mention the business_set profile dependency, but that is present in the schema, so the description is sufficiently complete for correct invocation.

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

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

Schema description coverage is 90%, so the schema provides detailed parameter semantics. The description only lists field names (summary, scope, deliverables, timeline, price, terms) without adding extra meaning about formats, defaults, or constraints, so it stays at the baseline for high coverage.

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

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

The description states a specific verb ('produce') and resource ('client-ready .docx proposal') and lists the content components, making it unmistakably a proposal-creation tool. The title reinforces creation, distinguishing it from siblings like contract_create and proposal_update without ambiguity.

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

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

The opening instruction 'Call this tool to produce a client-ready .docx proposal' gives clear context for when to use it, and the free-tier limit adds a constraint. However, it does not explicitly mention alternatives or when not to use it (e.g., for contracts or updates), so it stops short of full when/when-not guidance.

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

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

The description adds key behavioral detail beyond the annotations: it discloses in-place mutation, partial-update semantics ('Only the fields you pass change'), and the return value ('fields that changed and the file path'). Since all annotation hints are simply false, the description carries the burden well by explaining what the write operation does and returns.

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 concise sentences with no filler. The core action is front-loaded, the partial-update behavior follows immediately, and the return value closes it out. Every sentence adds relevant information.

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

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

For a 9-parameter tool with no output schema and no useful annotations, the description covers the most essential gaps: what is mutated, how much of the record changes, and what is returned. Minor gaps remain, such as not-found/error behavior and format expectations for fields like valid_until, but an agent has enough to invoke the update 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 low (11%), so the description must compensate; it does add important cross-cutting semantics by making clear that only passed fields are changed, which affects every parameter. The schema also gives a helpful reference description with an example and the free-tier implication. However, most parameters like valid_until, scope, and timeline still rely on names and types, with no format or value semantics 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?

The description uses a specific verb and resource: 'Rewrite an existing proposal in place from its reference.' It clearly distinguishes this from proposal_create by emphasizing 'existing' and 'in place,' so an agent can tell the two siblings apart. The 'Only the fields you pass change' clause further pins down the update-versus-create semantics.

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

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

The description gives clear context for when to use the tool: updating an existing proposal identified by reference, with partial-field patching. It does not explicitly name alternatives or state when not to use it, but the existing-in-place framing makes the intended use obvious against proposal_create.

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