NexDoc Design

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

Annotations already declare readOnlyHint and non-destructive behavior. The description adds useful behavioral context by naming the statuses and the required follow-up actions, going beyond what annotations provide.

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 filler. The core purpose is front-loaded, and the conditional workflow is compactly organized. Every sentence adds value.

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 status tool with an output schema and safety annotations, the description covers the key workflow and next steps. Nothing essential for invoking it correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate. It clarifies that file_id comes from request_file_upload or upload_file, but it does not describe format constraints or other details. This is adequate for a single simple parameter 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 clearly states a specific action ('Get upload status for a file_id') and ties it to the upload workflow. It distinguishes check_file from sibling check_run by focusing on file upload status rather than run status.

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

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

It gives clear contextual guidance on what to do after checking status ('ready' → pass file_ids to create_design or update_design; 'pending_upload' → PUT to upload_url first). It does not explicitly mention alternatives or when not to use the tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds valuable behavioral details beyond annotations: viewer_url is only present on completion, includes ?run=, and must never be reused from an earlier run. It also instructs 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?

Every sentence adds value: purpose, usage instruction, viewer_url behavior, caution about reuse, and concurrency notice. It is front-loaded with the core action and no fluff. Length is appropriate for the information density.

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 status-fetch tool with read-only annotations and an output schema (not shown but implied), the description covers all necessary behavioral aspects: field presence conditions, run_id usage, and user-facing notices. An agent can call this tool correctly without further assumptions.

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 clarifies run_id by instructing to pass THIS run's run_id after update_design, but job_id is left unexplained beyond being a required field. This partial compensation earns a 3; full compensation would explain both parameters explicitly.

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 clear verb ('Fetch') and specific resource ('run') with explicit output fields (status, charge_usd, viewer_url, error). It distinguishes itself from siblings like wait_for_run by focusing on fetching current status rather than blocking, and from check_file by naming 'run' directly.

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 context: use after update_design, pass THIS run's run_id, and never reuse previous run's viewer_url. It does not explicitly name alternative tools, but the guidance is strong enough to route the agent correctly. A mention of when to prefer wait_for_run would push it to 5.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds important behavioral specifics: omitting job_id always creates a new job, call at most once per request, concurrency_notice must be surfaced, notify_email should be set immediately, and after completion the user should see viewer_url. No contradiction with annotations exists.

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 main action and every clause carries necessary operational guidance. However, it is a single dense paragraph of semicolon-separated constraints, which is difficult to scan; grouped bullets or sections would improve readability without adding length.

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 full lifecycle: creation, retry/duplicate avoidance, email handling, file upload preferences, polling via wait_for_run, concurrency notices, and follow-up actions like offering export. With an output schema present, 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 description coverage is 100%, but the description adds meaningful decision-level semantics beyond the schema: file_ids are preferred, asset_files is a last resort, asset_paths cannot work on remote MCP, notify_email must be set early, and wait should be avoided. This is far more than repeating parameter names.

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 and resource: 'Create a job (or reuse job_id) and start a generative run.' This clearly distinguishes the tool from siblings like update_design and wait_for_run by naming the core outcome.

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: reuse job_id or use update_design if a job already exists, never call again without job_id for the same request, prefer request_file_upload for files, and use wait_for_run after creation. It also states exclusions like 'Do not set wait:true' and asset_paths being stdio-only.

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 it is not read-only and not destructive, so the description adds value by disclosing the short-lived nature of the download URL and the warning not to publish. It does not contradict annotations, and provides context beyond the structured fields, though it doesn't detail all side effects (e.g., file generation) or error conditions.

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 redundancy. The core action and formats are front-loaded, followed by usage guidance and a caution. Every sentence earns its place, and the structure is highly efficient.

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

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

Given the tool's moderate complexity (3 parameters, one enum) and that an output schema exists, the description adequately covers the essential context: what it does, how to choose format, and the key behavioral caution. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must explain parameters. It does explain the format enum values (pdf, html, png) with specific meanings (ZIP of site, ZIP of PNG pages). However, it does not clarify job_id or run_id semantics, especially run_id which is optional and less obvious. The description partially compensates but leaves gaps for non-format parameters.

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 (export a job), the resource (job), and the three output formats (pdf, html, png), and specifies the return of a 'short-lived download_url'. It also differentiates from the sibling tool publish_design by explicitly saying 'do not publish unless the user asks', making its role 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?

Provides explicit selection criteria for each format (pdf for print/slides/cards, html for web landing pages, png for images), and states it is the 'standard download step' while cautioning against publishing. This gives clear when-to-use guidance and distinguishes it from publish operations.

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?

The description adds the ordering behavior—'oldest first; the last entry is the latest run'—which is not available in the annotations or schema. The annotations already cover read-only and non-destructive behavior, so this extra ordering detail is meaningful behavioral context beyond what is structured.

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 with the core action and ordering detail front-loaded. There is no filler, and every clause adds meaning.

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

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

The tool is low-complexity: one required param, no enums, and an output schema is present. Annotations cover safety, and the description covers the key behavioral guarantee (ordering). No critical detail appears missing for an agent to call 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?

