奇妙生产力 · Qimiao Productivity

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

Goes beyond the annotations by disclosing a key side-effect boundary: cancellation does NOT trigger a refund, and refund requests must be routed to human support via email. That is genuinely useful context an agent cannot derive from readOnlyHint=false / destructiveHint=false / idempotentHint=true. It does not mention auth requirements or what state the order ends in, so it falls 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?

A single tight sentence with the action front-loaded and the refund/feedback caveat following. No padding, though the refund and feedback points could be split for faster scanning.

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?

An output schema exists and annotations cover safety/idempotency, so the description doesn't need to explain returns. But for a mutation tool with three undocumented required parameters, the description leaves an agent guessing about credential and request_key semantics, which is a meaningful completeness gap.

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

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

Schema description coverage is 0% and there are three required parameters (credential, service_id, request_key) with only regex patterns to hint at their form. The description says nothing about any of them — not what credential is, not that service_id must be an LX- identifier, not what request_key is for (idempotency). This is a clear miss against the low-coverage compensation requirement.

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

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

States a specific verb and resource ('取消...任务' = cancel a not-yet-completed task), which is distinct from sibling tools like create_order, get_order, request_change, and wait_order. It doesn't explicitly contrast against the nearest sibling (request_change), but the action and its scope are 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?

Adds one precondition ('尚未完成的任务' — only tasks not yet finished) which implies when the tool applies. However, it never names an alternative for related needs such as changing or refunding an order, so the agent must infer the routing (feedback/refunds handled by email) without a tool-level comparison.

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 only declare the generic profile (not read-only, open world, non-idempotent, non-destructive), while the description adds details that the agent could not otherwise infer: the authorization persists until revocation or account disablement, is independent of browser session length, the connection entry itself lapses after 10 minutes, historical services are not auto-claimed, and no charge can occur without confirmation. It also states a critical security boundary: passwords and verification codes are entered only on the original site. This is exactly the behavioral context that annotations cannot 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?

The purpose is front-loaded in the opening clause, and the remaining clauses are packed with non-obvious constraints rather than filler. The middle section is a long semicolon-chained sentence, which makes it dense to parse, but nearly every clause carries real operational weight.

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

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

For a zero-parameter, open-world authorization tool with an output schema and annotations, the description covers the full flow, the validity windows, the failure modes it deliberately avoids, and how to handle the returned credentials. An agent has everything it needs in order to guide the user correctly without opening the schema.

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

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

The tool takes no parameters at all, so there is nothing for the description to disambiguate, and a baseline of 4 applies. The mentions of connection_id and connection_credential describe the outputs to be stored privately rather than inputs, and an output schema already exists to cover the return shape.

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 first clause names a specific verb and resource: generating a first-party account connection page plus a six-digit connection code, at no cost. An agent immediately knows this is the account-linking entry point rather than a query or mutation of orders. It does not explicitly contrast itself with disconnect_account or get_connected_account, so it falls short of full sibling differentiation.

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 lays out the operating context: the user must log in to the original site themselves, enter the code, and explicitly confirm long-term authorization. It also implicitly excludes the retroactive case ('does not auto-claim historical services') and unconfirmed charges. What is missing is an explicit 'use this when…' statement or a pointer to the sibling tools that handle revocation or inspection.

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 flag readOnly=false, idempotent=true, destructive=false, openWorld=true; the description goes well beyond them. It discloses that paid quotes create a payment order, that owner_checkout_url is returned privately with read-only access and a 30-minute window, that it cannot be claimed or rotated, and that only checkout_url may be forwarded for delegated payment. That is exactly the side-effect and credential-handling context an agent needs before invoking a mutating, open-world tool.

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

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

The core action and its free/paid branching are front-loaded, and every clause (checkout_url lifetime, forwarding rule, confirmation gate) carries distinct information. It is a single dense run-on sentence with semicolons, which makes scanning harder than it needs to be.

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?

