Code Refactor

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

With no annotations provided, the description carries the full behavioral burden. It usefully discloses the billing model: pay-per-use, charge confirmed only on business success, and automatic full refund on content violation, model timeout, or generation failure. It does not mention authentication, rate limits, or what the output looks like, so it is strong but not complete.

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

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

The description is two compact sentences with no wasted words. The core purpose is front-loaded, followed immediately by the critical billing and refund terms.

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 code-explanation tool with a rich schema but no output schema, the description covers the core function, reader-level adaptation, and important billing/refund behavior. It omits some details, such as output structure and length limits already present in the schema, but is largely complete for correct invocation.

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

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

Schema description coverage is 100%, so all parameters are already documented in the schema. The description references reader level (zero-basis to expert), which maps to the level parameter, but adds no syntax, constraints, or meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states a specific verb and resource: break down (拆解) code logic, key points, and pitfalls according to reader level. It is clear what the tool does, but it does not explicitly distinguish itself from sibling tools such as review or errfix, which could also involve analyzing code.

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?

Usage is only implied: the tool is for explaining code at a chosen reader level. There is no explicit guidance on when to choose this over review, errfix, or codetrans, and no stated exclusions or prerequisites.

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，因此说明文字需要承担全部披露义务。它确实提供了结构化字段没有的重要计费语义：按次计费，仅在业务成功时扣费，内容违规、模型超时或生成失败会自动全额退款。但它没有说明如何使用返回的代码、延迟预期或长度限制。

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?

两句话，没有浪费：先给出目的，再说明计费和退款规则。对计费工具来说，放在前面的内容是正确的。

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?

参数已被 schema 完全描述，计费风险也已覆盖。但该工具没有输出 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?

Schema 描述覆盖率为 100%，四个参数都在 schema 中有完整文档，包括 prompt 的 4000 字符限制以及 requestId 的幂等用途。说明文字没有为这些参数增加任何信息，因此基线 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?

明确写出动词+资源：根据需求描述生成「可运行的示例代码」。这足以区别于 docgen、copywriter、translate 等工具。不过，它没有说明与 script 和 sqlgen 等相近同类工具的区别，而这两个工具同样会生成代码。

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?

用途只能从动词推断（把自然语言需求描述变成代码）。没有说明何时改用 script/sqlgen/testgen，也没有前提条件或排除项。至少所需输入（需求描述）是明确的，但缺少选择工具时的规则。

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

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

With no annotations at all the description carries the full burden, and it does disclose genuinely non-obvious behavior: billing occurs per call, is only confirmed on business success, and is auto-refunded on content violation, model timeout, or generation failure. That is real value beyond the schema. Still missing are latency expectations and what the response payload looks like structurally.

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 what is produced and then the billing/refund terms. No filler; the only shortfall is that the refund clause reads as marketing-adjacent rather than operative detail.

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

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

No output schema exists, so the description must describe returns — and it does name the three deliverables (equivalent implementation, dependency replacements, behavioral differences). Combined with the full schema coverage this is close to complete; a note on output format or expected turnaround would close the 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 100% with four parameters, so the baseline is 3. The description adds nothing about `from` auto-detection, the `to` enum, or the `requestId` idempotency key — all of that meaning already lives in the schema.

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

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

States a concrete verb+resource: converts code from language A to language B, and additionally returns dependency replacements and a behavioral-difference list. That output shape distinguishes it from siblings like codegen or translate (natural language), though no sibling is named 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?

Usage is only implied by the output description — an agent can infer this is for porting existing code to another language. There is no explicit when-to-use/when-not guidance, no pointer to alternatives such as codegen for new code or translate for prose, and no mention of input constraints (the 20000-character cap lives only in the schema).

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

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

With no annotations, the description carries the full burden. It discloses important billing behavior: per-use charge, confirmation only on success, and automatic full refund on content violation, model timeout, or generation failure. It does not mention authentication, rate limits, or output format details, but the billing and failure semantics are a strong addition.

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 sentences with no wasted words. The primary function is front-loaded, followed by critical billing context. Every sentence earns its place.

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

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

