NexDoc Design

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds behavioral context: it returns status (ready/pending_upload), notes that the response file_id is canonical after content dedup, and directs the PUT action for pending_upload. It does not mention failure modes, but the output schema likely covers that. 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?

The description is two sentences, front-loaded with the primary action. Every clause serves a purpose: origin of file_id, status handling, and canonical file_id. 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?

With an output schema present and annotations covering the safety profile, the description provides all necessary context: what triggers the tool, what to do with each status, and the dedup nuance. Nothing essential for correct invocation is missing.

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

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

Schema has one string parameter file_id with zero description coverage. The description compensates by explaining that file_id originates from request_file_upload or upload_file, and that the response returns a canonical file_id. This gives semantic meaning beyond the raw schema, though it doesn't detail format constraints (e.g., length) – not necessary given the context.

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

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

The description clearly states the tool's purpose: 'Get upload status for a file_id' and specifies the origin (from request_file_upload or upload_file). It differentiates from sibling check_run by targeting file uploads rather than runs. The verb 'get' and resource 'upload status' make the action 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?

It explicitly instructs when to use: after request_file_upload or upload_file. It also provides conditional follow-up actions: if ready, pass to create_design/update_design; if pending_upload, PUT to upload_url. This gives clear guidance on both when to call and what to do next, leaving no ambiguity.

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 indicate readOnlyHint=true, destructiveHint=false. The description adds behavioral context: viewer_url is only present when completed and includes ?run= for this generation; never reuse from earlier runs. It also mentions concurrency_notice. No contradiction.

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 concise and front-loaded with the main purpose. Important usage notes are placed early, and each sentence adds critical information without 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 fetch tool with an output schema that likely documents fields, the description covers key usage constraints (run_id, viewer_url handling). It omits specifics like response format or error cases, but the output schema mitigates that. Overall adequate.

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 parameters are just job_id and run_id with no descriptions. The description explains that run_id is the THIS run's run_id, but job_id is not explained beyond being required. It adds some value by clarifying run_id's role but does not fully compensate for the schema gap.

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

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

The description clearly states it fetches current status for a run with specific fields returned (status, charge_usd, viewer_url, error). It distinguishes itself from siblings like 'wait_for_run' and 'list_runs' by focusing on a single run's current status after an update.

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 explicit instructions: pass THIS run's run_id after update_design, do not look up the previous run, never reuse a viewer_url from an earlier run. Also specifies handling of concurrency_notice. This is clear guidance on when and how to use.

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?

Although annotations already signal destructiveness and non-readonly behavior, the description adds critical operational details: duplicate job creation on omitted job_id, 409 rejection while a run is queued/running, concurrency_notice handling, email notification timing, and the recommendation to avoid wait:true. This goes well beyond the annotations and meaningfully shapes agent behavior.

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

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

The description is long but dense with operational directives, and the most critical constraint ('call at most ONCE per user request') is front-loaded. Every sentence carries behavioral weight. The main weakness is the single-wall-of-text format; bullet or section structure would improve parseability, 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 complex, destructive creation tool with 12 parameters, the description covers the full lifecycle: creation, retry/reuse rules, file upload precedence, error/409 handling, wait_for_run handoff, email notification, and post-completion actions like returning viewer_url and offering export. With an output schema present, no critical information is missing for an agent to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial cross-parameter meaning: wait:true should be avoided, asset_paths is stdio-only, asset_files is a last resort while file_ids is preferred, and notify_email should be set immediately when the user asks to be emailed. These constraints are not inferable from the schema alone.

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

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

The description opens with a precise verb+resource statement: 'Create a job (or reuse job_id) and start a generative run.' It also differentiates from siblings by explicitly naming update_design and wait_for_run as related but distinct tools. An agent can immediately understand what create_design does and how it differs from other design-flow 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 gives explicit when-to-use and when-not-to-use guidance: call at most once per user request, always reuse an existing job_id rather than calling again, use update_design for continuations, prefer request_file_upload/upload_file for photos, and never set wait:true. This is strong routing and exclusion guidance that leaves little to inference.

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

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

Annotations carry no read-only or destructive hints, so the description carries the burden. It adds meaningful behavioral detail: the result is a short-lived URL, and it frames the operation as a standard, non-publishing step. It does not contradict annotations, though it omits explicit side-effect disclosure (e.g., whether the job is modified), which 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?

