meeting-notes-transcript-summary

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?

Annotations already flag destructiveHint=true and openWorldHint=false, so the safety profile is carried structurally. The description adds genuinely non-redundant context: the per-token scope of the deletion and the fact that a bad name is refused with no side effects, which is the key behavioral question for a destructive 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?

Three short sentences, front-loaded with the action and scope, followed by name format and failure behavior. 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?

For a one-parameter destructive tool with no output schema and full annotation coverage, the description supplies everything missing: name format, name discovery, token scoping, and no-op-on-miss 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 0%, so the description must carry the parameter's meaning — and it does: "name" is the upload name without the .docx extension, with doc_files as the way to obtain one. This is exactly the disambiguation an agent needs to avoid passing a filename.

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 ("Delete one document") plus its scope ("uploaded for your token"), which separates it cleanly from doc_upload, doc_read, and doc_files. An agent can identify the operation 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?

Explicitly routes the agent to doc_files to discover valid names, and states the outcome when the name is unknown ("refused and nothing is deleted"). It doesn't name a when-not-to-use case, but for a single-purpose delete tool the guidance 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds useful scoping ('for your token') and the shape of returned items ('sizes'), but says nothing about ordering, pagination, or what happens with zero uploads.

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 front-loaded sentence with zero filler. It is arguably too terse for a listing endpoint, 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 parameterless read tool with full annotation coverage, the definition covers scope and roughly what comes back. Minor gaps remain around pagination limits and whether metadata beyond size is included, which matter for an inventory call.

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 for the description to disambiguate; baseline 4 applies. The description correctly implies no inputs are required to enumerate the token's 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 ('List') and resource ('documents uploaded for your token') plus partial return content ('with their sizes'), which separates it from content-oriented siblings like doc_read. It stops short of naming which sibling to use instead, but the scope is 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?

No statement of when to use this versus doc_read, doc_files-style listing, or the upload/delete siblings; the only hint is the 'for your token' scope. An agent must infer that this is the inventory call before reading or deleting a 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?

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?

Adds substantial context beyond the annotations: uploads persist per token across calls, files are stored under the supplied name (defaults 'inline'/'template'), and deletes go through doc_delete_upload. It also discloses fetch limits (10s timeout, 3 redirects, public http(s) only, 2 MB cap). The one gap is that destructiveHint=true is never made explicit — the description implies re-uploading under an existing name overwrites it, but never says so outright.

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 essential model (upload once, reference by name), then details. It is a dense single paragraph with a long parenthetical of fetch constraints, but nearly every clause carries operational information; only the download-link sentence is tangential to the upload action.

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 3-parameter storage tool with no output schema, the description covers lifecycle (persisted per token, removable via doc_delete_upload), naming semantics, fetch safety limits, and the sibling hand-off. An agent has everything needed to call it and to know what to do afterward.

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

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

Schema coverage is 100%, so baseline is 3, but the description contributes a constraint the schema does not encode: the exclusivity of docx_base64 vs url (the schema has no oneOf, only `name` is required). It also repeats the size-based selection advice with the operational rationale rather than just restating the field docs.

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 ("Send an existing Word document to this hosted endpoint") and immediately explains the non-obvious framing: there is no filesystem, so upload once and reference by name. This distinguishes it cleanly from doc_read, doc_to_html and doc_fill_template, which consume the uploaded name.

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

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

Explicit routing rules: "Give exactly one of docx_base64 or url", plus a concrete heuristic for choosing (url recommended above ~10 KB because a 13 KB base64 paste takes minutes). It also names the cleanup path (doc_delete_upload) and notes that doc_read/doc_fill_template can bypass this tool entirely by taking docx_base64 directly.

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.