For a tool with a clear schema and no output schema, the description covers purpose, output expectations, and billing behavior. It could be slightly more complete by explaining what 'risk hints' entail or the expected structure of the bilingual message, but it is sufficient for an agent to call 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 100%, so the schema already documents all parameters including the style enum and idempotency key. The description adds no parameter-specific information beyond what is in the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb (generate) and resource (Conventional Commits commit message) with clear input (paste diff) and output (bilingual message + risk hints). This distinguishes it from sibling tools like translate or codegen, which don't focus on Git commit messages.

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 usage by specifying 'paste diff,' but does not explicitly state when to use this tool versus alternatives (e.g., translate or codegen) or when not to use it. No exclusions or alternative routing are provided.

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

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

With no annotations, the description carries the full burden and does disclose a meaningful behavioral trait: per-call billing that only charges on business success, with automatic full refund on content violation, model timeout, or generation failure. It does not cover permissions, latency, or what an error response looks like, leaving some gaps.

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 waste: the review capability is front-loaded and the billing/refund policy follows. Every clause 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?

With no output schema, the description does sketch the return content (risk levels plus suggested replacement wording), and the billing semantics are covered. Minor gaps remain around output structure and the interaction between retries and the idempotency key.

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

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

Schema description coverage is 100%, so 'text', 'party' (with its enum of stances), and 'requestId' idempotency are already fully documented in the schema. The description adds nothing about parameter meaning, so the baseline of 3 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 states a specific verb+resource: it marks high/medium-risk and missing clauses and supplies replacement wording, which is a concrete contract-review action. It is clear on its own, but it never distinguishes itself from the sibling 'review' tool, which plausibly overlaps.

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 guidance on when to choose this tool over 'review', 'docgen', or other siblings, and no preconditions or exclusions are given. The only usage-adjacent content is the billing rule, which governs cost rather than tool 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?

With no annotations, the description carries the burden and does well: it discloses the billing model, that charges only confirm on business success, and that violations, timeouts, or generation failures auto-refund in full. It omits return shape and latency expectations, keeping it 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?

Two sentences, no filler, with the output promise front-loaded and the commercial terms immediately after. Every clause carries information an agent or caller needs.

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

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

For a 4-parameter generation tool with no output schema, it covers the key unknowns: volume of output (3 versions) and billing/refund behavior. It stops short of describing the format of each version (title, body, tags) or length.

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% with enums for tone and platform, so the schema already documents every field. The description only adds the list of target platforms, which partially overlaps the platform enum, and says nothing about brief length or requestId idempotency beyond what the schema states.

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?

Names a specific output (multi-platform marketing copy for 小红书/抖音/公众号) and a concrete quantity (3 versions per call), so an agent knows exactly what it produces. It does not explicitly differentiate from siblings like translate or script, but the resource is distinct enough to be 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?

Implies usage through the platform list and the 'per call' framing, but never states when to prefer this tool or when not to. The billing/refund sentence is conditional context, not selection 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?

With no annotations at all, the description carries the full disclosure burden and does deliver the most consequential behavior: per-call billing, charge only on business success, and full auto-refund on content violation, model timeout or generation failure. It stops short of covering output format, typical latency, or any permission/auth requirements, which keeps it from 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?

Two sentences: capability first, billing guarantee second. Every clause earns its place and the pricing/refund fact — the highest-risk unknown for an agent — is stated up front rather than buried.

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?

There is no output schema, so the description should say what comes back (markdown text, file, URL) and roughly how long generation takes; it only alludes to timeout. Cost and refund risk are well covered, but for a paid generative tool the return contract is a real 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 coverage is 100% and every parameter including the docType and audience enums is fully documented in the schema, so the baseline of 3 applies. The description adds no syntax, length, or idempotency detail beyond what the schema already states (including the requestId dedup note).

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?

Names a specific verb (一键生成) and resource (README / API 文档 / 变更日志 / 技术方案), and enumerates concrete output artifacts that map to the docType enum. It doesn't explicitly contrast itself with siblings like codegen or copywriter, but the doc-type list makes the domain clear enough to separate it.

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?

Usage is only implied through the enumeration of documentation kinds — an agent can infer 'use this when you need README/API/changelog/design docs', but there is no explicit when-not guidance and no reference to the sibling generators (codegen, testgen, copywriter). The billing clause describes consequences, not selection criteria.

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

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