An output schema exists, so return values needn't be explained, and the behavioral branching is well covered. However, with four required parameters at 0% schema coverage and no parameter explanation at all, plus no statement of system prerequisites (which prior tool produces contract_id), the definition leaves a meaningful gap for a mutating tool.

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 all four parameters are required, including a 32-200 char credential and a pattern-constrained request_key. The description never mentions service_id, credential, contract_id, or request_key, so an agent gets no meaning for any of them — notably no hint that request_key is an idempotency key or that contract_id comes from the confirmed quote.

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 (启动任务 / create order) and distinguishes two concrete branches: zero-price quotes launch the original free task with no payment order, while paid quotes generate a payment order. It is clearly not quote_order or prepare_task because it is the 'user-confirmed agreement' step, but it never names the sibling it most resembles (pay_with_balance) or clarifies how the two relate.

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 preconditions are given: do not start without user confirmation, and if payment status is uncertain, query the original order instead of starting. That is a real when-not-to-use and an alternative path. The gap is that the alternative is described only as '查原单' rather than naming get_order, and no guidance distinguishes this tool from prepare_task or pay_with_balance.

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 the safety profile (not read-only, idempotent, not destructive), and the description adds genuine post-condition context: after revocation, balance payments stop working until the user reconnects and confirms. It does not say whether the credential is invalidated or whether the operation is reversible, which would complete the picture.

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

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

A single front-loaded sentence that leads with the action and appends the consequence. No padding or repetition.

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

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

An output schema exists so return values need not be described, but with both parameters undocumented and no note on retrieving/validating the credential, the definition leaves the agent short of what it needs to invoke this mutation confidently.

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 says nothing about connection_id or connection_credential. The regex pattern and length bounds hint at format, but there is no guidance on where the agent obtains the credential or what it authorizes — a real gap for a 2-required-param call.

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 (撤销/revoke) and resource (本Agent的账号连接/this agent's account connection). It is clearly the inverse of connect_account among the siblings, though it never names that sibling explicitly. An agent can tell what it does 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?

The clause about subsequent balance payments requiring reconnection and user confirmation implies the reason to call it, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g. connect_account to reverse it). Usage must be inferred.

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 already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, and the description is consistent with them ('只读，不扣款'). It adds real context beyond those annotations: the response includes a masked account and available balance, and the call transparently re-handshakes when the connection is not logged in or has expired. It still omits how a credential is obtained or what the response looks like on failure.

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 dense clause with no filler, and the primary action comes first, followed by the fallback behavior and the safety note. Its compactness is appropriate, but the credential requirement is compressed into an unexplained phrase.

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?

An output schema exists, so return values need not be described. However, for a tool that requires a patterned ID plus a 32–200 character secret, the description leaves the agent with no guidance on obtaining either value or on how this tool relates to connect_account and disconnect_account in the connection lifecycle.

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 has 0% description coverage, and both parameters (connection_id with its MC- pattern and connection_credential) are completely undocumented. The description says '凭私有连接' but never explains what a private connection is, where the credential comes from, or how it relates to connect_account, so the agent must infer both required values.

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 and a set of resources: query connection status, masked account, and available balance. It implicitly distinguishes the tool from mutation siblings such as connect_account, disconnect_account, and pay_with_balance by stating '只读，不扣款', but it never names those siblings explicitly.

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

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

The description implies that the tool is for checking connection state, and it mentions a failure condition ('未登录或连接过期时重新连接'), but it does not say which sibling to use instead. It does not make explicit whether the agent should call this before other tools or what to do when the call fails, so usage remains implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds value by disclosing that access is gated on a per-order working credential and that refund/feedback paths are out of scope and require human contact — context not present in the annotations.

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

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

A single dense sentence with the primary purpose front-loaded and the out-of-scope routing in a trailing clause. Nothing is redundant; it could only be improved by splitting the usage exclusion into its own short sentence.

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?

