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

No annotations exist, so the description carries the full burden and does so well: it discloses that the action is undoable, consumes no quota, creates no new draft, uploads a preview video for review when one exists, and auto-creates dependent objects. It also documents the validation failure path precisely (AI_COMBINE_APPLY_FAILED plus the editor's original message, with a concrete example) and the return payload (added_objects with object_path, draft_id nullable).

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 core action and its user-facing equivalent, then layered with prerequisites, side effects, failure modes, and return values. Sentences are dense but each carries distinct information. Slight cost: the parenthetical object-creation clause and the error example make it long, though both are load-bearing given no output 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?

For a mutation tool with zero annotations and no output schema, the description supplies everything an agent needs: what it mutates, that it is reversible, that it costs no quota, the auto-created objects, the error code and message shape, and the exact return fields including nullable draft_id. It even names the mandatory follow-up 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 both optional selectors (instance_id / project_path) and the required graph_id are already documented in the schema itself, including the '二选一' and 'only one window open' rules. The description reinforces graph_id as 'the workflow' but adds no syntax, format, or edge-case detail beyond the schema. 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?

Names a specific verb+resource ('把一张 AI 工作流放进场景' = apply an AI workflow into the scene) and pins down the exact user-facing equivalent ('AI 效果窗口的「应用」'). It also enumerates the concrete side effects — compile, upload workflow file, add AI 组合效果 object, auto-create 2D 前景/2D 摄像机 — which separates it cleanly from the sibling ai_combine_new (creation vs. application).

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 context is clear: it is the 'apply' stage that follows a workflow existing, and the description ends with the explicit next step '之后 save_project'. The graph_id schema entry also routes the agent to ai_combine_new / get_workflow_context for the required input. What is missing is an explicit when-NOT clause (e.g., don't call before the workflow node is wired), which is instead surfaced reactively as an error case.

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 whole burden and does: it states the operation is local-only, makes no network call, deducts no credits, and creates no cloud draft. It further discloses that official apply_workflow_patch saves a cloud draft on each edit and that generate_workflow costs credits, which is exactly the side-effect context an agent needs.

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 and the no-side-effect guarantees are front-loaded, followed by the workflow chain. It is dense and long for a two-parameter tool, but nearly every clause carries operational meaning (credit cost, cloud drafts, the menu_add warning), so little is wasted.

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

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

Even without an output schema, the description explains the return values (ai_graph_id plus each node's node_id) and what the caller must do with them. Combined with the downstream tool chain and cost caveats, an agent has everything needed to call it and continue correctly.

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

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

Schema coverage is 100%, so instance_id and project_path are already documented (mutually exclusive, both optional when only one project window is open). The description adds no additional guidance about those parameters, 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?

Names a specific verb+resource: creating a local 'AI 组合效果' workflow graph with exactly two unconnected nodes ('输入图' and '效果组合'). It explicitly contrasts this with the sibling menu_add ('只建空壳，不要用 menu_add') and with ai_combine_apply, so an agent can distinguish it from all nearby tools.

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

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

States the full call sequence: create here, then use official get_workflow_context / get_workflow_capabilities / apply_workflow_patch to add generation nodes and wire them, then generate_workflow to preview, then ai_combine_apply to place in the scene. It also gives an explicit exclusion ('不要用 menu_add') with the reason.

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 does so: it discloses the side effect of closing previous detection windows (with closed_previous count), that the window is closed only on a successful detail read (window_closed=true), that the window is left open on details_error or timeout, that timed-out checks keep running, and it enumerates the four possible verdicts.

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 first clause and every subsequent clause earns its place by describing a distinct return state (verdict, checks, figures, advice, details_error, timeout, closed_previous). It is a single dense run-on sentence joined by semicolons, which makes the branching logic harder to scan 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?

There is no output schema and no annotations, yet the description fully specifies the return shape (verdict, checks with figures for size and android/ios frame rate, advice or advice_unavailable, window_closed, closed_previous, details_error, timeout) and the window lifecycle in every branch. An agent has everything needed to call it and interpret results.

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 baseline is 3, but the description adds real meaning for timeout_ms beyond the schema's value bound: what happens on expiry (returns timeout, window stays open, detection continues). instance_id / project_path are left entirely to the schema, which already documents their mutual exclusivity and the single-window default.

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+resource (特效检测 / effect check) and immediately disambiguates scope: it uploads the effect package for cloud checking, explicitly 'not publishing' (不是发布). An agent can distinguish this from my_effect_reviews or submit_prepare without opening the schema.

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

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

It anchors usage to a concrete UI action ('same as clicking 特效检测 in the editor toolbar'), which tells the agent when this is the right call, and rules out publishing as an alternative intent. It does not name a sibling tool to use instead in any scenario, so it stops short of explicit alternative 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 burden and does well: it discloses the exact return payload per plugin and the important caveat that the plugin is inert in already-open windows. It never explicitly says the call is side-effect-free or cheap, but a status/self-check framing makes read-only behavior clear enough.

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?

Purpose is front-loaded, followed by returned fields, then troubleshooting triggers. The sentence about newly opened windows is a bit tacked-on but carries real behavioral information, so it 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, no annotations, and no parameters, the description must explain what comes back — and it lists the returned fields explicitly. Adding whether the output is a single object or a list per plugin would close the remaining 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 schema coverage is a non-issue and the baseline is 4. The description spends its words on the returned fields instead, which is the right use of space.

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 resource (extension self status) and enumerates exactly what it reports: official MCP connection state plus per-plugin project window data (pid, project path, official instance_id, editor interface self-check). No sibling tool in the list reports diagnostic state, so an agent can place it immediately.

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 precise trigger conditions: call it first when a tool reports a missing window, INCOMPATIBLE_EDITOR, or unavailable official tools. It also warns the plugin only takes effect in project windows opened after installation. It does not name an alternative tool or state when not to call it, so it falls short of full routing guidance.

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

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

No annotations are supplied, so the description carries the full burden, and it does disclose the return shape (object_path, enabled state, brush index and intensity) plus an important behavioral quirk about set_component not being able to change intensity. It does not state whether the call mutates anything, how large scenes are handled, or whether results are paginated, which keeps 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 with the resource and return fields front-loaded, then the alternative routing. The parenthetical about cat/dog faces and the set_component warning both earn their place, though the sentence is dense enough to need a second read.

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 or annotation coverage, but the description compensates by enumerating the returned fields and flagging the set_component limitation. Nothing critical for calling a read-only two-parameter lister is missing, though scope of the listing (whole scene vs. current instance) is only implied.

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% and both parameters (instance_id, project_path) already document their mutual exclusivity and the single-window fallback. The description adds no parameter-level meaning, so the 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?

States a specific verb plus resource: list all FaceWarpX brush components in the scene, including the cat-face/dog-face variants. It also names the exact fields returned (object_path, enabled flag, per-brush index and intensity), so an agent can distinguish it from the sibling face_warp_set_intensity without opening any schema.

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

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

Explicitly routes the intensity-changing case to the sibling face_warp_set_intensity and warns that the official set_component cannot change brush intensity. It gives clear context for reading, but offers no exclusion about when this listing is unnecessary (e.g., versus scene_tree or inspect_many for general 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?

With no annotations supplied, the description carries the full behavioral burden and does meaningful work: it discloses that only intensity changes, that existing brush data is preserved, and that the change is undoable (可撤销). Those are exactly the mutation-scope and reversibility facts an agent needs. It does not cover failure behavior, required permissions, or what a successful call returns, which keeps it below a 5.

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

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

Three compact sentences, front-loaded with the action and its constraints, followed by the path-sourcing rule and the item_index default. There is minor overlap with schema text, but nothing is wasted or out of order.

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 five-parameter mutation tool with no annotations and no output schema, the description covers purpose, mutation scope, reversibility, path sourcing, and the item_index default. The gap is the project_path/instance_id selection and any hint about the response, though the schema does document the project targeting.

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

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

Schema description coverage is 100%, so the parameters are already well documented, and the description largely restates them (0–100 intensity, object_path from face_warp_list, item_index omitted means all). It adds no meaning for instance_id or project_path, and the baseline of 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 names a specific verb and resource (modify the 塑型画笔 intensity), gives the numeric domain 0–100, and anchors it to a familiar concept (the inspector intensity slider). It also distinguishes itself from the sibling face_warp_list by naming it as the source of object_path, so an agent can tell the read tool from the write tool without opening either schema.

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

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

It clearly states the operational context: object_path should come from face_warp_list or a uniquely-locating trailing segment, and omitting item_index sets every brush item. That is enough to select and drive the tool, but there is no explicit when-not guidance or statement of what happens when the path is ambiguous or missing.

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 the key behaviors: no auth parameter is needed because the editor's logged-in account is used, and a project window must be open. It also enumerates the status vocabulary (done/in_progress/locked) and notes that the top tier pays out in rights rather than cash. Pagination and error behavior are unstated, which keeps it below 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?

Dense but mostly load-bearing: since no output schema exists, describing the return shape (level, reward, status, goal, current/target, rights) is necessary, and the worked example 「绑定「灵感」上线 0/3 个作品」 pins down progress semantics. The parenthetical level enumeration (新手特效师、潜力特效师……大师特效师) is decorative and could be trimmed.

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

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

For a read tool with no annotations and no output schema, the description covers the return structure thoroughly, names the account source, and disambiguates against tasks_list. It omits what happens when no window is open and any error or empty-state behavior, but nothing essential for a correct call is missing.

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

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

Schema description coverage is 100% and both parameters (instance_id, project_path) are already documented as mutually exclusive and omittable when exactly one window is open. The description's line 任意一个工程窗口开着即可 corroborates that but adds no new syntax or selection detail. Baseline 3 is appropriate when the schema does the work.

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

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

The description clearly states the resource: the current account's effect-artist level plus every level's cash reward, status (done/in_progress/locked), goals with current/target progress, and the rights granted at the top tier. It is not verb-first (it opens with the feature name 「成长之路」), but an agent can still tell it apart from tasks_list, which the description explicitly names as the sibling for per-task growth content.

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 concrete precondition (any project window open is sufficient; the editor's logged-in account is used) and explicitly routes the agent to tasks_list with kind=growth for the task-center items that carry reference projects and tutorials. There is no explicit when-not case, but the split between this tool and tasks_list is stated plainly.

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 usefully conveys that this is a human-in-the-loop UI tool ('让用户在里面挑选或调整') rather than one that mutates project state directly, which is meaningful context. However it says nothing about whether a project window must already be open, what happens when the window is already open, or what the call returns.

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

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

A single well-formed sentence with the resource front-loaded and no filler. Slightly more could be gained only by adding the routing information the description currently lacks.

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 simple (two optional params, no output schema, no annotations), so not much is required. Still, an agent would benefit from knowing the relationship to icon_set and whether an open project is a precondition, both of which are absent.

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% and both parameters are documented there, including the instance_id/project_path either-or rule and the case where both may be omitted. The description adds no parameter meaning beyond the schema, 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 names a specific verb (打开) and resource (编辑器的「图标制作」窗口) and enumerates the three kinds of content available inside (官方图标模板、文字模板、AI 图标). It is clear what the tool does, but it never contrasts itself with the closely related sibling icon_set, so an agent must infer which of the two it needs.

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: opening a window so the user can browse or adjust icons suggests a create/browse flow, as opposed to icon_set which presumably applies one. There is no explicit when-to-use, no when-not-to-use, and no mention of the sibling alternative, leaving the boundary to inference.

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

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

With no annotations at all, the description carries the full burden and does so well: it discloses image transformation and resize, the on-disk location of written files, the external platform upload side effect, the required female and male slots, and an error code ICON_UPLOAD_FAILED with retry guidance. It leaves out whether existing icons are overwritten and what authentication the upload requires, which are the only notable side-effect 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?

The sentence begins with the purpose and the submission requirement, which is the right order. The parenthetical clauses pile up (提交窗口只认上传过的图标, 提交窗口要这两个), repeating the 'submission needs both icons' point more than once, but nothing is truly irrelevant.

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 four-parameter mutation tool with no annotations and no output schema, the description covers side effects, error handling, accepted image sources (generate_image output or capture_preview files), and the required follow-up call. Without an output schema, it could say what the call returns, and it says nothing about overwriting existing icons.

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 explains every parameter, including the type enum and the instance_id/project_path either-or rule. The description mostly restates the default for type (both slots) rather than adding new semantics, 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 names a specific verb and resource (设置特效图标), then enumerates the concrete operations: center-crop to square, scale to 360×360 PNG, write into the project's Icon/ directory, and upload to the Douyin effects platform. That is far more specific than the name alone, and the parenthetical (提交特效必需) distinguishes it from general icon-editing siblings such as icon_open.

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 clearly says when this tool is needed (submission requires uploaded icons) and ties it to the sibling workflow: the same files the 「图标制作」 window saves, the same effect as that window's 「完成」 button, plus the follow-up step with save_project. It does not state when to prefer icon_open or when not to use this tool, so the alternatives are only implied.

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 so: it discloses the per-call cap of 8, the accepted formats, per-item partial failure semantics (only that item's reason is written), and the truncation behaviour for large/animated images with a not_returned list requiring a second call. These are non-obvious operational traits an agent could not infer elsewhere.

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?

Purpose is front-loaded and every clause carries information (sources, formats, cap, failure handling, truncation). It is somewhat run-on as a single semicolon-chained block, and the parenthetical examples could be tightened, but there is no filler.

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

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

There is no output schema, yet the description effectively documents the return shape: per-item failure reasons and a not_returned list for truncated batches. Combined with the input sourcing rules and the video/audio fallback, an agent has everything needed to call this correctly and interpret partial results.

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 single parameter's schema description already lists refs, http(s) URLs and absolute paths, so the baseline is 3. The description adds provenance the schema lacks — which sibling tools emit which reference form — plus the caveat that video/audio refs are not viewable, which meaningfully guides what to put in the array.

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?

Opens with a specific verb+resource (查看图片) and immediately distinguishes itself from the many list/detail siblings by naming exactly which of their outputs (short *_ref/*_refs references, image_url addresses, image_file paths) are valid input here. An agent can tell what this tool is for without opening the schema.

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

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

Explicitly routes the agent: list-type tools give refs, detail-type tools give addresses, and both should be passed here; it also states the negative case — video:3 / audio:5 references cannot be rendered and their original address is returned instead. Constraints (max 8, png/jpeg/gif/webp only) and the retry path for oversized images are stated up front.

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 supplied, so the description carries the full burden, and it does substantial work: it discloses output shaping ({type, data} unwrapping, long arrays truncated to length plus leading items), reference encodings for resources and objects, per-item partial failure reporting, and that save_to persists results long-term as inspect_many.json. It does not mention the cost implication of internally invoking inspect once per guid or any practical ceiling beyond the schema's maxItems of 40, which is the main behavioral gap.

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

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

The purpose and the alternative-tool routing are front-loaded, and most sentences carry operational facts. It is dense with nested parentheses, and the aside explaining how the preset list was originally derived is lower-value than the rest, slightly diluting an otherwise tight definition.

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 8 parameters, no annotations, and no output schema, the description covers filters, mode selection, output shape, per-item failure, and persistence — enough to call it correctly. It stops short of describing the envelope of the returned result (per-object keys, ordering relative to the input guids) and the performance characteristics of sequential per-object inspection.

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?

Although schema coverage is already 100%, the description adds genuinely new meaning: fields matches case-insensitively on property-name substrings with concrete examples, component_types is exemplified with ["Transform"], preset='key' is fully enumerated (transform, visibility/enabled, intensity/opacity/weight/color, str text, sizeDelta, bound resources, all script-component params) rather than left to the schema's circular '见工具说明', and guids switches to #序号 form in project_dir mode. This is above the baseline-3 expectation for a fully documented schema.

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

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

The opening clause gives a specific verb (查看), a specific resource (多个对象的组件参数), and a batch scope, then immediately contrasts with the single-object sibling 'inspect'. An agent can distinguish inspect_many from inspect without opening either schema.

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

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

It states explicitly when to use the sibling instead ('只看一个对象的完整原始数据时直接用 inspect'), explains the two execution modes (project_dir for offline/no-window reads vs instance_id/project_path for a live editor), and says preset and fields can be combined. It even admits preset is a heuristic list derived from prior makeup/warp/sticker/text work and directs the agent to fields for gaps.

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 well: it discloses that binding uses the same interface as the editor, that the change is not persisted until save_project, and that the submit window auto-populates. It does not cover error/duplicate-binding behavior or whether the project must already be open.

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 that front-load the core action, then the persistence step, then the alternative path. The parenthetical asides are slightly dense but every clause conveys usable 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 three-parameter tool with no output schema or annotations, the description covers the action, persistence requirement, downstream effect, and the alternative route. Only edge cases like existing bindings or failure modes are absent.

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 instance_id/project_path mutual exclusivity and the inspiration_id format are already documented. The description reinforces the binding role of inspiration_id but adds no format or constraint details beyond the schema.

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

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

States a specific verb and resource: binding an inspiration (by inspiration_id) to the current project. It also distinguishes itself from the sibling submit_prepare by explaining that the latter picks inspirations by name at submission time.

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

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

Explicitly gives the alternative path: if you only need to choose an inspiration during submission, pass inspiration to submit_prepare instead. It also names the required follow-up (save_project) so the agent knows the full flow.

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 usefully discloses that the write targets the current logged-in account and mirrors the UI button, which is real behavioral context. However, it is ambiguous whether the tool itself re-queries to confirm or the agent is being instructed to do so, and it says nothing about idempotency, permission requirements, or what a failed confirmation means.

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 with the action and the account scope front-loaded and no wasted wording. The trailing verification clause is slightly ambiguous rather than verbose, keeping it below a 5.

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 an annotation-free mutation with four parameters and no output schema, the description covers what changes and in whose account, which is the essential part. It still leaves the post-action verification semantics and failure behavior unclear, so an agent cannot fully predict the call outcome.

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 collect's default true/false semantics, the instance_id vs project_path either-or, and inspiration_id are already fully documented. The description adds only the high-level collect/uncollect framing, which is a baseline-3 contribution.

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 concrete verb pair (favorite / unfavorite) applied to a specific resource (an inspiration), and clarifies it writes to the currently logged-in account, the same as the favorite button on the inspiration detail page. It is clear what the tool does, but it does not distinguish itself from nearby siblings such as inspiration_detail or inspiration_bind.

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 context is only implied: the equivalent-to-UI-button framing tells the agent this is the favorite action, and the trailing clause suggests verifying afterward. There is no explicit when-to-use / when-not-to-use guidance or named alternative for reading favorite state (e.g., inspiration_detail).

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 supplied, so the description carries the behavioral burden. Reading '详情' implies a read-only fetch, and the description usefully notes that favorite status is account-scoped ('当前账号是否已收藏'), but it never states read-only semantics, permission requirements, or that project_path/instance_id select the working context. It is generous about returned fields but thin about behavior.

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

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

The whole definition is a single run-on sentence with stacked parentheticals, so it is dense and hard to scan, though the leading clause is front-loaded with the core purpose and every listed field is genuinely informative.

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 annotations, the description appropriately compensates by enumerating the returned fields (including nested video attributes like url, cover_url, likes, size), which is exactly what an agent needs to know before calling. It is only missing the usage/alternative context, which the field enumeration cannot cover.

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% and each of the three parameters (instance_id, project_path, inspiration_id) is already documented in the schema, including the either/or relationship. The description adds no additional parameter semantics, 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 it is the detail view of a single inspiration ('一个灵感的详情') and then enumerates the concrete payload: gameplay notes, effect type, incentive info, images, author, rewards, related hotspots, official project, existing effects, videos, stickers, and favorite status. That is specific enough to distinguish it from a list operation, though it never explicitly contrasts with siblings like inspiration_list or task_detail.

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 versus inspiration_list (which produces the id), rank_hotspots, or task_detail, all of which the parameter schema itself says also yield inspiration_id. The only routing hint is '用 image_view 看' for images, which is a follow-up action rather than a use-case boundary.

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 does a good job: it discloses that all category tabs are returned on every call, that tab defaults to the first (全部), and — critically — that *_ref references are only valid for the lifetime of this MCP service run. That lifetime caveat is a real behavioral constraint an agent could not infer from structured fields. It does not mention permissions or rate limits, though these are low-risk for a read.

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 purpose, then the field list, then the forward reference to inspiration_detail, then a separate paragraph on ref resolution and lifetime. Every sentence carries information, though the ref paragraph is somewhat dense and could be tightened; the explanatory gloss on what an inspiration is is justified for grounding.

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, and the description compensates by naming the returned fields and explaining that media come back as short *_ref references that must be resolved via image_view, with videos/audio returning original addresses. Combined with a fully documented input schema, an agent has enough to call this correctly; only cross-tool selection guidance versus non-inspiration listing tools is absent.

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 tab, count, cursor, instance_id and project_path including the 全部 default and next_cursor paging. The description only reinforces the tab-source rule and does not add syntax or format details beyond that, so the 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 + resource + scope: paginated listing of inspirations under a category, and defines what an inspiration is (effect ideas published by officials and creators, matching the homepage '灵感' tab). It also enumerates the returned fields (inspiration_id, title, tags, author, favorite count, favorited flag, AI flag, hotspot, cover_ref), so an agent can tell instantly that this is the discovery/listing tool distinct from inspiration_detail.

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

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

Explicitly routes the agent forward: 'after getting inspiration_id, use inspiration_detail to see details', and explains that tab values come from the tabs returned in a previous response. It stops short of naming when NOT to use this tool (e.g. versus library_list or rank_hotspots when the agent wants hotspots or assets), so no exclusions are given.

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 supplied, the description carries the full behavioral burden and does so: it declares the operation undoable, spells out the pipeline (package download, MD5 verification, import, default scene placement), states it blocks until the object appears in the scene, and clarifies that AI image / AI makeup kinds only download existing results with no regeneration and no credit consumption. That is exactly the permission, side-effect and cost information an agent needs before a mutating call.

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

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

A single dense paragraph where each clause carries real information (pipeline, kind dispatch, return shape, prerequisite, verification). The return-value detail and the prerequisite are somewhat back-loaded rather than front-loaded, which slightly hurts scanability.

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, and the description compensates by naming the response fields (kind, added_objects with object names and object_path, package_folders). Combined with the kind-specific behavior and the pre/post-step guidance, nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all five parameters; the description adds the session-scoped provenance requirement for template_id and reinforces the kind=package constraint on auto_instantiate. It does not add new syntax or edge cases beyond that, but it does more than restate 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 ('apply an official asset to the target project') and anchors it to a familiar UI action ('same as clicking Apply in the library panel'). It also distinguishes this tool from the sourcing siblings (library_list / library_search) and from music_apply by scoping itself to official material and plaza cards.

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 hard prerequisite ('template_id must come from this session's library_list / library_search') and a follow-up step ('use capture_preview to verify'), plus explains that plaza cards dispatch by kind. It stops short of an explicit exclusion such as when to prefer music_apply or aweme-style flows, so it is strong but not a full when/when-not map.

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 supplied, the description carries the full disclosure burden. It does add useful behavioral context — the *_ref values are short references and are only valid for the duration of this MCP service run — but it never says the call is a read-only, side-effect-free lookup, nor does it discuss result size or ordering; the video/audio reference note appears to be generic boilerplate unlikely to apply to this 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 first sentence is well front-loaded and earns its place. The second paragraph about img:/video: short references reads as shared boilerplate pasted across tools, and its video/audio clause is not clearly relevant here, so it dilutes rather than sharpens the definition.

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 must explain what comes back — and it does, describing a per-card set of result images enumerated by image_index. Combined with the reference-lifetime caveat, an agent has enough to call it and hand the refs to image_view; only the read-only nature is left implicit.

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 instance_id, template_id and project_path are already fully documented, including the instance_id/project_path either-or. The description only restates the template_id provenance that the schema already states, adding no new 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?

The description identifies the resource precisely: the full set of result images for an AI image card (kind=ai_image), with each image_ref numbered by image_index. It also names the sibling tools it pairs with (image_view, library_apply, library_list/library_search), so it is distinguishable. It lacks an explicit verb (it reads as a noun phrase rather than 'list/get'), which slightly blunts the action.

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 concrete routing: use image_view to look at the images, use library_apply with the image_index to apply one, and template_id must come from this session's library_list/library_search. That is clear when-to-use and prerequisite guidance, though it never states a when-not-to-use condition.

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 important behavior: square (aigc_material) items apply without regeneration or quota consumption, generated AI panels are excluded, panels without applicable content are omitted but counted in unsupported, and *_ref references expire when the MCP service run ends. However, it does not cover error behavior, auth/prerequisite needs, or the difference between instance_id and project_path beyond what the schema already states.

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 behavior before the alternative tools and downstream steps, and almost every sentence adds information. The downside is density: the long parenthesized enumeration of panel kinds and the catalog of subcategories make it a wall of text that is harder to scan than a short bulleted structure would 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?

With no annotations and no output schema, the description supplies what an agent needs: the shape of the response (panels, subcategories, materials with template_id/title/kind/cover_ref, next_cursor), pagination behavior, the unsupported counter, and the lifetime of image/video/audio references. It is nearly complete for a browsing tool, with only retrieval edge cases left unstated.

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

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

Schema coverage is 100%, so the schema documents all six parameters and the baseline is 3. The description does add real meaning for panel_key by explaining the general/square/collection grouping and the kinds inside each, and it hints at subcategory structure for category_id, but the other parameters (count, cursor, instance_id, project_path) are described only in the schema.

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

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

The description states two precise modes: with no panel_key it lists applicable panels and kinds, and with panel_key it paginates the materials inside that panel. It names the resource (panels/materials) and the exact identifiers returned (panel_key, kind, template_id, cover_ref), so an agent can distinguish it from library_search, library_apply, and library_images without opening any schema.

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

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

It gives explicit routing: use image_view when selecting by visual appearance via cover_ref, use library_search when you know what keyword you want, and use this tool when browsing by panel and subcategory. It also states the downstream steps (library_apply for template_id, library_images for ai_image results), which is clear when-to-use and when-not guidance.

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

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

With no annotations supplied, the description carries the full burden and delivers unusual detail: per-panel/per-subcategory result caps (最多 300 条), a fully specified ranking order (exact title > prefix > contains > category match > rest), the meaning of the matched field, a 10-minute result cache that makes paging free, and the lifetime of returned *_ref handles (valid for this MCP run). This is exactly the operational context an agent cannot infer from the schema.

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

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

Purpose and matching behavior are front-loaded, then ranking, pagination, and return fields follow in a logical order. It is dense but long, and the kind enum listing and cap repetition add bulk that could be tightened without losing 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 7-parameter search tool with no annotations and no output schema, the description still documents the return shape (template_id, title, panel_key, kind, cover_ref, total, by_panel, matched_categories, related_categories), the full kind enumeration, and how to consume *_ref values via image_view. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it links queries to synonym-batch usage with a concrete example, ties offset/count to the cache so paging does not re-request, and connects panel_key to the by_panel return field for narrowing. It does not clarify the instance_id/project_path either-or beyond what the schema already says.

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 (按关键词搜索官方素材库) and enumerates the covered domains (美妆、滤镜、贴纸、音效等), so an agent can immediately tell this is the keyword-search path over the material library. It also names the sibling boundary — library_list for enumerating categories, image_view for resolving refs — which most search tools omit.

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 concrete usage context: semantic/panel-name matching with worked examples (「滤镜」→滤镜面板, 「腮红」→美妆/腮红), queries for up to 8 synonyms, and panel_key to narrow from by_panel. It does not explicitly state when to prefer library_list or library_images over searching, but the routing to library_list for related_categories implies the boundary.

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 real behavior: it reads the scene file, defines what makes a layer ineffective (hidden object/parent, disabled component, both intensities 0), and explains how part_from and color weighting are derived. However, the save_to parameter implies a save/side-effect operation that the description never addresses at all, leaving a meaningful behavioral gap.

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

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

Purpose is front-loaded in the first clause, but the remainder is one dense run-on paragraph that mixes usage, effectiveness rules, part-inference logic, and output field meanings without separation. Most clauses are earned because there is no output schema, yet the lack of structure hurts scanability.

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

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

For a complex analysis tool with no output schema, the description explains the returned fields an agent needs (groups, absent, part_from, color, hsl, intensity) and the effectiveness determination, which is the important part. The only significant omission is what save_to does, keeping it from 5.

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 both project_dir and save_to. The description adds context about the project directory (pointing to works_download's project_path) but says nothing about save_to's semantics that goes beyond the schema, 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?

Opens with a clear verb+resource: list all makeup layers (FaceMask妆容层 and EyeColorV2美瞳) in a project. It specifies the exact scope and the two layer types covered, so an agent can distinguish this from general project or scene inspection tools without reading further.

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 concrete use cases: see what a makeup set is missing, or reverse-engineer which parts and colors someone else's works_download project used, plus a prerequisite (save_project first for a project being edited). It does not name an alternative tool or state when-not to use it, so it stops short of 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?

With no annotations, the description does real work: it discloses that the operation is equivalent to an editor menu click, that it is undoable (可撤销), that package-type items trigger a download before import, and what the result contains (added_objects with name and object_path). It omits permission/auth requirements and whether the project must be saved afterward, 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?

Three compact clauses, each carrying unique information: what it does, the undo/download caveats, and the return shape. Nothing is repeated from the schema and the core action is front-loaded.

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

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

For a mutation tool with no annotations and no output schema, the definition covers the essentials including a description of the return value. The remaining gap is context around preconditions (an open project, and that menu_id should be fetched via menu_list), which is only inferable from the schema rather than stated.

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 menu_id, instance_id and project_path are all already documented in the schema, including the instance_id/project_path either-or and the 'may omit when only one project window is open' rule. The description adds only the semantic that menu_id selects an official menu entry and that package-type entries have side effects. That is marginal value over the schema, so the 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 + resource: 'add an official feature object to the scene by menu_id', with the equivalence 'same as clicking in the editor menu'. That is concrete and distinct from siblings like menu_list (listing) or works_download (asset acquisition). It stops short of naming a sibling explicitly, so it is clear but not fully differentiated.

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 phrase '按 menu_id' plus the schema note that menu_id comes from menu_list hints at a lookup-then-add flow, and 'kind=package 的项会先下载' hints at a slow path. There is no explicit 'use this when X, use Y instead' guidance or statement of prerequisites such as needing an open project.

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 returned fields, that details=true adds description plus an image that is either image_url, a local image_file, or null, and that details is capped at 8 items with an error when query matches more. It never states read-only/no-side-effect behavior explicitly, which is the remaining gap for a mutation-free listing 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?

Purpose and the sibling differentiation are front-loaded, but the text is one long dense block with lengthy parenthetical category enumerations (面部提拉、祛皱纹、烟熏妆、卡通脸…) that could be trimmed. It is information-dense rather than wasteful, yet the sprawl hurts 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?

There is no output schema, and the description fully covers return values, the details variant with image fallback semantics, the 8-item error condition, and which sibling to use for excluded cloud AI items. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: query matches 中文名, 路径 or menu_id with concrete examples, and details has a hard consequence (query matching more than 8 items raises an error) beyond the schema's softer '须不超过 8 个'. instance_id and project_path are left entirely to the schema, which is acceptable given full coverage.

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

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

States a specific verb and resource: lists every official item in the 「添加对象」 menu, and names the returned fields (menu_id, 中文名, 路径, 类型). It explicitly differentiates itself from sibling tools menu_add, add_builtin_object, ai_combine_new and ai_combine_apply, so an agent can select it without opening any 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?

Gives explicit when-to-use routing: this tool enumerates the menu, add_builtin_object covers only part of it, menu_add is for 美容/面部生成/表情生成/性别年龄/五官处理/身体换装, and cloud AI combos use ai_combine_new / ai_combine_apply. It also states an exclusion (云端 AI 生成项不在列表中) and points at image_view when picking effects visually.

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 supplied, the description carries the full burden and does so well: it discloses the network side effect (uploading the effect package to Douyin servers), the possible moderation failure with the exact error code MOBILE_PREVIEW_MODERATION_FAILED, and the lifecycle of the generated qr_file (auto-deleted at expires_at, typically 7 days). This is behavior that could not be inferred from the schema.

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

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

Front-loaded with the core action and then the return artifacts, side effects, and error code in a logical order. It is dense but nearly every clause carries operational value; a slight trim of redundant phrasing about the QR file would make it tighter.

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?

Although there is no output schema, the description explains the return payload (QR image, its text, validity period, qr_file), the storage location and expiry, and the failure mode. For a two-optional-parameter tool, an agent has everything needed to call it and report results correctly.

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

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

Schema coverage is 100%, and each parameter already documents its mutual-exclusion rule (instance_id vs project_path, both omittable when only one window is open). The description adds nothing about the parameters, so the baseline 3 applies — the schema does all the work here.

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 concrete verb+resource pair: packages the current project the way the toolbar's "手机预览" does, uploads it, and returns a QR code. The comparison to the editor toolbar action plus the explicit return artifacts (QR image, its text, expiry) makes the purpose unmistakable and separates it from generic preview siblings like preview_frames.

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 usage context — scan the QR with the Douyin app to check the effect on a real device — and implicitly anchors the tool to the equivalent toolbar action. It stops short of explicitly contrasting with alternatives such as preview_frames or submit_prepare, so the agent must infer when not to use it.

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

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

With no annotations, the description carries the full burden and does well: it discloses that audio is downloaded into the project, that a scene object is created, and critically that re-invocation REPLACES the previous track — a destructive side effect an agent must know. It omits error/permission conditions (e.g. what happens with no open project, download failures), keeping it at 4 rather than 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?

Front-loads the core action and equivalence, then parameters, then next steps — a logical order with no filler sentences. It is a single dense block of clauses rather than clearly separated segments, which slightly hurts scanability but wastes no words.

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 mutating tool with five parameters, no annotations, and no output schema, the description covers what an agent needs: the action, the replacement semantics, the clipping behavior, the ID provenance constraint, and the verification/persistence follow-ups. Missing only failure modes and whether the audio download is slow or rate-limited.

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 five parameters are already documented. The description adds only modest meaning: that start_sec/end_sec jointly define a clip with 'default whole song', and that music_id must be sourced from music_list in this session (partly already in the schema). This is the baseline-3 case where 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?

States a specific verb and resource ('把一首抖音音乐设为特效的音乐') and immediately anchors it to a known UI action ('和音乐库里点「使用」相同'), then enumerates the three concrete effects: download audio, write music info, add a Douyin music object to the scene. This distinguishes it from siblings like music_list (discovery) and library_apply (non-music library assets).

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 hard prerequisite ('music_id 须来自本会话的 music_list') and a follow-up workflow ('之后 capture_preview 验收、save_project 落盘'), which tells the agent how this tool fits into a sequence. It stops short of naming an alternative tool for other music sources or stating an explicit when-not-to-use condition, so it is not a full 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?

Because there are no annotations, the description carries the full burden, and it discloses real operational behavior: the page size of 35 for category browsing, the fact that *_ref references are valid only during this MCP service run, and a safety-relevant warning that has_copyright=false or null must not be used for effects intended for publishing. It omits authentication and permission requirements and does not state whether the operation is read-only, though that is self-evident.

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 modes, then lists return fields, then follows with the reference-resolution rules. Every sentence carries information, though the reference-resolution paragraph is generic cross-tool plumbing that could live in shared documentation rather than here.

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 must explain the returns, and it does: music_id, title, author, duration_sec, cover_ref, preview_ref, and has_copyright with its usage caveat. The remaining gap is that the description does not say how many results a query search returns or whether results can be paged, but the category case is specified.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema cannot express: the default behavior when both query and category_code are omitted returns the category codes and names, and category_code yields the first page of 35 tracks. That mode interaction is genuinely beyond the field-level 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 and resource (list Douyin music) and defines three operating modes: neither parameter (category list), query (keyword search), and category_code (first page of a category). It clearly describes the tool's unique behavior, though it never names the sibling music_apply or explains how this tool differs from it (list versus apply).

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

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

The description gives explicit mode-selection guidance: how to call the tool when you want the category list, when you pass query, and when you pass category_code (first page, 35 tracks). The only gap is that it does not say what to do next, such as using music_apply to apply a track, or when to choose search over browsing categories.

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 supplied, so the description must carry this information itself. It does well: it frames the tool as returning a review-record set rather than mutating anything; it states that reviews are ordered newest-first; it names and explains the status values; it says the text has markers stripped; and it notes that innovation_reviews is empty when there is none. It does not state permission or quota 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?

It is a single dense sentence that is front-loaded with the purpose and then enumerates the return structure field by field; no sentence is wasted. It is a run-on and slightly heavy, but every clause carries information the schema does not.

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 must explain the return value, and it does so thoroughly, covering both timelines, ordering, and the nested fields time, text, refuse_reasons, and links. What is missing is minor: there is no note on how a large history is bounded or how the instance/project context affects the result.

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%, and the schema already explains that effect_id comes from my_effects and that instance_id/project_path are mutually exclusive, with both optional when a single project window is open. The description adds nothing about the parameters, 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 names a specific resource (the review records of one's own effect) and explains what is returned: the name, current status, bound task, plus two timelines (reviews and innovation_reviews). It is clear what the tool does, but it never names a sibling it differs from, so an agent cannot tell from the text alone why it should call this instead of effect_check, works_by_effect, or task_detail.

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 says the tool covers 'one's own effect' and mirrors the mobile app's '审核记录' page, which implies when it is relevant. However, there is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives, so the caller must infer the selection rule.

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

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

There are no annotations, so the description must carry the full burden of explaining the tool's behavior—and it mostly does. It gives the meaning of each status code (100/101/111/112/120/103/104/113/118/119), describes the nested `review` object (text, refuse_reasons, links) that appears only on 101/112/119 effects, and warns that returned refs are valid only for the lifetime of this MCP service run. It never states that the tool is read-only or what permissions it requires, which is a small gap for a listing 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?

It is dense but ordered well: it first explains what the result is and how it is ordered, then details the returned fields and status codes, and finally explains ref handling and how refs are passed to image_view. Listing every status code is verbose, but because there is no output schema, that list earns its place. A few clauses could be tighter, but overall it is information-dense with little 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?

There is no output schema, and the description fully compensates by documenting the returned fields, the status code table, the conditional `review` subobject, and the short-ref indirection to image_view with its validity window. For a 4-parameter, 0-required tool with 100% schema coverage, nothing an agent needs in order to call it or interpret its output is missing.

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

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

Schema description coverage is 100%: the schema already documents count (default 20, max 50), the cursor (take next_cursor verbatim), and the instance_id/project_path alternative. The description adds nothing about these parameters, so the baseline of 3 applies; it does not compensate for anything because nothing needs it.

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 definition states a specific verb and resource: the effects that the currently logged-in account has submitted, ordered with the newest first, and notes that it uses the same interface as the 像塑 mobile app's 「作品」. It also names the sibling tool it is not: my_effect_reviews is for the full review timeline, so an agent can distinguish the two without opening either 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 description explicitly tells the agent when to switch tools: for the complete review timeline, use my_effect_reviews instead, and pass returned image/video/audio refs to image_view. It does not clearly contrast with works_list or works_by_effect, but within its own scope, the guidance is clear and actionable.

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 so well: it discloses that child objects are removed, that the object deletion is undoable, that resource deletion is NOT undoable, and that the default is report-only. It also explains editor_only_paths are editor-side artifacts that vanish on next save and must not be deleted, plus that unused_paths only contain paths existing on disk — behavior an agent could not infer from any structured 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?

The core action and its scope are front-loaded and every sentence carries distinct information. However, the definition is one dense run-on paragraph with stacked parentheticals covering deletion, orphan detection, editor folders, and sibling routing, which makes it harder to scan than a short structured list would 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?

There is no output schema, so the description must explain return values, and it does: it defines unused_paths, editor_only_paths, and the report-vs-delete outcome of the flag. For a destructive, two-mode tool this covers everything an agent needs before invoking 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 the baseline would be 3, but the description adds real meaning: object_path accepts a full hierarchy path or unique trailing segments (with a concrete example), and delete_unused_resources is characterized as destructive and off by default. instance_id and project_path are left entirely to the schema, which is acceptable given full coverage.

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

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

The opening clause gives a specific verb and resource ('删除一个场景对象（含子对象，可撤销）') and immediately extends it to the orphan-resource discovery behavior, which is the tool's real differentiator. It names the siblings it is not (delete_render_group, edit_by_dsl, resource_delete_unused), so an agent can distinguish it 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?

Explicit routing is provided for every adjacent case: render groups go to the official delete_render_group, object-only deletion can use edit_by_dsl, and deferred resource cleanup uses resource_delete_unused. The default-vs-opt-in behavior of delete_unused_resources is also stated, so the agent knows when to set it.

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

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

With no annotations supplied, the description carries the full burden and does so well: it discloses that capture works with the window backgrounded or minimized (temporarily restoring normal frame rate), that it resets the preview and waits for the reloaded frame by default, that switching videos has a side effect (project becomes modified), and that frames land in a temp directory and are deleted after 24 hours unless save_to is given. The only blemish is the stated cap of 24 frames per run, which conflicts with the schema's count maximum of 12 and videos maxItems of 4.

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?

Nearly every clause carries real information — resolution, background capture, reset behavior, side effects, retention, timestamps — with little filler. The weakness is structural: it is one long run-on paragraph with stacked parentheticals rather than being front-loaded into capture behavior, side effects, and output in that order.

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 nine-parameter tool with no annotations and no output schema, the description covers the mechanics, side effects, and file retention an agent needs to call it safely. Return-value detail is only loosely sketched (paths in files, per-frame timestamps), which is acceptable given there is no output schema but leaves the exact response shape partly implicit.

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

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

Schema coverage is 100%, so the baseline would be 3; the description goes further by explaining that crop is ratio-based and typically used to isolate a face, that save_to is the long-term alternative to the 24-hour temp directory, that videos are used one after another and the original is restored at the end, and that each frame carries a timestamp relative to reset completion. It does not mention instance_id/project_path at all, leaving the target-selection semantics entirely to the schema.

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

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

The description states a specific verb+resource: consecutively capture preview frames at a fixed interval from the preview render output, with the resolution explicitly pinned (720×1280 vs. the official 320×569). It also names the concrete purpose (seeing motion, the side of the face during a head shake), which separates it from static-image siblings like image_view or mobile_preview.

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

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

It gives clear when-to-use context (viewing dynamic effects, side profile while shaking the head) and points at list_preview_videos as the source of the videos names, including a format example. It also warns that switching videos marks the project as modified and requires save_project afterwards. It stops short of stating when NOT to use it, e.g. why you would pick image_view or mobile_preview instead.

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 supplied, the description carries the full behavioral burden and does disclose the key trait: a default refusal on unsaved changes, plus the mutation escape hatch and the safe alternative (save_project). It does not state what the tool returns, whether other open windows are affected, or what the state is after a forced discard. Strong for a mutation tool, but not fully 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?

Two sentences, zero filler, with the default-safe behavior and the escape hatch front-loaded. Nothing repeats the schema and nothing is left dangling.

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

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

For a 3-parameter, zero-required mutation tool with no annotations or output schema, the description covers the decisions that matter: prerequisite save, default refusal, forced-discard semantics. The missing piece is target-resolution behavior when both instance_id and project_path are omitted (single-window case), which affects whether an agent can call it blind.

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 3 is the baseline. The description earns above baseline by explaining the behavioral consequence of the discard_changes flag (default rejection vs. forced close) rather than just naming it. It does not clarify the instance_id / project_path mutual exclusivity or the 'both omittable when a single window is open' rule, which the schema itself carries.

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 ('关闭一个工程窗口' = close a project window) and anchors it to a concrete UI equivalent ('等同工具栏「回到首页」'), which removes ambiguity about what closing means here. Against the sibling set (project_open, project_new, works_cleanup), the scope is unmistakable.

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?

Names the prerequisite alternative explicitly ('有未保存改动时默认拒绝，先 save_project') and gives the exact condition for the destructive path ('确实要丢弃改动才传 discard_changes=true'). The 'only if you really mean it' framing of the discard path is real guidance, not a restatement.

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 disclosure burden. It does useful work by stating the directory-emptiness constraint, the open-window prerequisite, and the return values (pid and instance_id), implying a new window is spawned. It is silent on failure behavior when prerequisites are unmet and on any side effects of a partial save.

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

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

Three tight sentences with no waste: action first, then preconditions, then return value. Every clause contributes information an agent needs before calling 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?

For a single-parameter creation tool with no output schema, the description covers purpose, prerequisites, and return values, which is enough to attempt a correct call. It could go further on error conditions and whether the created window remains open, but nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a real constraint not in the schema: the directory must not already exist or must be empty. That materially affects how an agent must choose the path value.

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 a new blank Xiangsu project and save it to path for the first time. 'New blank project' implicitly distinguishes it from the sibling project_open, though it never names that 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?

Clear preconditions are given: the target directory must not exist or must be empty, and an existing project window must already be open. It stops short of naming alternatives (e.g., project_open for existing projects) or explicitly stating when not to use it.

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

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

With no annotations, the description carries the full load, and it discloses two non-obvious behaviors: the idempotent short-circuit when the project is already open, and that old-version projects can trigger an upgrade dialog which requires manual confirmation in the editor. It does not cover failure modes (invalid path, missing effect.dyehpj), permission needs, or whether the call blocks, so it is not fully transparent.

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

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

Three short sentences, the core action first, then the return values, then the one operational caveat. Every sentence adds information an agent needs, with no filler.

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

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

For a simple single-parameter tool with no output schema, the description usefully names the return values (pid, instance_id) and warns about the upgrade dialog, so an agent knows what to expect after calling it. Only error behavior and the difference from works_open are left unaddressed.

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 documents the single path parameter at 100% coverage, including that it is absolute and must include effect.dyehpj, so the description need not repeat it. The description adds no extra meaning about path format or path aliases, so the 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 says exactly what it does: opens an existing project (已有工程) in a new window, and it also covers the already-open case. 'Existing' implicitly contrasts with the sibling project_new, but it never names brothers like project_new, project_close, or works_open, so an agent must infer which one to choose.

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: it applies to an existing project folder, and if the window is already open it returns directly, which is useful idempotency context. There is no explicit 'use project_new instead when...' or warning about when not to call it, so the guidance is adequate but not directive.

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 meaningful work: it discloses the hourly refresh cadence, that pagination follows next_offset, and — most valuably — that *_ref/*_refs media handles are short-lived and only valid for the lifetime of this MCP service run. It stops short of stating read-only semantics or error/empty-result behavior, but the reference-lifetime disclosure is exactly the kind of non-obvious trait agents need.

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?

Purpose and pagination are front-loaded, which is good, but the image_view handoff is stated twice (once for cover_ref in the hotspot paragraph, again for *_ref/*_refs in the closing paragraph), so the second paragraph partly repeats the first. The field enumerations are dense but reasonably earned since there is no output 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?

For a five-parameter tool with no output schema, the description compensates by enumerating the returned fields for both the hotspot mode and the inspiration mode, and by explaining the media reference scheme. Only the optional instance_id/project_path scoping story is left entirely to the schema, which is acceptable here.

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 offset, count, topic_id, instance_id, and project_path; the description mostly restates the paging and the topic_id mode switch. It adds only the return-field lists per mode, not new meaning for the parameters themselves, 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 names a specific resource (抖音热点榜, sorted by 热度, refreshed hourly) with a clear verb-like action of ranking/listing, and it explicitly describes a second mode: passing topic_id returns the inspirations under that hotspot. This distinguishes it well from generic siblings like rank_list or inspiration_list, though it never explicitly names which sibling to prefer.

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 solid routing rule: pass topic_id to switch from the hotspot list to that hotspot's inspirations, and hand media refs to image_view. But there is no guidance on when to use this instead of rank_list, rank_subjects, rank_innovation, or inspiration_list, and no prerequisites for instance_id/project_path are stated in prose.

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 substantial work: it discloses the per-kind return field sets (standing in for a missing output schema) and an important lifecycle constraint — short media references are only valid for the current run of the MCP service. It does not explicitly state the tool is a pure read with no side effects, but nothing suggests otherwise.

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 tool's identity, then organized by kind, then by output-reference handling — a logical progression with little filler. The clause describing the mobile discovery page ('像塑移动版发现页的精选列表，移动版展示的是模板') is the only mildly redundant passage, since the schema already explains the template/effect distinction.

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 five-parameter read tool with no output schema, the description supplies the return shapes per kind and the reference-resolution rule, which is what an agent most needs. It omits how pagination continues (the schema's next_offset does cover this) and gives no hint of result ordering or typical volume, minor gaps rather than blocking ones.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning by mapping each kind value to the concrete records returned (official selections vs. creator monthly ranking), which is exactly the information an agent needs to pick kind. instance_id/project_path are left entirely to the schema, which is acceptable given its coverage.

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

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

The description opens with a concrete resource ('创新计划的榜单') and then enumerates exactly what each kind returns (effect name, effect_id, tags, submission count, revenue, selected date, cover vs. rank, uid, nickname, work count, remix count, bonus). That is far more specific than the bare name, though it never names its ranking siblings (rank_list, rank_hotspots, rank_subjects) or states how it differs from them.

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 one explicit routing instruction is downstream: '*_ref / *_refs ... 交给 image_view' with a clear statement of what image_view does for each media type. There is no guidance on when to choose this tool over the sibling ranking tools, and no prerequisite or exclusion stated; usage is implied by the meaning of the kind values.

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 substantial work: it discloses that results are paginated with a cursor, that each page carries that day's category tree, and — importantly — that image/video/audio come back as short refs (img:12, video:3) that are only valid for the lifetime of the current MCP run and must be routed through image_view. It stops short of stating permission requirements or that no state is mutated, though '读取' implies a read.

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?

Purpose and content list are front-loaded, then filtering, then cross-tool routing, then return-value semantics — a logical order with no filler sentences. It is dense and long, but nearly every clause carries information an agent needs; the only soft spot is the slightly sprawling category parenthetical.

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 12-parameter tool with no annotations and no output schema, the description compensates well by describing the returned fields and the ref-based media handling. Gaps remain around pagination termination and what the response envelope looks like (next_cursor is only named inside the schema), but nothing critical for calling it correctly is missing.

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

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

Schema description coverage is 100%, so date, count, cursor, rank_type, categories and the rest are already documented in the schema, including the 'take next_cursor' and 'take categories from the previous page' rules. The description reinforces the category hierarchy idea (level 1 大类 vs level 2 细类) but adds no new syntax or constraints beyond what the schema states, 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 names a specific verb and resource — paginated reading of a 排行榜 — and enumerates the returned fields (名次、effect_id、等级、投稿量、跟拍量、热玩分…). It explicitly separates itself from rank_subjects for topic-based boards and from works_by_effect for drilling into one effect, so an agent can distinguish it from the many rank_* siblings.

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

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

It gives clear routing for two cases: subject/topic boards go to rank_subjects, and inspecting a specific effect's project goes to works_by_effect. It does not, however, say when to pick this over rank_hotspots or rank_innovation, so the alternatives guidance is partial rather than exhaustive.

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，描述承担了全部说明责任。它正确披露了返回内容（前几个特效、浏览量）、keyword 与分页交互，以及重要的引用机制——*_ref/*_refs 短引用仅在本次 MCP 运行期间有效，并交给 image_view。但它从未说明这是安全的只读操作、是否可访问所有工程、或是否需要授权。

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?

把 kind 用法和返回引用说明前置，总体结构良好；每一段都提供可用信息，没有空话。第一句很长，示例挤在一起，但去掉示例会降低工具准确调用的能力。

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?

面向一个 7 参数的只读工具——没有 annotations、没有 output schema——描述涵盖了榜单内容、分页行为、keyword 覆盖，以及按会话有效的图片/视频/音频引用处理。它没有列出完整的返回字段或明确说明 next_cursor，尽管 schema 已说明 cursor 的用法。

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 为 100%，因此基线是 3；描述在此基础上增加了值，因为它说明了每个 kind 值实际包含什么（示例榜单名、近 200 期、征集活动优质特效），以及 subject_id 是从本工具自身返回中获取的链式输入——这些是 schema 未说明的信息。它没有新增 cursor 或 instance_id 与 project_path 相互替代的语义。

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

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

描述清楚说明了具体资源（像塑移动版「专题合集」榜单），并用具体的榜单名示例区分 kind=effect（特效专题榜）与 kind=template（模板专题榜）。它允许 agent 在无需打开 schema 的情况下选择正确的 kind，但没有说明与兄弟工具 rank_hotspots、rank_list 或 rank_innovation 的区别。

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?

描述给出了清晰的使用上下文：keyword 按榜名搜索全部期且不分页，subject_id 返回该榜全部特效（最多 20 个），这等于说明了先列出、再用 subject_id 下钻的流程。缺少的行为是显式排除——它没有说明何时应改用 rank_hotspots 或 rank_innovation。

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 two most important traits: deletion is irreversible, and a pre-delete reference check will refuse still-used paths. It does not cover permission requirements, partial-failure behavior when only some paths are rejected, or what the response reports back.

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

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

Three short sentences, front-loaded with the action, then the source constraint, then the safety guard and irreversibility warning. Every sentence contributes distinct information with no repetition.

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

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

For a destructive, three-parameter tool with no annotations and no output schema, the description covers the source of input, the validation guard, and irreversibility. It is slightly thin on what happens when some paths are refused and how results are reported, which matters for a batch destructive operation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the paths must be the unused_paths values returned by object_remove and represent project-relative resource files or asset pack folders. It adds nothing about instance_id/project_path beyond what their schema descriptions already state.

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: delete the unused_paths reported by object_remove, and clarifies those paths are project-relative resources or asset pack folders. This clearly separates it from the sibling object_remove, which only reports them rather than deleting.

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?

States the precondition that paths must originate from object_remove's unused_paths, and a hard exclusion rule: anything still referenced by the current scene is rejected. It does not name an alternative tool for cleanup scenarios (e.g. works_cleanup), so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full burden and delivers: project_dir mode works without an open window by reading Assets/main.scene and main.scene.extra, objects are renumbered as #index, the render-group layer disappears and groups become root objects, component names fall back to scene-file names when editor data is missing, and unexpanded children are annotated with counts. save_to is disclosed as a persistent side effect that creates the directory.

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 most important comparison (versus get_scene) is front-loaded and the parameter notes follow in the order an agent would consult them. It is dense but nearly every clause carries new information; only the project_dir passage is long enough to be slightly hard to parse on first read.

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 6-parameter tool with no annotations and no output schema, the description still tells the agent what the output looks like (indented text per object), what a truncated tree looks like, and what session prerequisites each mode needs. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra credit by adding meaning the schema lacks, notably that save_to writes a file named scene_tree.txt inside the given directory and how subtree accepts #index or name in project_dir mode. It does not, however, explain the interplay or precedence among project_path and instance_id beyond what the schema already says.

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 output form (indented compact text) and enumerates exactly what each line contains: render group, guid, name, hidden flag, component types. It explicitly distinguishes itself from get_scene (full JSON) and inspect_many (parameter lookup), so an agent can pick the right tool without opening schemas.

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 workflow (survey structure first, then inspect_many for parameters), names the alternative for full JSON (get_scene), and routes single-object exploration to the subtree parameter. Both the when-to-use and the when-not-to-use are spelled out.

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 present, the description carries the full burden and does so: it discloses that a leftover submission window may be closed (closed_previous count, WINDOW_NOT_CLOSED failure), that the window stays open on mid-flow errors, that page prompts are surfaced verbatim, that page detection takes about a minute, and that publishing only occurs after a user click. Unfilled page settings are preserved and reported in other_sections, so the agent knows the tool does not silently overwrite the form.

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?

Purpose is front-loaded in the first clause, and nearly every sentence conveys operational detail (check order, page-by-page fill, error behavior). It is nonetheless a single dense block of roughly 400 characters, and the return-value enumeration at the end could be split or tightened for 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?

For a 9-parameter mutation tool with no annotations and no output schema, the description supplies the missing return contract (page summary, per-check results, agreement state, submit-button clickability, next step, other_sections, issues) plus failure semantics. Nothing an agent needs to invoke it safely appears to be absent.

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 explains name length rules, camera enum, task_track requirements, and the instance_id/project_path mutual exclusion. The description adds only ordering context — e.g. icon_image is applied before the window opens — rather than new meaning about the parameters themselves. 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 opens with a precise verb+resource+end-state: fill the submission window and stop before the user clicks 「提交审核」. It explicitly delineates what the tool will NOT do (no agreement checkbox, no submit click) and contrasts its own entry path with the toolbar 「提交特效」 button, so an agent can distinguish it from adjacent tools like effect_check or my_effect_reviews.

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 specifies the precondition sequence (local checks must pass first, otherwise no window opens and issues are returned) and names concrete error exits (SUBMIT_*, SUBMIT_TASK_NEEDS_TRACK). It also implicitly routes icon work to icon_image and mentions the task/inspiration binding tools. What is missing is an explicit statement of when a caller should use this versus doing a manual staged submission through icon_set / task_bind / inspiration_bind separately.

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 supplied, so the description must fully disclose the side effects, and it does: the project window is closed (refused if there are unsaved edits), then reopened with the task bound, and a new pid and instance_id are returned. It discloses the mutation, the failure mode, and the return values an agent needs for follow-on calls.

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

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

The description is front-loaded with its purpose, then moves through mechanism, precondition, and alternative in a logical order with no filler sentences. It is dense and multi-clause, which makes it slower to parse, but every sentence contributes required 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 two-parameter mutation with no annotations and no output schema, the description covers everything an agent needs: purpose, required provenance of task_id, the save_project precondition, the returned pid and instance_id, and the submit_prepare alternative. Nothing material is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, including the bindable=true constraint on task_id. The description still adds a useful constraint beyond the schema by requiring that task_id come from tasks_list in the current session, though it adds nothing about the path parameter that the schema does not already say.

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 (bind a project to an already-claimed task) and explains the mechanism precisely: the editor only writes task info when a project is opened, so the tool closes and reopens the window. It also distinguishes itself from the closer sibling submit_prepare by explaining the different route to the same outcome.

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

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

It gives explicit prerequisites (task_id must come from tasks_list in this session; the project must have no unsaved changes, otherwise call save_project first) and explicit when-not-to-use guidance: if you only want to pick a task at submission time, pass the claimed task title to submit_prepare instead of reopening the window. This is the strongest kind of 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 at all, the description carries the full behavioral burden and does substantial work: it discloses that embedded media comes back as short refs (img:12, video:3) that are only valid for the lifetime of this MCP run, that unusable/blob URLs are only counted in unusable_media, and that unrecognized fields land in unread. It never states that the call is read-only or what happens on an invalid/foreign task_id, which keeps it below the top score.

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

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

The purpose is front-loaded, but the body is a single very long run-on sentence enumerating return fields, followed by two more dense paragraphs; a bulleted field list would be far more scannable. Most of the content earns its place given there is no output schema, but the packaging is heavy and hard to parse at a glance.

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 must explain the return value — and it does so thoroughly for both task variants: field-by-field for 征集任务, a separate summary for 成长任务, plus edge cases (unusable media, unread fields, money_mode/people semantics). Nothing an agent needs in order to call this correctly or interpret the result is missing.

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

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

Schema coverage is 100% and every parameter is already documented in the schema, so the baseline of 3 applies. The description adds the session-scoped provenance of task_id and the purpose of save_to, but it says nothing about instance_id/project_path (the either/or pair) and nothing about the save_to file naming or retention beyond what the schema already 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?

Opens with '一个任务的详情' — a clear resource (a single task's detail) whose content is then enumerated, so an agent knows exactly what it retrieves versus tasks_list (which supplies the ids). The verb is implied rather than stated, but the resource and scope are unambiguous and the differentiation from the sibling tasks_list/task_receive is evident.

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 an explicit prerequisite ('task_id 须来自本会话的 tasks_list') and an explicit exclusion ('活动没有详情'), plus a routing note that growth tasks return a different shape (rewards, reference projects, inspiration, tutorials). It stops short of naming which sibling to use instead when the target is an activity, so it is not a full when/when-not/alternative statement.

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 well: it discloses that the write is bound to the currently logged-in account, that the action is irreversible ('领取后不能撤销'), and that invalid statuses are rejected rather than partially applied. It does not cover concurrency or error payloads, nor whether instance_id/project_path affect the outcome.

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

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

Three dense sentences, each earning its place: what it does, the precondition and irreversibility, then the return value and next step. The irreversible-write warning is front-loaded 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?

Covers the operation, its irreversibility, the gating status, return fields and the required follow-up call — everything an agent needs to sequence it correctly. The only gap is that the role of instance_id/project_path is left entirely to the schema, though that schema is fully described.

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 task_id, instance_id and project_path are already documented, including the tasks_list source and the instance_id/project_path mutual exclusivity. The description adds no parameter-level detail beyond what the schema provides, so the 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 ('领取一个征集任务' / claim a solicitation task) and immediately scopes it against the UI equivalent ('与活动中心的「领取」按钮相同'). It also distinguishes itself from the sibling task_bind by describing the sequence in which binding becomes possible only after receiving.

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 hard precondition — only tasks in WAIT_RECEIVE status can be claimed and others are rejected outright — and names the follow-up step (re-run tasks_list, then task_bind). It does not explicitly say which sibling to use if the task is in another status, so an agent must infer the alternative, keeping this below 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?

With no annotations supplied, the description carries the full burden and does substantial work: it enumerates the returned fields per kind, explains that media come back as short references (*_ref / *_refs like img:12) that are only valid for the lifetime of this MCP server run, and notes that image_view resolves them. It never explicitly states that this is a side-effect-free read operation, nor does it mention result totals or what happens at the end of the list — minor but real gaps for a tool with zero annotation coverage.

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 structure is front-loaded and purposeful: purpose and pagination first, then a per-kind breakdown, then the follow-up tool chain, then reference-handling semantics. All four paragraphs earn their place, though the field enumeration per kind is dense enough that an agent must parse a long run-on clause rather than scan a 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?

There is no output schema, so the description must describe return values — and it does, per kind, plus the ref-resolution rule and the follow-up tool chain. For a five-parameter, two-variant list tool this is nearly complete; only end-of-list/total-count behavior and the instance_id vs project_path resolution are left unaddressed in prose.

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 every parameter is already documented, and most description text (offset default 0, next_offset usage, count default 20) merely restates that. The one genuine addition is expanding what kind=effect versus kind=growth actually returns, which helps the agent pick a value, but instance_id/project_path — including the fallback when only one project window is open — are left entirely to the schema. This is the correct baseline-3 case where 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 opens with a concrete verb+resource+scope: paginated listing of activity-center tasks via offset/count. It immediately splits the result set by the `kind` enum, stating what each variant contains (effect: title/status/received flag/remaining days/revenue/schedule/claim counts; growth: reward amount and reference project), so an agent can distinguish it from task_detail, task_receive, task_bind and growth_route without opening any schema.

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

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

It gives a clear downstream routing chain — obtain task_id here, then use task_detail for details, task_receive to claim, task_bind to bind (only when bindable=true) — and states that kind=effect is the default while kind=growth targets growth tasks. What it does not do is say when to skip this tool entirely (e.g., if you already have a task_id, or when growth_route already supplies level/progress), so exclusions are 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 burden and does so: it enumerates the three per-effect outcomes (found / same_name / not_on_homepage) with precise meanings, and explicitly warns that same_name is a different effect_id and must not be treated as the same effect. It also discloses cost (one to two requests per effect, about 6 seconds for 20), which fields are usable downstream (template_id), and the critical lifetime constraint that image/video/audio refs are only valid for the duration of this MCP run.

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 and the outcome enumeration are front-loaded, and the operational notes (cost, ref lifetime) are pushed to the end where an agent can skim them. Sentences are dense rather than padded, though the closing paragraph about *_ref handles and image_view is a slight tangent relative to the core lookup and could have been one clause shorter.

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 must explain returns, and it does: status semantics per effect, that found and same_name works appear in items with works_list-compatible fields, that template_id feeds works_download / works_open, and how media refs are encoded and consumed via image_view. For a four-parameter, batched, no-output-schema tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema does not: it justifies the category_id default (推荐 is the only category that reliably resolves ID lookups across categories) and explains the batch bound in domain terms (max 20 = one rank page) plus what the optional name field enables (same-name fallback). It adds context beyond the field-level descriptions rather than repeating them.

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

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

The description opens with a specific verb and resource: look up whether the homepage has a project (工程) for a given effect ID, and states it is the same backend as the homepage search box's 特效ID search. It also names the upstream sources of the ID (rank_list / rank_subjects / rank_innovation effect_id) and the downstream consumers (works_download / works_open via template_id), so an agent can position it against siblings without opening other schemas.

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 default (query in 推荐, so category_id is usually unnecessary) and explains why: querying by ID in 推荐 also finds works that only appear in other categories, whereas querying by ID in another category can miss them. That is actionable when-to guidance plus a concrete exclusion. It stops short of naming a specific sibling as an alternative (e.g. works_search or effect_check), so it is not a full when/when-not/alternatives statement.

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 whole burden and does so well: it discloses that this is a destructive file removal, that only registered download paths are accepted and all others are refused, and that items open in the editor are skipped and reported in kept_open. The main omission is that irreversibility (no trash/undo) is only implied by the verb, not stated.

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

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

Three tight sentences, front-loaded with the scope of deletion, then the omit-paths default, then the open-window caveat and retry instruction. Dense but every sentence carries operational content; only the parenthetical directory detail borders on redundant.

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 destructive, single-parameter tool with no annotations and no output schema, the definition covers scope, refusal of unregistered paths, the bulk-delete default, and the kept_open return field an agent must inspect. What's missing is only the reversibility/permission story, which is a modest gap given how much else is specified.

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 single paths parameter is fully documented in the schema, including its provenance (works_download/works_open project_path) and the omit-means-all behavior. The description restates that same semantics rather than adding new meaning, so the 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 (删除/delete) and a precisely bounded resource: project works downloaded via works_download/works_open, including the app temp directory and dest copies. It names the sibling tools that produce those artifacts and scopes deletion to registered downloads only, which lets an agent separate it from generic siblings like resource_delete_unused or project_close 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?

Gives concrete operating guidance: omit paths to delete everything, and if an editor window is open the item is preserved and returned in kept_open, so re-call after closing the window. That covers the main decision points and the retry path, though it doesn't explicitly contrast with resource_delete_unused or state what to do for paths outside the registry beyond 'rejected'.

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: dest must not exist or be empty, Library cache is skipped, the temp copy is deleted afterwards, downloads are registered and auto-deleted after a 24-hour expires_at on the next download. It also discloses the return payload, a directory plus a files list of relative paths and sizes. That is unusually complete behavior disclosure for a mutating file-producing 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?

It is one dense paragraph, front-loaded with the action and return value, then destination semantics, lifecycle, alternatives, and licensing. Every clause earns its place, though the parenthetical explaining what to read inside the project is slightly 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?

For a four-parameter tool with no output schema, no annotations, and a file-system side effect, the description covers return shape, cleanup lifecycle, destination preconditions, sibling routing, and licensing constraints. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the preconditions on dest (must not exist or be empty, Library cache skipped) and the consequence of omitting it (the project stays in the temp directory). That is real added value rather than repetition.

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

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

The description opens with a specific verb and resource: download a complete project for a homepage work and unzip it. It immediately names the sibling it is not (works_open) for viewing in the editor, so an agent can distinguish the two without opening either schema.

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

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

It gives explicit routing: use works_open if you want to see the effect in the editor, and call works_cleanup immediately after you finish learning. It also states the acquisition path (template_id from works_list / works_search / works_by_effect) and the licensing restriction against copying into your own project.

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 so well: it discloses cursor-based pagination (next_cursor, null on last page), that each work may have null effect_id/publish_count, that a project window must be open, and, importantly, that *_ref references are only valid for the lifetime of the current MCP service run. It does not state that the operation is read-only, or describe any rate or size limits.

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 purpose is front-loaded in the first sentence, and the workflow handoff and reference-lifetime note follow in a logical order. The final paragraph on *_ref short references is somewhat generic, but it is still load-bearing because it tells the agent to route them through image_view.

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 must describe the return shape, and it does: template_id, title, tags, effect_id/publish_count with null handling, usage count, package size, cover_ref and gif_ref, plus pagination cursor semantics. Given six all-optional parameters and no annotations, this is close to complete; only explicit read-only and permission expectations are missing.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema, which sets the baseline at 3. The description reinforces that category_id values come from the categories list returned by this tool and that instance_id/project_path can be omitted when only one project window is open, but it adds little beyond the schema 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 description opens with a specific verb and resource: paginated listing of works under one category of the Xiangsu homepage Templates section, and it explains what those works are (complete official/user-submitted projects). That is enough for an agent to distinguish it from siblings such as works_search, works_by_effect, and works_download.

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 a concrete workflow handoff: once you have a template_id, use works_download to download the project, and it says to always pass all returned categories. However, it never explicitly contrasts this tool with works_search or works_by_effect, so the choice among the listing/search siblings is left to inference.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that no version-upgrade prompt appears, the project is left unsaved, the return payload (window pid, official instance_id, project directory), and the important constraint that the project cannot be deleted while the window is open.

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?

Purpose is front-loaded, then the workflow and cleanup sequence follow in a logical order. It is dense but nearly every clause carries operational information; only the closing cleanup sentence is slightly 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?

There is no output schema, but the description explicitly enumerates the return values and the required teardown steps, so an agent knows both what it gets back and how to clean up. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents template_id, instance_id, and project_path including the either/or relationship. The description adds no parameter-level detail beyond what the schema provides, so the 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 ('下载一个首页作品并在新的编辑器窗口里打开') and pins down the exact semantics by equating it to clicking a work on the homepage. This distinguishes it from siblings like project_open (existing project) and works_download (download only).

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 a full lifecycle: open, observe with get_scene/capture_preview, close with project_close(discard_changes=true), then works_cleanup. That is clear when-to-use and follow-up guidance, though it never explicitly contrasts with project_open or works_download as 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?

With no annotations supplied, the description carries the full behavioral burden and does so unusually well: it discloses the ~300-item cap per category, the merge ordering, 10-minute result caching so paging doesn't re-request, the server-side stuck-page failure surfaced as `incomplete`, and the lifetime of short refs (valid only for this MCP service run) plus how to resolve them via image_view. These are exactly the non-obvious traits an agent needs before calling.

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

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

The description is dense but front-loaded: purpose first, then the no-category behavior, then pagination/caching caveats, then sibling routing, then ref handling. Nearly every clause carries a distinct operational fact, though the merge-order and 300-cap detail could be tightened without losing meaning.

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

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

For an 8-parameter, annotation-free search tool with no output schema, the description compensates by naming the returned fields (found_in, total, by_category, matched_queries, incomplete, *_ref refs) and the pagination contract. Nothing an agent needs in order to call it correctly or interpret its results is missing.

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

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

Schema coverage is 100%, so the schema already documents each parameter; the description still adds real meaning beyond it, notably the consequence of omitting category_id (search-all with dedupe), the 8-term cap on queries and the matched_queries annotation returned per item, and that offset/count paging is served from cache. Only instance_id and project_path are left entirely to the schema.

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

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

The opening clause states a specific verb and resource ("按作品名搜索首页作品") and pins the exact backend semantics ("与首页搜索框同一个接口"). It also differentiates from siblings by naming works_by_effect for effect-ID lookups and by deferring field semantics to works_list, so an agent can choose among the three without opening any schema.

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

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

It gives explicit conditions: omit category_id to search all categories with merge/dedupe, use queries for up to 8 terms, and use works_by_effect when searching by effect ID. What it doesn't spell out is when to prefer works_search over works_list or library_search for a plain browse, leaving that routing to inference from "其余字段同 works_list".

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