With no annotations, the description carries the full burden, and it does disclose a non-obvious behavioral trait: per-call billing that only charges on business success and auto-refunds on content violation, model timeout, or generation failure. It also enumerates the deliverable (root cause, patch, verification steps), which effectively stands in for a missing output schema. It does not cover latency, retry semantics beyond the schema's requestId, or limits on output size.

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 zero filler: the first is the input→output contract, the second is the billing/refund policy. The core capability is front-loaded before the commercial detail.

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

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

For a 4-parameter tool with one required field, full schema coverage, and no output schema, the description covers both what the tool produces and how billing behaves. Missing only minor operational details such as expected turnaround or output size limits, which are unlikely to change how an agent invokes it.

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

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

Schema description coverage is 100%, so all four parameters including the requestId idempotency key and the 6000-character error limit are already documented. The description only restates that error and code are the core inputs and adds nothing about format or syntax. Baseline 3 is appropriate when the schema does the heavy lifting.

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 concrete input→output contract: error stack plus code in, root-cause localization, minimal fix patch, and verification steps out. That is far more specific than a name restatement and clearly separates it from sibling generators like codegen or codeexplain. It stops short of naming a sibling, so 4 rather than 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?

Usage is only implied by the input contract — an agent infers it should call this when it has an error stack to diagnose. There is no explicit 'use this instead of codeexplain when…', no preconditions, and no exclusions. The billing sentence adds cost awareness but not 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?

With no annotations, the description carries the full burden; it does disclose that the lookup is free of charge (不收费) and that results include failure reasons, which signals a read-only diagnostic call. It does not state what happens on a miss (empty vs error) or whether results are cached/paginated.

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 sentences, zero filler, with the query key and returned fields front-loaded and the cost note trailing. Every clause 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 one-parameter read tool with no output schema, enumerating the return fields and the no-charge property covers most of what an agent needs. Missing only explicit routing against list_orders and not-found 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 coverage is 100% and the schema itself gives the format hint (SG20261018…). The description adds only a restatement of "by order number", which is the baseline expectation rather than added meaning.

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 (一笔调用/订单) and enumerates the returned fields (状态、金额、耗时、失败原因), so the agent knows exactly what it gets. The singular "一笔" implicitly separates it from list_orders, but the sibling is never named.

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?

Usage is only implied: query by order number for a single order. It never says when to prefer this over list_orders or what to do when the order number is unknown, so the agent must infer the 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?

No annotations are provided, so the description carries the full behavioral burden. It adds useful context that the service is free (不收费) and that results are recent, but it does not explicitly state read-only behavior, side effects, authentication requirements, rate limits, or pagination behavior beyond the limit 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?

The description is a single compact sentence plus a short no-charge note. It is front-loaded with the main action and scope, and every part contributes useful information.

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

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

For a simple read-only listing tool, the description covers purpose, filtering, and cost context. However, with no output schema and no annotations, it could say more about return contents or ordering, though the core call parameters are well covered by 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?

Schema description coverage is 100%, so the schema already fully documents limit, status, and platform. The description mentions status and platform filtering but adds no syntax or semantics beyond what the schema provides; this meets the baseline 3 when the schema does the heavy lifting.

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: it lists recent invocation orders, with status/platform filtering. It is clear what the tool does, but it does not explicitly distinguish this listing tool from the sibling get_order 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?

It gives a clear use context: reconciliation (对账), and it mentions the available filtering approach. It does not explicitly say when to use get_order instead or when not to use this tool, but the use case is clear enough for an agent to act on.

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

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

With no annotations, the description carries the behavioral burden and discloses important traits: per-call billing, charge confirmation only on business success, automatic full refund on content violations, model timeouts, or generation failures, and a safety property about catastrophic backtracking. It does not cover rate limits or authentication, but the billing and failure behavior are unusually well specified.

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

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

The description is two tight clauses with no waste: the core capability comes first, followed by the billing/refund policy. It is appropriately front-loaded and sized for the tool.

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?

There is no output schema, but the description names the main return components: the regex, segment-by-segment explanation, and matching examples. Combined with the fully documented parameters and billing policy, this is nearly complete, though it does not detail exact response shape or limitations.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description only implicitly references the natural-language requirement and sample text, adding no additional parameter semantics beyond what the schema provides.

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

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

The description states a specific transformation: natural language to precise regex, plus segment explanations and match examples, with protection against catastrophic backtracking. This is clearly a regex-generation tool, though it does not explicitly differentiate itself from siblings such as codegen or script.

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?