An output schema exists, so return values need no explanation, and the description covers the status domains queried plus the credential requirement. Minor gaps remain around how a caller obtains the credential and behavior on invalid input, but the definition is sufficient to invoke 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 carry the burden. It clarifies that credential is the order's working credential, which adds meaning beyond the bare minLength/maxLength constraint, but it says nothing about service_id or its required 'LX-' + 32 hex format, leaving one of two params entirely undocumented.

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 ('查询' / query) and enumerates the exact resource facets returned: payment, fulfillment, interaction and delivery status. It is clearly a read-status tool, distinguishably different from siblings like pay_with_balance or cancel_order, though it does not name a sibling explicitly.

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 the precondition for use ('凭本单工作凭据' — with this order's working credential) and gives an explicit exclusion: feedback and refunds must go to a human via the email in the rules. That routing guidance is genuinely useful, but it does not cover adjacent cases such as what to do if the credential is invalid or when to prefer get_run_result.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld, so the safety profile is fully covered elsewhere. The description adds what kind of state is surfaced (steps, pending questions, versions), which is genuinely useful context, but says nothing about ordering, pagination, or credential requirements.

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

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

A single front-loaded sentence with the verb first and no filler. It is brief, though it is brief partly because important parameter and usage details were omitted rather than compressed.

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?

An output schema exists, so return values need not be explained, and annotations cover behavior. Still, for a two-required-parameter call with zero schema descriptions, the definition leaves the agent without guidance on the credential or the service_id pattern, and offers no routing versus sibling read tools.

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

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

Schema description coverage is 0% for both required parameters (service_id, credential), yet the description does not compensate at all — no mention of the LX-… identifier format or what the credential represents. This is the biggest gap for an agent trying to construct a valid call.

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 (读取/read) and enumerates the concrete resources returned: persisted steps, pending questions, and delivered versions. It is reasonably distinguishable from get_run_result and get_service_overview, though it never names those siblings to sharpen the boundary.

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

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

There is no indication of when to choose this over get_run_result, get_service_overview, or get_task_materials, all of which sit adjacent in the sibling list. Usage is only implied by the noun list, with no conditions or exclusions stated.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real value beyond them: file links are valid only ~15 minutes, and re-fetching is the correct recovery rather than redoing the task. It does not disclose auth/permission requirements tied to the credential parameter.

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 semicolon-joined sentence with zero filler: precondition first, then return payload, then expiry behavior and the recovery rule. Front-loaded and appropriately sized.

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?

An output schema exists, so return-value detail is unnecessary, and the delivery precondition plus link expiry are well covered. However, for a tool requiring a pattern-constrained service_id and a 32+ char credential with no schema descriptions, the absence of any parameter guidance leaves a real completeness gap.

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

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

Schema description coverage is 0% across three parameters (service_id, credential, version), yet the description mentions none of them. With no field-level documentation anywhere, the agent gets no guidance on the service_id pattern or what version selects, so the description fails to compensate for the coverage 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?

States a specific verb (获取/get) and concrete resources: the delivered 正文 (content), manifest, and time-limited file links, scoped to after successful delivery. It is clearly distinct from sibling get_run_events (events) and get_order (order state), though it does not name an alternative explicitly.

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

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

Gives a clear precondition (成功交付后, only after successful delivery) and an operational rule for the failure path: if links expire, re-fetch rather than re-running the task. It lacks explicit 'use X instead when…' routing against siblings such as get_run_events, keeping it 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 readOnly/idempotent/non-destructive/openWorld, so the description's job is to add nuance, and it does: it is free of charge and performs no order creation. It does not mention call volume, rate limits, or whether 'full' is a strict superset of 'compact', which is the remaining ambiguity.

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

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

Front-loaded with the purpose, then the mode recommendation, then the scope exclusion in a single dense but well-ordered passage. Every clause adds information; the only cost is that the mode guidance and the 'what full mode contains' clause are packed together in one long sentence.

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?

An output schema exists, so return format need not be described. Given a single optional enum parameter and full annotation coverage, the description supplies everything an agent needs: what it is, which mode to pick, where to go next, and the fact that it has no write side effects.

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

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

With 0% schema description coverage, the description carries the weight and succeeds: it names both enum values, explains what 'compact' returns (grouping + delivery summary) versus 'full' (inputs, live pricing, examples, connection methods), and states the default. It stops short of clarifying whether full mode also includes the compact summary.

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 the resource clearly ('了解奇妙生产力当前的文件制作与实用工具') and frames the tool as a free overview whose output is a grouping and delivery summary, so an agent can tell it apart from get_tool and search_tools. It never says the explicit noun 'catalog/list of services', which keeps it one step short of a 5.

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

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

It gives an explicit recommended path — use mode=compact first, then go deeper with search_tools/get_tool — plus the default (full mode) if detailed inputs, pricing and examples are needed. It also states the boundary '不创建订单', ruling out the order-creating siblings (create_order, prepare_task) unambiguously.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds that reading is free and scopes the content to terms/policies, which is mild additional context, but says nothing about authoritative freshness or how it relates to sibling read tools.

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 compact sentence enumerating the covered topics, so it is efficiently sized. The decorative adjective '奇妙生产力' adds no retrievable meaning and slightly buries the core 'service rules' framing.

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?

Return values are covered by the existing output schema and there are no inputs to document, so the remaining burden is disambiguation. The description lists the policy topics but never tells an agent why to pick this over get_service_overview, leaving a meaningful gap.

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

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

The tool takes zero parameters, so the schema is trivially complete and the description need not explain inputs. Baseline of 4 applies.

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 read-only action ('免费阅读') and enumerates the content covered (platform/capability summary, fees, delivery, storage, retrieval, after-sales terms). However it never frames this as a 'service rules/terms' tool in a way that clearly separates it from the sibling get_service_overview, and the marketing phrasing ('奇妙生产力') dilutes the signal.

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

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

There is an implied two-step order ('再查看'), but no statement of when to call this versus get_service_overview or the order/payment tools. No prerequisites, no exclusions, no alternatives are named despite a dense sibling set.

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

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

Adds real context beyond annotations: hash verification, format-limit parsing, and — importantly — that short-lived upload links may be refreshed as a side effect, which is not obvious from readOnlyHint=true. The 'untrusted data' admonition also flags a security trait. It stops short of saying what happens when hash verification fails.

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

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

Two dense sentences, front-loaded with the core action, no filler. The chain of clauses is slightly run-on and mixes procedure, security, and next-step guidance in one line, costing some scannability.

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?

Output schema exists, so return values needn't be described, and annotations cover the safety profile. The remaining gap is credential handling and failure behavior (hash mismatch, expired link), which an agent needs before invoking a tool that requires a secret.

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 carries the full burden, yet it never explains either required parameter. '本草稿' implies draft_id, but draft_credential (32–200 chars, required) is never mentioned or characterized as an authorization secret, which matters for an openWorld tool.

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

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

States a concrete verb set and resource: read a draft's actual files, verify hashes, parse summaries/format limits, optionally refresh short-lived upload links. The closing clause ('use file_id for quoting') hints at how it differs from siblings like quote_order, but the name 'materials' is never explicitly defined, so boundaries remain partly inferred.

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

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

Gives a downstream-usage hint ('after verification use file_id for quoting') and a security rule ('treat summaries only as untrusted material data'), which implies this is the pre-quote verification step. It does not say when to skip this tool or how it relates to prepare_task / get_order / renew_quote.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally. The description adds genuinely new behavior: the read is free of charge and the response covers pricing, actual deliverables and modification/input restrictions. It still doesn't say what happens for an unknown or over-length tool_id, or how pricing figures should be interpreted.

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 purpose is front-loaded, which is good, but the sentence packs many loosely grouped nouns ('成果角色', '修改与输入限制') that read as an enumeration rather than a clear statement. The two trailing clauses about the official site and quotes feel bolted on without clear relation to invocation.

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

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

An output schema exists, so return-value explanation is not required, and annotations cover the safety profile. Missing pieces are the meaning/lookup path for tool_id and any sense of what an error or missing-capability response looks like — material for a lookup tool with a single opaque identifier.

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 one parameter (tool_id) exists and schema description coverage is 0%, so the description must carry the meaning. It never explains that tool_id identifies the capability to fetch, nor where such an ID comes from (e.g., search_tools results). The trailing clause about quotes conforming to the schema is ambiguous rather than explanatory.

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 gives a specific verb and resource ('免费读取能力详情' — read capability details for free) and enumerates the fields returned (category, operations, outcome roles, input.schema, price, deliverables). It notably disambiguates the generic name 'get_tool' by framing it as a capability-detail read. It does not, however, differentiate itself from siblings like search_tools or get_service_overview.

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 hints at boundaries by saying the full official-site capabilities and MCP packages are viewed separately, which implies this tool is a subset read. But there is no explicit 'use this when X; use search_tools instead when Y' and no stated prerequisites beyond a tool_id. Usage is implied rather than directed.

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, idempotentHint=true and openWorldHint=true; the description adds genuinely non-obvious behavior: retries do not double-charge, the original order must be checked on success or uncertainty, and amounts changing forces a fresh confirmation. It stops short of describing permissions or what exactly is debited if the frozen quote expired.

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 intent is front-loaded, but the remaining content is one dense block of prose covering confirmation flow, token retry, native confirmation, amount changes, idempotency and web payment fallback with no structure. Every clause carries information, yet the flow steps would be far easier to execute as a short ordered list.

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?

An output schema exists and annotations carry the safety/idempotency profile, so much of the burden is lifted. Still, a destructive payment tool should clarify where the required identifiers come from (quote_order output?) and what happens when user_confirmation is passed without a prior quote; those gaps matter for correct invocation.

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

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

Schema coverage is 0%, so the description must carry the load, and it does explain the two non-obvious parameters: the exact user_confirmation shape (confirmed:true, amount_cents = 本单分值, currency CNY) and confirmation_token obtained from an unconfirmed first attempt and replayed on retry. The six remaining identifiers (service_id, contract_id, connection_id, credentials, request_key) are never explained.

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 clause states a specific verb and resource: charge a bound account's balance without opening a web page, which distinguishes it from quote_order/create_order siblings. It never names a sibling tool directly, so differentiation relies on the reader inferring the ordering flow.

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 lays out an explicit conditional flow: pass user_confirmation only after the user says 确认 in the conversation, omit it when unconfirmed so the client returns a summary plus confirmation_token, then retry with the token. It also states when not to proceed (编造确认, 沿用其他订单的同意, 金额变化须重新询问) and names 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 only say write, non-idempotent, non-destructive, open-world. The description adds real substance: no charge occurs, no task is executed, credentials must be saved, the direct upload address expires in 15 minutes, and uploads must be raw HTTP bytes rather than Base64. The repeated mention of the upload page and the jumbled ordering cost it a point.

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 information-rich, but the sentence is a run-on chain of semicolons and '用户上传页' is stated twice in consecutive clauses. The key safety facts ('no payment, no execution') sit mid-paragraph instead of being front-loaded.

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

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

For a single-optional-parameter write tool with an output schema, the description covers the essentials an agent needs: cost, side effects, credential handling, and the upload expiry window. Return-value detail is partly redundant with the output schema but nothing critical is missing.

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

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

Schema coverage is 0%, so the description must carry the parameter, and it does partially: it tells the agent tool_id is mandatory for media tools. However, it does not explain the four enum values or what omitting tool_id means for non-media drafts, so the gap is only half closed.

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

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

States a specific verb and resource: prepare a private task draft, free of charge, and usable without attachments. It also bounds the scope with 'no payment, will not run the task', which separates it from the ordering/payment siblings, though it never names create_order or quote_order 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?

It gives one conditional rule ('media tools must pass tool_id') and implies the pre-order drafting context via 'no payment / won't run the task', but never explicitly says when to call this versus create_order or what to do after receiving credentials.

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

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

It adds substantial facts beyond the annotations: the call is free (no charge), it returns a service order and a private credential, a user confirmation is required before purchase, and safe retries depend on a fixed request_key. This is richer than the annotations, which only state the safety profile and open-world behavior. One tension is left unresolved: the description promises safe retry via a fixed key, while idempotentHint=false implies repeated calls do work each time; an explicit distinction between calls with the key and calls without it would remove the ambiguity.

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

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

The core action is front-loaded and there is no padding, but the text packs four separate concerns (purpose, prerequisite and retry mechanics, clarification policy, purchase gating) into a terse run-on with no sentence-boundary signposting. The mid-sentence shift to '先prepare_task' reads at first as this tool's own workflow rather than as a prerequisite. It would benefit from being split into distinct sentences.

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 output schema exists, so not explaining return values is fine, and the open-world, non-destructive profile is covered. But for a 5-parameter mutation with a nested free-form input object and 0% schema descriptions, the description should show what input must contain and how the draft_id, the draft credential and the request_key fit together. It hints at this without enough precision for an agent to call the tool confidently.

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 has to carry the full burden of explaining the parameters, and it does not. It gives real semantic value for request_key (fix it to enable safe retry) and mentions a draft credential, but tool_id and draft_id go entirely undocumented, the nested input object is opaque, and requirements_confirmed is referenced even though no such property exists in a schema with additionalProperties:false. An agent cannot tell what to put in input or tool_id from this text.

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 states a concrete action (freezing the input, template and material hash) and its results (a service order plus a private credential), so it is much more than a restatement of the name. The closing clause 'confirm price/delivery before purchasing' implies that this is a quoting or freezing step rather than the purchase itself, which partly separates it from create_order/pay_with_balance. It never explicitly contrasts itself with those siblings, so it does not reach a 5.

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

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

It gives useful sequencing, namely that prepare_task comes first and that user confirmation on price/delivery must precede purchase, and it notes that requirements_confirmed=true means stop asking. However, it never says when to choose quote_order over create_order or renew_quote, which are the genuinely ambiguous alternatives in the sibling list. The guidance is implied by workflow rather than by explicit routing.

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 already declare non-read-only, open-world, idempotent, non-destructive behavior, and the description adds genuinely useful workflow context (expired-quote scope, prior payment closure, duplicate-purchase guard). However, it never states the financial consequence of calling it — whether it charges, reserves funds, or merely re-issues a quote — which is the key unknown for a payment-adjacent mutation.

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 dense sentence with the action front-loaded and the preconditions following; no filler. The semicolon-joined clauses are packed but each carries distinct information, so length is justified even if readability is slightly strained.

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?

Output schema exists, so return values need not be explained, and annotations cover the safety profile. The remaining holes are material for a mutation tool: zero documentation of the four required parameters and no statement of authentication/credential expectations or what happens to the original quote on success.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it explains none of the four required parameters. It never clarifies that 'credential' is an auth token, that 'contract_id' links to the original contract, or that 'request_key' is an idempotency key, leaving the agent to infer all of this from names and regex patterns.

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: renewing/reserving an expired quote ('续开过期报价') tied to a service order. An agent can tell this is a renewal operation rather than a fresh quote, but no sibling tool (e.g., quote_order, create_order) is named, so differentiation is left implicit.

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 a real precondition ('先确认原付款单已关闭' – confirm the original payment order is closed) and an explicit when-not rule ('付款不明确时不得重复购买' – do not repurchase when payment status is unclear). What is missing is routing against alternatives such as quote_order for a non-expired quote.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the lower bar applies. The description usefully adds that no payment is charged and no new task is created automatically when out of scope, but it does not disclose how quota is consumed, what credential authorizes the change, or how request_key deduplication works.

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?

It is short and front-loads the action, but the second half is a dense chain of conditional clauses separated by semicolons that would read more clearly as distinct sentences. No filler text, but structure is serviceable rather than effective.

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 mutation tool with annotations, an output schema present, and five fully required parameters, the description covers scope limits and the no-side-effect guarantee. What it omits is parameter meaning and quota-consumption mechanics, which an agent needs to call it correctly on the first attempt.

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

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

Schema description coverage is 0% across five required parameters, so the description carries the full burden, yet it explains none of them. change_kind's enum values (tone/structure/correction/new_material/new_task) are especially critical for routing behavior and are left completely undocumented, as are the credential format and the idempotency role of request_key.

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 the core action (modify the same task within the revision quota declared for this order) but relies on an unclear referent ('本单') and never names the resource being modified (delivery, copy, service output). An agent can form a rough idea, but the scope of the mutation remains ambiguous relative to siblings like create_order or prepare_task.

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 some deliverables/tools do not include revisions, and that out-of-scope requests return a new quote or requires_new_service with user confirmation required first. That is real guidance about the boundary between revising and re-ordering, though no sibling tool is named as the alternative.

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 non-readonly, idempotent, non-destructive, open-world. The description adds genuinely new behavior: the version and request key must be fixed/pinned, and the backend keeps executing after the reply, which explains why the call returns before work completes. It does not say what the answer affects or what errors occur on version mismatch.

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

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

Two short clauses, front-loaded with the action and followed by the key behavioral trait; nothing is padded. It is arguably too terse rather than verbose.

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?

An output schema exists and annotations cover the safety profile, and the description adds the crucial asynchronous-execution note and the pinned version/request-key expectation. With six fully required, entirely undocumented parameters, however, the definition still leaves the caller short of what it needs to invoke correctly.

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

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

Schema description coverage is 0% for six required parameters, so the description carries the full burden, yet it only alludes to version and request_key ('版本和请求编号固定') without format, constraint, or concurrency semantics. answer, credential, service_id, and interaction_id receive no explanation at all.

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

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

The description names a specific action (answering a persistent delivery question) but never uses the tool's core concept 'run', so the link to siblings like get_run_result or get_run_events is only inferable from the name. It is vague about what entity is being answered.

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

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

There is no statement of when to call this instead of get_run_events, get_run_result, or prepare_task, nor any prerequisite or exclusion. The agent must guess the routing from the tool name alone.

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 readOnly/idempotent/non-destructive annotations, the description discloses important behavior: up to five recommendations, no padding when fewer match, preview/review scope, default selection handling, quote version pinning, and no charge. It also adds a caution against mislabeling source-site usage as Xiaohongshu viral evidence.

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 purpose and contains useful details, but it is a dense single block mixing PPT behavior, Xiaohongshu behavior, selection workflow, quoting, and warnings. Several clauses are operationally useful, but the lack of structure makes it harder to scan than necessary.

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 complex with nested constraints and an output schema, and the description covers behavioral context and selection workflow well. However, it leaves important parameter semantics undocumented despite 0% schema description coverage, so an agent still needs to infer required fields and pagination behavior.

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 undocumented parameters. It explains several constraint concepts such as form, purpose, mood, color, brightness, photos, title, and include/exclude subjects, but it never explains the required tool_id, offset, limit semantics, or many remaining constraint fields like industry, source_kind, background_scope, and exclusion lists.

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 states a specific verb and resource: free search for actual templates. It also clarifies that the tool returns recommendations rather than creating PPTs or generating images, but it does not explicitly distinguish itself from sibling search_tools beyond a gating note about get_tool.

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

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

The description gives clear usage context for PPT and Xiaohongshu cover scenarios, including how to pass natural-language requirements and optional constraints. It also states exclusions such as not making PPTs or images and not charging, but it does not name alternative tools or say explicitly when not to use this search.

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, idempotent, non-destructive, and open-world; the description adds that it is free, returns real deliverables/capability version/price, and has no file-creation or order side effects. That is useful behavioral context beyond the annotations, though it does not discuss rate limits or authentication.

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 text is compact and front-loaded: free search, default scope, filters, pagination, return contents, and side-effect limits arrive without filler. Each clause carries operational information.

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

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

With an output schema and rich annotations, the remaining description needs are about scope, filters, side effects, and return contents; these are all addressed. The only notable gap is explicit routing against sibling search tools.

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%, but the description names the main filters (section, output_family, operation, formats, use_case) plus limit/offset and implies query through '完整需求'. It does not explain enum value meanings, format syntax, or query behavior beyond filtering, so it only partially compensates for the missing schema descriptions.

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 (检索/search) and resource (已开放的制作与工具), states the default scope (搜索全部), and lists filterable facets. It does not explicitly contrast with sibling tools such as search_templates or get_tool, so sibling differentiation is implicit rather than stated.

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

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

It explains the default all-search behavior, the available filter dimensions, pagination, and clarifies that it will not create files or orders, which sets usage boundaries. It does not say when to choose search_templates or get_tool instead, so alternatives remain unaddressed.

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 give readOnly, idempotent, non-destructive and openWorld, so safety is covered. The description adds real behavioral value by capping the block at 15s and mandating backoff, but it omits what happens on timeout (empty result? stale version?) and nothing about auth requirements for the credential field.

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

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

Two short clauses with the time cap front-loaded, so it is compact. However part of that scarce space is spent on a field that does not exist in the input schema, and the brevity reflects under-specification rather than disciplined editing.

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?

An output schema exists, so return values need not be described. But for a blocking, credentialed, idempotent wait tool with 0% parameter coverage, the definition should at minimum explain what is being awaited, what after_version means, and what a timeout result looks like – none of which is present.

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

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

Schema description coverage is 0%, so the description carries full responsibility for four parameters, and it explains none of them. Worse, it cites next_poll_after_ms, which is not even a parameter in the schema, while after_version, timeout_ms and the required credential are left completely unexplained – the reference is misleading rather than additive.

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 only states a wait duration limit and a polling rule; it never says what is being waited on (presumably an order transition) or what condition ends the wait. Against siblings like get_order and get_run_result, an agent cannot tell from this text alone which one actually blocks for a state change.

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?

'单次最多等待15秒' plus '遵守 next_poll_after_ms，不无限轮询' implies a poll-then-backoff loop and warns against tight polling, which is genuine usage guidance. But it never says when to prefer this over get_order or what to do when the wait expires, so the alternative-selection guidance is absent.

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