The input schema has zero description coverage for job_id, so the description carries the burden. The sentence maps job_id to 'a job' and clarifies the output ordering, but it does not add details about the ID's format, domain, or required existence. For a single, self-explanatory 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 opens with 'List runs for a job'—a specific verb plus resource with a scope qualifier. It clearly distinguishes this tool from siblings like list_formats, check_run, and wait_for_run by naming the resource and operation.

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 'for a job' gives a clear condition for when to use the tool, but it does not explicitly mention alternatives or state when not to use sibling tools. The context signal of a single job_id makes usage obvious, but the description leaves the choice of, say, check_run over list_runs to the agent's 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?

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?

Annotations are minimal (all false hints), so the description carries the behavioral burden. It discloses the core behavior: returns an upload_url, requires a PUT, and mandates follow-up with check_file. It could add details about failure modes or auth requirements, but the key workflow is transparent.

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

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

Four sentences, no waste. Purpose and usage are front-loaded, and the workflow steps are logically ordered. Every sentence adds value and the structure is easy to follow.

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 multi-step tool, the description covers the entire lifecycle: mint, PUT, check, and handoff to design tools. It also specifies allowed file types and contrasts with the sibling upload_file. Output schema exists, so return values are covered. 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 100% and all params have descriptions. The description reinforces semantics by noting 'same Content-Type' for content_type and 'exact byte size' for size_bytes, adding usage nuance beyond the schema. This justifies a 4 rather than a baseline 3.

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

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

Description states a specific verb ('Mint a presigned upload URL') and resource ('photo/logo/PDF'), and distinguishes from sibling upload_file by noting it's preferred for larger files and explicitly forbids base64 encoding into asset_files. This makes the tool's 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?

Explicitly states when to use (anything larger than a small icon), what not to do (do not base64, do not compress), and the full workflow: PUT original bytes, check_file until ready, then pass file_ids to design tools. This leaves no room for misinterpretation.

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 indicate destructive and open world. The description adds that it creates a new run, potentially destructive to previous run context, and provides wait policy. Mentioning not to share old preview and to show concurrency notice adds context beyond 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?

Dense and informative, each sentence adds action or constraint. Front-loads the core purpose and then details key behaviors. No fluff.

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

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

Given a complex tool with 11 params and output schema exists, the description covers critical behavior and error handling, file upload preferences, wait policy, and constraints. Complete enough for an agent to correctly invoke.

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 already provides detailed descriptions for most parameters, with 82% coverage. The description reinforces key guidance like preferring file_ids over base64. It does not add meaning for parameters not covered, but overall schema carries the burden.

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?

Description states it updates an existing job with diff-style edit instructionsJS。 It mentions creating a new run and uses the verb 'start an update run' with a specific resource, which is clear. It does not explicitly differentiate from create_design, but the diff-style edit focus implies the difference.

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 to wait once then offer email, to avoid looping, and to prefer file uploads over base64. It names alternatives like request_file_upload, upload_file, and wait_for_run, providing clear guidance on when to use them. Also tells not to share old viewer_url and to only share after completion.

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 that this tool reads from the client's disk, which is a key behavioral trait not fully captured by annotations. It also notes the limitation that Remote/OAuth MCP cannot read the client's disk. However, it doesn't detail side effects or error conditions, but the annotations already indicate non-read-only and non-destructive.

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 core action, then provides usage guidance and alternatives. Every sentence adds value, and the structure is logical: action, use case, workflow, and limitation.

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

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

Given the tool's simplicity (one parameter, clear output schema), the description covers all necessary context: what it does, when to use it, what to do with the result, and the limitation of remote MCP. The output schema exists, so return values are already documented.

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 provides 100% coverage for the single parameter 'path' with a clear description. The tool description adds context about the path being on the local machine, which reinforces the schema. Since schema coverage is high, the baseline is 3, and the added context about local path usage justifies a 4.

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 function: read a local path, upload it to NexDoc, and return a file_id. It distinguishes itself from sibling tools like asset_files and request_file_upload, 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 explicitly states when to use this tool (stdio MCP, large photos) and when not to (Remote/OAuth MCP), and names the alternative (request_file_upload and PUT). It also provides a clear workflow: pass 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?

Beyond readOnlyHint/destructiveHint flags, the description discloses the timeout default/cap, the at-most-once contract, the instruction not to reuse a previous viewer_url while still running, and how to surface concurrency_notice. It also defines follow-up behavior (show job_id and new run_id, only offer email if not already asked), which an agent could not infer from 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?

Every sentence carries operational guidance; the main purpose and timeout are front-loaded before behavioral rules. There is no filler or repetition of schema/annotations.

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

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

The description covers sequencing, recurrence limits, timeout behavior, viewer_url handling, concurrency_notice, and email-notification policy, so an agent can invoke the tool correctly. It slightly under-specifies the interval_sec parameter, but output schema and annotations cover the return/read-only side, making this a near-complete definition.

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 prose adds real meaning for run_id ('that run's run_id' from create/update) and timeout_sec (default 45, max 90, do not raise to loop). However, job_id's role is only implied and interval_sec is never described, and the schema itself covers only timeout_sec (25%), so the compensation is partial.

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

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

The opening sentence defines a specific action ('Poll a run'), the target resource, and the exact terminal outcomes (completed, failed, cancelled, or timeout). It also names the preceding tools (create_design/update_design), which separates this polling tool from status-reading 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 explicitly says to call at most once after create_design or update_design and to pass that run's run_id. It gives a when-not rule: if still_running is true, do not call again unless the user explicitly asks, and it points to notify_run_email as the conditional alternative.

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