Two sentences deliver all necessary information: the action, formats, return type, usage preferences, and an exclusion. The most critical facts are front-loaded, and there is no redundant or filler content.

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 3 parameters (2 required, one enum) and an output schema, the description covers the essential call-time details: what it does, output format, URL lifetime, and usage routing. The missing run_id explanation and lack of explicit side-effect notes are minor gaps, but the presence of an output schema reduces the need to describe return structure.

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 compensate. It explains the format parameter thoroughly with per-format usage context, and job_id is implicitly clear as the job to export. However, the optional run_id parameter is not mentioned at all, leaving its purpose ambiguous for an agent, though its optionality reduces the impact.

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 ('Export') and resource ('a job'), lists the three output formats (pdf, html, png) with their packaging details, and states the return value (short-lived download_url). It distinguishes itself from siblings by explicitly noting it is the 'standard download step' and contrasting with publishing, making its purpose 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?

The description gives explicit format-selection guidance ('Prefer pdf for print/slides/cards; html for web landing pages; png when the user wants images') and a clear exclusion ('do not publish unless the user asks'), telling the agent exactly when to use this tool and when to avoid alternatives like publish_design.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the 'authenticated' qualifier and the exact fields returned, which is useful context, but it does not go deeper into behavior such as balance freshness, caching, or auth requirements beyond the word 'authenticated.'

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 sentence with no filler. The verb and resource are front-loaded, and the parenthetical list conveys the exact scope efficiently. Every word 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 zero-parameter, read-only wallet summary tool, the description is complete: it says what the wallet summary includes, annotations cover the safety profile, and an output schema exists to define the return shape. No essential invocation 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?

The tool has zero parameters and 100% schema description coverage, so there are no parameter semantics to explain. The baseline for a zero-parameter tool is 4, and the description appropriately focuses on the return content instead.

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 ('Get'), a specific resource ('authenticated org wallet summary'), and enumerates the included fields (USD balances, plan, concurrent_run_limit, auto-topup, past_due). This clearly distinguishes it from the sibling file/run/design tools, which have different domains.

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: this tool is for retrieving the org wallet summary. No when-not-to-use guidance or alternative tool is mentioned, but no sibling appears to be a wallet-related alternative, so exclusions are not required. Still, it does not explicitly state a selection rule.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds value by indicating the output includes selection guidance, not just raw slugs. However, it does not disclose any additional behavioral details such as whether the list is static, ordered, or affected by context; for a simple 0-parameter listing tool, this is acceptable.

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 a single, tight sentence with no wasted words. It front-loads the verb and resource, then appends the guidance detail. Every word 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 0-parameter, read-only listing tool with an output schema present, this description is complete. It states what the tool returns (format slugs) and what extra value it provides (selection guidance). Nothing an agent needs to invoke it correctly is missing.

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

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

The tool has 0 parameterstons, so there is no parameter burden. The schema coverage is trivially 100% (empty properties). Per the rubric, 0 params gives a baseline of 4, and the description does not need to add parameter-level semantics.

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 ('List') and names the resource ('supported NexDoc Design format slugs'), and adds that it provides selection guidance. This clearly distinguishes it from sibling tools like list_runs or check_file, which deal with runs and files rather than formats.

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 'with selection guidance' signals when to use this tool: when an agent needs to know which format slugs are available and which one to pick. It does not explicitly name alternatives or exclusions, but since this is a standalone listing tool with no direct sibling, the context is sufficient.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the ordering behavior ('oldest first; the last entry is the latest run'), which is a meaningful behavioral detail beyond the annotations. It does not contradict them.

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 a single sentence, front-loaded with the action and resource, and includes the ordering detail without any waste. Every word 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 simple read-only list tool with one parameter, an output schema (which covers return format), and annotations covering safety, the description is complete. It states the purpose and ordering, and nothing critical is missing 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?

Schema coverage is 0%, so the description must compensate. It adds that job_id is the job for which runs are listed, giving some meaning beyond the bare string type. However, it does not provide format details, constraints, or examples, leaving the parameter under-documented.

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 'runs for a job', and adds ordering context ('oldest first; the last entry is the latest run'). It distinguishes itself from siblings like check_run (which likely handles a single run) and wait_for_run (which waits on a run).

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 no guidance on when to use this tool versus alternatives such as check_run or wait_for_run. It only states what the tool does without any context on selection criteria or exclusions.

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

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