Usage is implied by the natural-language-to-regex framing, but the description gives no explicit when-to-use, when-not-to-use, or alternative-tool guidance. An agent must infer that it should choose this over codegen or script when the task is specifically regex generation.

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

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

With no annotations provided, the description carries the full burden and does real work: it discloses per-call billing, that charges are confirmed only on business success, and that content-policy violations, model timeouts, or generation failures trigger an automatic full refund. It also states the anti-fabrication guarantee. What it omits is anything about the returned artifact or processing time, keeping it 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?

Two compact sentences: the first front-loads capability and the core integrity constraint, the second front-loads the billing rule. Nothing is wasted and no sentence repeats structured data.

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

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

For a 3-mode generation tool with no output schema and no annotations, the description covers the commercial and integrity dimensions well but says nothing about what the agent receives back (diagnostic report vs. rewritten resume text) or how modes differ in output. An agent can call it correctly but not predict the response shape.

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

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

Schema description coverage is 100%, so all four parameters (jd, goal, resume, requestId) are already documented, including the enum meanings and idempotency key. The description adds no parameter-level detail beyond the integrity constraint, so the baseline 3 for fully documented schemas 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 concrete verb set (diagnose match against a JD, rewrite in STAR format) and a resource (resume), with a notable constraint (never fabricate experience). It's clear what the tool does, though it emphasizes match/rewrite while the default goal 'optimize' is only visible in the schema, and it doesn't differentiate itself from unrelated siblings (all content-generation tools, so differentiation is less critical).

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 implies usage context (you have a resume and optionally a JD) and discloses the billing/refund trigger conditions, which is useful when deciding whether to call. However, it never says when to pick this over a sibling tool or when not to call (e.g., missing JD for match/rewrite is only stated in the schema), so guidance is implied rather than explicit.

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

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

With no annotations, the description carries the full behavioral burden and does disclose the commercially important trait: pay-per-call with charge confirmed only on business success, and automatic full refund on content violation, model timeout, or generation failure. That is real, non-obvious context. It stops short of covering authorization/prerequisites or what happens to submitted code, which is why it is not 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?

Two sentences, purpose front-loaded, zero filler. The billing sentence is dense but earns its place because it is the tool's only non-schema disclosure.

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?

Billing risk is well covered, but for a tool with no output schema the description never characterizes the response — what 'graded' means (levels? counts? line references?) is undefined. It also omits practical limits and the idempotency expectation, leaving meaningful gaps for an agent planning a call.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds nothing about code, focus, language, or the requestId idempotency key, all of which are already fully documented in the schema.

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

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

States a specific verb+resource+output shape: review code and return graded fix suggestions. That clearly separates it from codegen/testgen/docgen siblings, though it never names an alternative explicitly. It falls short of 5 only because the 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?

The second sentence is about billing mechanics, not about when to reach for this tool versus codegen or testgen. There is no 'use this when…' or 'do not use for…' guidance at all; an agent must infer usage purely from the one-line purpose.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses billing behavior: charges are confirmed only on business success, and content violations, model timeouts, or generation failures trigger an automatic full refund. It does not cover auth, rate limits, or whether generated content is stored, 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?

The description is two tight sentences: the deliverable list is front-loaded, followed immediately by the billing and refund terms. Every sentence earns its place with no repetition or 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?

With no output schema, the description usefully enumerates the returned artifacts and explains the billing/refund safeguards. It still leaves a minor gap around whether assets are returned inline or stored, so it is strong but not fully complete.

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

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

Schema description coverage is 100%, so the schema already documents topic, duration, platform, and requestId thoroughly. The description adds no parameter-level semantics beyond the deliverable list, making the baseline 3 appropriate.

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

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

The description names a specific deliverable set: three opening-hook versions, a storyboard table, and spoken copy that is ready to shoot. It clearly identifies the generated assets, but it does not distinguish this tool from siblings such as copywriter or codegen.

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 '可直接拍摄' implies the tool is for producing shoot-ready short-video scripts, but there is no explicit when-to-use guidance, no exclusions, and no comparison to sibling tools such as copywriter.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses that the call is free ("不收费") and lists the returned data, but does not state whether it is strictly read-only, whether it requires authentication, or any other operational constraint.

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 short sentence front-loads the return contents and adds the free-of-charge note without any filler. Every clause contributes 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 no output schema and no parameters, the description must explain what comes back, and it does so by enumerating the four returned items. It is nearly complete for this simple informational tool, with only minor gaps around response format.

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, which is the baseline-4 case. There is nothing for the description to clarify beyond confirming the call is parameterless by implication.

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 (返回/returns) and enumerates exactly what is returned: availability, per-use price, supported programming languages, and disclaimer. It is clearly distinct from all sibling tools, which are generation or order-management tools, though it never names 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?