Goes well beyond the annotations by describing edge-case behavior: sends immediately if the run is already terminal, reports when an email was already sent, and avoids duplicates. This aligns with and enriches the destructiveHint/openWorldHint 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?

Four sentences with clear hierarchy: core action, primary invocation condition, terminal-state edge case, and duplicate-prevention behavior. No filler or redundant restatement of the name or schema.

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

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

With an output schema presentable and annotations covering side effects, the description covers purpose, timing, and idempotency well. However, the complete absence of parameter guidance means an agent may struggle to construct a correct call, especially if it does not already know where job_id and run_id come from.

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 does not explain job_id or run_id, how they relate to each other, or where the agent should obtain them. The parameter names are suggestive, but the description fails to compensate for the missing schema details.

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 ('Email'), a clear recipient ('authenticated account'), and an explicit trigger ('when this run finishes') with enumerated terminal states. No sibling tool overlaps with this purpose, so differentiation is inherent.

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 instructs when to call it: whenever the user asks to be emailed, including after wait_for_run and even after the run has already finished. It does not name exclusions or alternative tools, but no sibling directly competes with this notification behavior.

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 convey readOnlyHint=false and destructiveHint=true, so the agent knows this is a mutating, potentially destructive action. The description adds that the job is exposed at a public URL, which is useful context beyond the annotations. However, it does not discuss side effects (e.g., whether the URL can be taken down, or if approval is needed), so it stays at a moderate score.

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 wasted words, and the core purpose is front-loaded. The second sentence is a highly valuable usage warning. Every character 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?

The description nails the usage trigger and overall purpose. However, it fails to define run_id or clarify what 'public URL' means in terms of access or reversibility. The existence of an output schema and annotations mitigates return-value and safety gaps, but the parameter and behavioral gaps leave it merely adequate, 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%, so the description must compensate, but it does not. It never mentions job_id or run_id. The word 'job' implicitly maps to job_id, but run_id remains completely undefined. The agent has to guess what parameters mean, making this a serious gap.

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

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

The description uses a specific verb and resource: 'Publish a job to a public URL.' It clearly states the effect and differentiates from siblings like export_design and unpublish_design by focusing on making a design publicly accessible. The explicit trigger ('ONLY call this when the user explicitly asks...') reinforces the distinct purpose.

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 explicit when-to-use guidance ('when the user explicitly asks to publish or make the design public') and when-not-to-use ('never as a default step after create/export'). This is clear, unambiguous, and directly helps the agent decide between this and 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?

The annotations provide only readOnlyHint=false, openWorldHint=false, and destructiveHint=falseaborate. The description adds valuable behavior beyond that: after an in-progress update, the preview still shows the previous design, and the URL can expire or return 401. It does not mention auth prerequisites or side effects, so it stops short of 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?

Three concise sentences front-load the core purpose, then cover the stale-snapshot caveatchen, then give routing guidance. Every sentence contributes distinct information with no filler.

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

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

Given the low complexity (one required parameter) and the presence of an output schema, the description covers purpose, usage timing, a stale-state caveat, and the preferred alternative. Nothing needed for correct selection or invocation is missing.

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

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

Schema coverage is 0% and the description does not explain job_id directly. However, the phrase 'a job's current snapshot' supplies enough context to infer that job_id identifies the job whose preview is being refreshed. For a single simple required string parameter, this is adequate but not rich.

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 ('Mint a fresh viewer_url') and ties it to a job's current snapshot. It is clearly distinguishable from sibling tools like check_run or export_design because it names the artifact produced and the condition it addresses.

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 explicitly says when to use this tool ('Use this when a completed preview link expired or 401s') and when to prefer a sibling instead ('Prefer check_run on the new run_id and only share that viewer_url when status is completed'). This gives an agent precise 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?