Usage is implied by the returned fields — an agent would call it to check whether a skill is listed and what it costs. There is no explicit when-to-use/when-not-to-use guidance or reference to any sibling tool, leaving the routing inference to the agent.

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

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

With no annotations, the description carries the full burden and does add real behavioral value: automatic interception of destructive statements and a per-call billing model where charges confirm only on success and auto-refund on violation/timeout/failure. It still leaves ambiguous whether the SQL is merely generated or actually executed, and says nothing about latency or response shape.

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, front-loaded with the core capability before the billing caveat; no filler. The billing sentence is slightly long but every clause (success-only charge, auto-refund triggers) is decision-relevant.

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

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

For a 4-param, no-annotation, no-output-schema tool, the definition covers purpose, safety and cost but omits what the caller receives (SQL text only? explanation? result rows?) and whether execution occurs. That return-value gap matters precisely because there is no output schema to fill it.

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

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

Schema description coverage is 100%, so all four parameters (including the dialect enum and requestId idempotency key) are already documented in the schema. The description only echoes '按表结构' for the schema param and adds no syntax or format detail beyond that, so baseline 3 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 states a specific verb and resource — generating/optimizing SQL from table schemas — plus an extra behavior (destructive-statement interception). It doesn't name the closest siblings (codegen, script, testgen), but 'SQL' is a sharp enough resource to distinguish it in practice.

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 guidance on when to pick this over codegen or script, nor any exclusions or prerequisites. The only conditional content is about billing/refund outcomes, which is not usage 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?

With no annotations, the description carries the full behavioral burden. It discloses the pay-per-use billing model and refund conditions, and mentions automatic mocking of external dependencies. However, it omits other behavioral details such as output format, data handling, or runtime expectations, leaving significant gaps for a creation 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?

Two sentences, each earning its place: the first states the core function and key feature (mocking), and the second explains the billing model. It is front-loaded and free of waste.

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 generation tool with no output schema and no annotations, the description covers purpose and billing but is thin on other behavioral aspects like return format, performance expectations, or security/privacy. It is minimally adequate but not fully informative.

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

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

Schema description coverage is 100%, so all four parameters are fully documented in the schema. The description adds no parameter-level semantics beyond what the schema provides; its billing note is behavioral, not parameter-specific. Baseline 3 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?

States a specific verb and resource: '生成可运行的单元测试' for '核心代码', plus the automatic mocking of external dependencies. This distinguishes it from a general code generator like codegen, though it does not explicitly name sibling alternatives.

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 intended use is implied by the verb and resource: generating tests for core code. However, there is no explicit guidance on when to use this vs. codegen or other generation tools, nor any exclusions or prerequisites.

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

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

No annotations exist, so the description carries the full burden, and it does disclose meaningful behavior: per-call billing with charge confirmed only on success, and automatic full refund on policy violation, model timeout, or generation failure. It omits rate limits, latency expectations, and what the output actually contains.

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, front-loaded with capability followed by billing terms, with no filler. The tier enumeration is the only part that does not earn its place, given it contradicts the 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?

Billing and failure handling are well covered, but with no output schema the description should indicate what a successful response looks like beyond 'three tiers of output'. The style-tier mismatch between the description and the enum also leaves the agent with an ambiguous mental model of the output modes.

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

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

Schema coverage is 100%, so all four parameters including the style enum are already documented, which sets the baseline at 3. The description's '直译+润色+术语表三档' framing loosely maps to the style options but actually conflicts in count and content with the schema's four values (literal/polished/seo/academic), adding confusion rather than clarity.

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 (translate) plus scope (10 languages, three output tiers), which is clear enough for an agent. It does not differentiate from siblings such as copywriter or docgen, which could also produce prose in a target language.

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

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

No explanation of when to select this tool over copywriter or docgen, and no exclusions or prerequisites. The only usage-adjacent content is the billing model, which informs cost rather than tool selection.

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