Beyond the annotations (readOnlyHint false, destructiveHint false, openWorldHint false), the description discloses the conditional reuse behavior (already_uploaded skips PUT), the requirement to PUT original bytes with the same Content-Type, and the need to poll check_file before proceeding. It does not contradict annotations and adds meaningful workflow context, though it omits error handling or auth-specific details.

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 sentences: purpose, preference/alternative, and workflow. Every clause carries necessary information and the main action is front-loaded. It is dense but not padded, slightly long due to the complex workflow, but well structured.

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 4-parameter tool with an output schema, the description covers the full lifecycle: when to call, what to pass, how to handle the response (already_uploaded vs PUT), and integration with sibling tools (check_file, create_design, update_design). It leaves little ambiguity, though it could mention error cases or prerequisites like authentication.

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 all parameters are already documented (e.g., content_sha256's deduplication role is fully explained in the schema). The description adds workflow context (e.g., size_bytes must match the PUT, content_sha256 is optional) but mostly reinforces schema text, so the baseline of 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 opens with a specific verb and resource ('Mint a presigned upload URL') and scopes it to photo/logo/PDF. It explicitly contrasts with the sibling upload_file and warns against base64-ing into asset_files, so an agent can distinguish it from siblings 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?

It states a clear preference rule ('Preferred for anything larger than a small icon — do not base64 the file into asset_files and do not compress or generate a replacement') and provides a step-by-step after-action workflow: skip PUT if already_uploaded, otherwise PUT original bytes with the same Content-Type, poll check_file until ready, then pass file_ids to create_design or update_design. This is explicit when/how and names the 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 destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation. The description adds the context that it affects a 'public site' and is only for taking down a published design, which is useful. However, it doesn't disclose what happens to the design itself (e.g., whether it remains editable, whether the URL becomes inaccessible immediately) or any irreversibility beyond the annotation.

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 with no wasted words. The core action is front-loaded, and the usage condition is stated directly. Every word 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 single-parameter tool with a clear name and sibling context, the description is nearly complete. The output schema exists, so return values are covered. The only gap is the lack of detail on the parameter's meaning, but the tool name and description make it obvious that job_id refers to the job whose design is being unpublished.

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

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

Schema description coverage is 0%, so the description must compensate for the undocumented job_id parameter. The description mentions 'a job's public site,' which implies job_id identifies the job, but it doesn't explicitly explain that job_id is the identifier or provide any format details. With only one parameter and a clear name, the baseline is 3, and the description adds minimal but non-zero context.

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

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

The description clearly states the action ('Unpublish a job's public site') and the resource (a job's public site), distinguishing it from its sibling publish_design. It could be slightly more specific about what 'unpublish' entails (e.g., removing the site or making it private), but the verb and resource are clear.

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 a clear usage condition: 'Only when the user asks to take a published design down.' This tells the agent when to use the tool, and the sibling publish_design implies the alternative. It doesn't explicitly state when not to use it, but the condition is specific enough to guide selection.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is covered. The description adds valuable behavioral context: the 409 rejection on concurrent runs, the need to report job_id and NEW run_id, not sharing the old viewer_url, the concurrency_notice reminder, and the wait-then-email policy. It doesn't detail failure modes beyond 409, but the annotations plus description cover the critical behaviors.

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 dense but every sentence carries operational guidance. It front-loads the core action and the most critical constraint (never update while running). It's longer than ideal, but for a complex mutation tool with 11 parameters and multiple sibling tools, the length is justified. The structure could be slightly improved by grouping related constraints, but it's well-organized.

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

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

For a complex mutation tool with 11 parameters, destructive annotations, and 15 sibling tools, the description covers the full decision tree: when to call, what to avoid, how to handle files, what to report, and what to do after. The output schema exists, so return values don't need explanation. The only minor gap is not detailing the exact 409 error handling flow, but the description explicitly says to wait and report.

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 82%, so the schema already documents most parameters. The description adds meaningful guidance beyond the schema: the diff-style nature of instructions, the file upload preference chain (request_file_upload → upload_file → asset_files → asset_paths), and the warning against base64 for large images. It doesn't explain every parameter, but the schema covers those, and the description adds the decision logic.

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

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

The description opens with a specific verb+resource: 'Start an update run on an existing job with edit instructions (diff-style).' This clearly distinguishes it from create_design (new job) and refresh_preview (preview refresh), and the diff-style qualifier adds precision. The title 'Update design' is generic, but the description fully compensates.

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 explicit when-to-use guidance: never update while a run is queued/running (409), wait for run completion, and only cancel/re-run on explicit user request. It also names sibling tools (wait_for_run, request_file_upload, upload_file, upload_data) and states the same wait policy as create_design. This is exemplary 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 only mark the operation as non-read-onlyasi, but the description adds meaningful behavioral detail: uploads go through the existing MCP session host, there is a ~20MB size ceiling, and corrupt bytes should not be uploaded. It also discloses the successful result shape by mentioning the returned file_id.

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

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

The description is front-loaded with its core purpose and every sentence serves a purpose, including alternatives, constraints, and validation guidance. It is somewhat dense and repeats part of the schema's decoding warning, and the phrase 'for file_ids' is underexplained, which keeps it from being perfectly concise.

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 this complexity, the description covers the key decision context, constraints, corruption handling, alternatives, and expected output. The presence of an output schema means return-value details do not need to be restated, and nothing essential for correct invocation is missing.

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

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

Schema coverage is already 100%, so the baseline is a 3. The description adds some value by emphasizing local decode checks and the size limit, but much of the base64-integrity warning is already present in the data_base64 parameter description, so the extra semantic lift is moderate.

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 identifies upload_data as a base64, API-host upload that returns a file_id, and differentiates it from the presigned-PUT path and asset_files usage on create_design/update_design. The 'remote-safe' qualifier and base64 mechanism make its role specific and distinguishable from related upload 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?

It states exactly when to use the tool—sandboxed clients whose egress blocks PUTs—and when not to: files over ~20MB or cases where a presigned PUT is possible. It also gives a concrete pre-upload validation workflow, telling the agent to decode locally and report corruption instead of uploading.

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 goes well beyond the sparse annotations by disclosing that it is stdio-only, hashes file content, deduplicates by matching content, and returns a ready-to-use file_id. It also explains the critical limitation (cannot read disk over remote/OAuth) that the annotations alone would not convey.

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

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

Three dense sentences cover operation, dedup, alternative tools, and downstream usage with no filler. The most important constraint ('stdio MCP only') 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?

Given the tool's complexity, the description fully covers what it does, when to prefer it, when to avoid it, and what to do with the result. The presence of an output schema relieves it from explaining return details, and no necessary behavioral context is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches the single path parameter by explaining that the path must be a local, client-side file readable by stdio MCP and that its bytes are used for SHA-256 content matching. This adds practical meaning beyond the schema's 'absolute or relative path'.

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 precise verb and resource: reads a local path, SHA-256s the bytes, uploads to NexDoc, reuses an existing matching file, and returns a file_id. It also distinguishes this from request_file_upload by transport, and from asset_files by use case, so an agent can tell it apart from siblings.

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

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

Explicit when-to-use guidance is present: 'Use this instead of asset_files for large photos' and 'Remote/OAuth MCP cannot read the client's disk — use request_file_upload... instead.' It also chains the tool into the workflow by directing file_ids to create_design or update_design.

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 it read-only, and the description adds behavioral context beyond annotations: terminal-state handling, default/max timeout, the instruction not to raise the timeout to keep looping, and post-result requirements like not sharing a previous viewer_url and showing concurrency_notice. 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?

The description is front-loaded with the core polling behavior, then gives one-shot usage, then conditional output handling. Every sentence carries operational value, and there is no filler.

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

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

Given the output schema exists and the tool has complex follow-up behavior, the description covers all agent-facing decisions: when to call, timeout limits, how to interpret still_running, and when to offer notify_run_email. Nothing essential for correct invocation is missing.

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

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

Only timeout_sec has a schema description, giving 25% coverage. The description adds useful context for run_id and timeout_sec, but job_id and interval_sec remain undocumented in both the schema and the description, so the low parameter coverage is only partially compensated.

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 ('Poll a run until completed, failed, cancelled, or the timeout') and ties it to run IDs from create_design/update_design. This makes the tool's purpose clear and distinguishable from lighter-status siblings like check_run.

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

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

It gives explicit call timing ('at most ONCE after create_design or update_design'), a when-not rule ('do not call this tool again unless the user explicitly asks'), and an alternative path via notify_run_email under a clear condition. This fully satisfies the when/when-not/alternatives criterion.

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