canvas-mcp

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

Despite annotations already covering the safety profile, the description adds substantial context beyond them: credits are deducted from the tenant owner's balance for paid actions (5 for gen_report, 2 for run_detection), no charge on failure, and same-key calls return cached results without re-charging. It also discloses the two return shapes (sync data vs job+jobId/pollSec) and the auth rule for public vs owned tenants.

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 purpose and required params, then cost, caching, orchestration and examples. Information-dense with no filler, though it packs several distinct concerns (params, pricing, retry, auth, examples) into one long paragraph that could be broken up.

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 the return contract (sync vs job modes with fields), cost semantics, caching/retry, auth boundaries and a worked public-tenant example. Given the nested params object and mutation semantics, nothing essential is left to inference.

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 80% (baseline 3), and the description adds meaning by stating slug/action are required, pointing params at list_actions' JSON Schema, and explaining why session_id would be set ('想让结果落在某次会话里') and that hostUserId is optional. It does not add format/syntax detail beyond that, so it stops short of 5.

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 ('执行一个岗位动作') and immediately enumerates concrete action families (preflight / list_checks / gen_report / run_detection / resolve_user). It also contrasts the tool against siblings (list_actions for schemas, get_job for polling, open_canvas for sessions), so an agent can distinguish it without opening other 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?

Gives an explicit orchestration recipe (list_actions → preflight → gen_report → get_job → narrate), states the public-tenant rule and the 403 condition for non-owners, and tells the agent when retrying is safe. When-to-use, when-it-fails, and the alternative tools are all named.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: the queued/running/done/failed state machine, that done carries a result and failed carries an error, and an explicit error-handling policy (relay the message verbatim, do not paraphrase as 'system busy', do not retry). That is real operational context, not restated structured data.

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, front-loaded, and waste-free: the resource and its states come first, then cadence, then the error-handling rule. Every clause carries a distinct instruction an agent must follow.

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

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

With no output schema, the description correctly takes on the burden of describing return shape by naming the four states and what done/failed carry. It stops short of describing the payload of result or how a job_id is first obtained, but for a single-parameter polling tool it is close to complete.

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

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

Schema coverage is 0% and job_id has no description, so the only parameter semantics come from the description's '按 job_id 查', which essentially restates the parameter name. With just one self-explanatory required parameter this is minimally adequate, but nothing explains where the job_id comes from or its expected format.

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 (查长任务 by job_id) and enumerates the four terminal/intermediate states it can return, which no sibling tool covers. An agent can distinguish this polling tool from list_sessions, get_stats, or query_events 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 concrete operating guidance: poll every 3 seconds, and explicitly do not retry with the same parameters when an error is returned. It lacks a named alternative or a when-not-to-call-this condition, but the polling cadence and no-retry rule are the practical guidance an agent actually needs here.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered. The description adds meaningful context beyond that: the explicit auth parameter semantics, the privacy boundary limiting reads to one's own role, and the fact that AI replies include token counts. It omits anything about log size, pagination, or truncation behavior for potentially large sessions.

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 that front-loads what the tool returns, then parameters, then prerequisites, then access limits. Every clause carries information (contents, params, source of session_id, privacy, auth), with no filler or repetition.

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

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

With no output schema, the description carries the burden of explaining return content and does so by enumerating the record types. Auth and privacy constraints are covered. The main remaining gap is volume/pagination behavior for a full session log, which an agent might need to handle large sessions.

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

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

Schema coverage is 0% and both parameters are undocumented in the schema, so the description must compensate. It states both are required, explains slug as the explicit auth handle, and tells the agent where a valid session_id comes from — enough to invoke correctly despite the bare 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 (retrieve a single session's full chronological log) and enumerates exactly what the stream contains: user messages, AI replies with tokens, tracking events, action calls, screen pushes. It distinguishes itself from the sibling list_sessions by describing a per-session detail dump rather than a listing.

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 concrete prerequisite: obtain a valid session_id from list_sessions or open_canvas before calling. It also states the access condition (only your own role's records; valid Key required, anonymous not enabled). It does not explicitly say when NOT to use this tool versus list_sessions for bulk inspection, so it falls short of a full when/when-not routing 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?

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower. The description adds real value: it discloses that llmMode only reports BYOK status and never returns the key, which is a security-relevant disclosure not captured by 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?

Front-loads purpose, then the returned-field inventory, then the parameter, then the read-before-write rationale. Dense but every clause carries information; the enumerated field list is long but functional.

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 purpose, returned fields, the single parameter, and the workflow warning. For a 1-param read tool with annotations and no output schema, this is largely complete; only slug provenance is 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?

Schema coverage is 0% and the only schema info is the slug type, so the description's 'slug 必填' is the sole semantic hint. It confirms requiredness but adds nothing about slug format or where the value comes from, leaving the parameter under-specified.

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 (读岗位配置) and enumerates exactly which config fields are returned, which is more than a tautology. It is distinguishable from sibling list_my_staff (enumerating staff) and patch_staff_config (mutating config), though it doesn't name 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?

Gives a clear imperative '改之前先读' with the concrete consequence of skipping it (overwriting the customer-tuned version with a guessed persona). Implies patch_staff_config as the follow-up mutation but doesn't name it explicitly.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral facts beyond them: a valid Key is required, anonymous access is refused, and the default window is the last 30 days when from/to are omitted.

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 aggregate and its metrics, then parameters, then usage trigger, then auth requirement. Three compact clauses with no filler; every sentence contributes information the agent needs.

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

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

With no output schema, the description compensates by listing the returned metrics and the daily curve. Auth, defaults, and required fields are all stated. It is complete enough to invoke correctly, with only the slug identifier's exact form unspecified.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning and largely does: slug is required, from/to are ISO timestamps, and the default range is 30 days. It leaves ambiguous what slug actually identifies (job id vs. name), which is a minor residual gap.

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

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

Names a specific resource (岗位) and operation (一段时间汇总) and enumerates the exact metrics returned: 会话数、真人对话轮数、埋点数、动作调用数、tokens、按日曲线. This clearly separates it from siblings like get_session_log or list_sessions, which return records rather than aggregates.

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 trigger ('用户问这岗位最近怎么样/今天多少人来就用它') plus a negative instruction not to infer numbers from chat history, which steers the agent away from a plausible wrong behavior. It does not name an alternative tool for adjacent needs, so it stops short of 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?

Adds substantial behavior beyond annotations: return values (slug, canvasUrl, actual kbs), cost model (free trial then monthly Token deduction, per-conversation charge), requirement to confirm with user, account limit and error behavior, and that invalid kbs names are silently ignored. Annotations already declare readOnlyHint=false and destructiveHint=false, and the description is consistent with them.

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

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

Front-loaded with purpose, then parameters, returns, cost, and limits. Every sentence carries operational value; no redundant restatement of the name or title.

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, but the description explains the key return fields. It covers cost, confirmation, error conditions, and parameter sourcing, so an agent has enough to invoke the tool correctly given the annotations and schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: templateId must be from list_templates canOpen=true with a concrete example, name is what customers see, and kbs must be published under the user's name or will be ignored. It does not add format or validation details beyond the schema for all parameters.

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

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

States a specific verb and resource: opening a new digital employee position (开一个新的数字员工岗位). The word 'new' distinguishes it from sibling update/config tools like patch_staff_config, and the return values clarify what the operation produces.

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 clear prerequisites and conditions: templateId must come from list_templates where canOpen=true, the user must be asked to confirm before opening, and account limits trigger an error requiring cleanup. It does not explicitly name when-not-to-use or an alternative sibling tool for modifying existing staff.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile needs no restatement. The description adds real behavior context: the returned 'params' is a JSON Schema that must be used to fill canvas_action, and action sets vary per job. It stays silent on pagination or failure modes, but for a small read-only lookup that is a minor gap.

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

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

One dense sentence of output shape followed by the parameter note and the routing instruction, all front-loaded with zero filler. Every clause earns its place.

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

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

For a one-parameter read-only list tool with no output schema, the description covers the return payload, the required input, and the handoff to canvas_action. The only omission is clarifying what the slug refers to, which the sibling tools imply but never state.

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

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

Schema coverage is 0%, so the description must carry the parameter meaning; it states 'slug is required' but adds nothing about what the slug identifies (the job/template) or its format. This only partially compensates for the empty schema, leaving the meaning of the one input to inference.

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 ('list the actions this job can do') and enumerates the returned fields (id/title/description/cost/credits/anonymous/job/params), so an agent knows exactly what comes back. It also implicitly separates itself from canvas_action, which executes actions rather than listing 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?

Explicitly instructs to call this before canvas_action and warns against guessing action names because action sets differ per job template. That is a concrete when-to-use plus a when-not-to-do-something-else rule naming the sibling.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: the priority rule for workspace-owned vs referenced KBs and the instruction to surface both when sources conflict, plus the semantic note that KBs are the grounding source for digital-employee answers.

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 enumeration is front-loaded, but the main sentence is overloaded, stringing three result categories together with nested parentheticals before any usage guidance arrives. The closing sentence about KBs being the basis for digital-employee answers is useful framing but sits after the operative instructions rather than before them.

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 carries the burden of describing returns and does so field-by-field across all four result groups. The one gap is pagination: '每页的 path 与标题' implies paged results but the description never explains page size or how to page through them.

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

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

The tool takes zero parameters, so the rubric baseline is 4. The description correctly describes the shape of the result (which fields appear per KB, ownerKey/ref for shared and workspace entries) rather than inventing input arguments, which is the right use of space for a no-param tool.

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

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

The description gives a precise verb (列出) and enumerates exactly which resources are returned: the user's published KBs (name/version/publish time/article count/path/title), each job's configured KBs, plus workspaces and shared KBs with ownerKey and ref. It is clearly distinguishable in practice from read_kb and set_staff_kbs, but it never names a sibling or states what it is not, so it falls short of the 5 bar.

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 invocation triggers ('用户问"我有哪些知识库""这个岗位用的什么资料"时用') and an operational rule for ambiguous situations ('在某个工作区里干活时，优先读那个工作区的库和它引用的库，说法冲突时都列出来'). An agent knows both when to call it and how to resolve conflicting results without inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds a genuinely behavioral fact beyond them: this call is the canonical provenance of slug values for all later operations. It omits pagination/volume behavior, 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: what it returns, when to call it, and the slug-provenance rule. Nothing is wasted and the return-field list 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?

With no input params and no output schema, the description carries the return-shape information itself by naming the four fields, and the slug rule covers the cross-tool contract. 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?

Zero parameters, so the baseline is 4. The description reinforces this explicitly with "参数：无", leaving no ambiguity that the tool takes no arguments.

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

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

States a specific verb and resource (列出我名下的数字员工岗位) and enumerates the returned fields (slug / 名称 / 模板 / 画布链接), which cleanly separates it from siblings like get_job, list_templates, and get_staff_config.

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 trigger (用户问"我有哪些岗位"用它) plus a hard workflow rule: every downstream per-staff tool needs a slug and the slug must be taken from here rather than reconstructed from memory. That is when-to-use plus a concrete dependency chain.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds real context beyond them: sort order, the returned field set, the auth requirement ('需要有效 Key，匿名不开'), and the cursor pagination contract (pass the nextCursor from the previous page).

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 organized: purpose and returned fields are front-loaded, then parameters, then the usage trigger and auth note. Every clause carries information, though the parameter list is compressed into semicolon fragments rather than fully unpacked.

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

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

With no output schema, the description usefully enumerates returned fields and explains pagination and the auth gate, which is what an agent needs to call it correctly. Remaining gaps are the from/to format and limit bounds, both minor for a read-only list tool.

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

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

Schema description coverage is 0%, so the description must carry the load. It explains slug (required), q (fuzzy search on host user identifier), and cursor (pass the prior page's nextCursor), but only bare-mentions from/to and limit without stating format, date semantics, or the limit ceiling (max 200).

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

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

States a specific verb and resource (访客会话列表 for a 岗位), the sort order (最近优先), and enumerates the returned fields (session_id、宿主用户标识、轮数、时间). It implicitly routes detail-lookup to a separate tool via '再拿 session_id 看明细', distinguishing it from get_session_log.

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 concrete when-to-use trigger ('想看最近都服务了哪些人用它') and the follow-up step of taking session_id to a detail tool, plus the prerequisite that a valid Key is required and anonymous access is disabled. It stops short of naming the sibling tool explicitly, leaving the routing slightly implicit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description focuses on domain behavior instead: it enumerates the returned fields and, crucially, explains that canOpen=false means the template lacks implementation and must not be recommended. That missingHandlers/canOpen semantics is exactly the kind of business rule annotations cannot express. It stops short of a perfect 5 only because it says nothing about auth or result size ordering.

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

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

Four tight clauses, each with a distinct job: purpose, usage trigger, return shape, anti-pattern plus caveat. Purpose and the routing warning are front-loaded, and nothing is repeated from the schema or annotations.

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

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

With no output schema present, the description compensates by listing the exact return fields (templateId/名称/说明/canOpen/missingHandlers/动作清单) and the interpretation of canOpen=false. Purpose, usage, returns, and caveats are all covered for a zero-parameter list tool.

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

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

Zero parameters, so the baseline is 4; the description explicitly confirms '参数：无', matching the empty schema and removing any doubt that a filter might exist. There is no additional parameter meaning to add.

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 (列出数字员工模板) and immediately scopes it as the catalog of *provisionable* templates, explicitly distinguishing it from list_my_staff which holds already-provisioned staff. An agent can route between 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?

States both when to use it ('想知道系统能开哪些岗位'、用户要开通新岗位时) and when not to ('别用它找已开好的岗位——那是 list_my_staff'), naming the alternative outright. This is the full when/when-not/alternative triad.

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

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

Annotations only declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false); the description adds substantive context the annotations cannot convey — that the session is already live on return, that push_screen can pre-stage cards for users who haven't arrived, that offline re-push occurs on link open, and that hostUserId governs session ownership. Auth requirements and failure modes are still unstated.

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 front-loaded: purpose first, then parameters, then return value and lifecycle implications. Every clause carries information, though the run-on parameter paragraph could be split for faster scanning.

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

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

Covers the return shape ({url, session_id}) even though no output schema exists, and explains the session lifecycle and downstream consumers. For a four-parameter mutation tool with annotations already covering the safety profile, little is missing apart from error/edge-case behavior.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: hostUserId is flagged as '强烈建议带' because session ownership and offline re-push depend on it, and targetId is framed as a care/business object. That dependency rationale is not present in 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?

States a specific verb+resource pair ('为岗位生成画布链接 + 会话 ID') that no sibling duplicates, and immediately scopes it with the user-facing scenario ('看得见的界面'). An agent can distinguish this from canvas_action, get_session_log, or push_screen 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 a clear trigger condition ('用户需要看得见的界面：看报告/看商品/做检测') and names the downstream siblings that consume its output (get_session_log / push_screen). It lacks an explicit 'when not to use' or a named alternative for the same task, so it stops short of a 5.

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

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

Annotations already flag destructiveHint=true, idempotentHint=true, and readOnlyHint=false, but the description adds crucial context beyond them: writes affect the customer's staff config and take effect immediately, and it warns to confirm user intent first. This is exactly the kind of operational nuance annotations can't convey.

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

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

The content is valuable but densely packed into one long run-on sentence with inline parentheses that is hard to parse. It is front-loaded and no sentence is wasted, but the structure could be cleaner with the schema doing more of the field enumeration.

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 2-param partial-update mutation with no output schema, the description covers the fields, the required params, the immediate-effect behavior, and the confirmation guidance. What remains missing is return behavior, though the absent output schema somewhat lowers that burden.

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

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

With only 50% schema coverage and a free-form patch object, the schema alone is nearly useless. The description compensates heavily by enumerating every patchable field, its structure, and sub-keys, and confirms both slug and patch are required. It loses a point only because some nested field semantics (e.g., promotionConfig defaults) remain implicit.

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 (局部修改/patch) and resource (岗位配置), and the description enumerates the exact patchable field structure. An agent can distinguish this from get_staff_config and set_staff_kbs 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 clear usage context: 'patch 只放要改的字段' constrains partial updates, and points to the set_staff_kbs alternative for the kbs field. It also advises reciting the change back before calling when unsure. No explicit when-not-to-use, but the context is strong.

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?

Even though annotations already flag destructiveHint=true and idempotentHint=true, the description adds substantial context: same-name republish is a whole-library replacement, checked must be true, hard limits (200 files / 64KB each / 2MB total), publication is public, and the 'verified-pages-only' mode makes new/edited pages pending review that the caller cannot self-approve. This is far beyond what the annotations convey.

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

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

The purpose is front-loaded and almost every sentence carries operational value (index format, media fence, digit/date rules, privacy). It is dense and presented as one long paragraph with inline rule markers rather than scannable sections, which slightly hurts structure but the length is justified by the tool's complexity.

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 write tool with no output schema, the description covers everything needed to call it correctly: directory conventions, per-page naming/size guidance, the kb-media fence grammar, byte/file limits, privacy constraints, verification behavior, and the user-confirmation step. No material gap remains.

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 genuinely useful gotcha for files: it is an array of {path, content}, not a {path: content} object, backed by a concrete JSON example. Owner/slug/name semantics are already fully in the schema, so the marginal value is limited to the format warning.

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+resource: '把一套整理好的 Markdown 发布成知识库', and immediately distinguishes three publication targets (my own name, a role via slug, a workspace via owner=ws:<id>). This clearly separates it from read_kb and list_kbs, which read rather than publish.

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 when-to-use context and alternatives: before re-publishing under the same name, '更新前先 read_kb 把现有页面读回来合并', and it instructs confirming the library name and role assignment with the user beforehand. Nothing about routing or preconditions 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?

Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false); the description adds real behavioral detail absent from them: online sessions display immediately, offline or never-opened sessions are queued as pending and auto-pushed on the next open by that session or same-position/same-hostUserId. Auth requirements and session-vs-person ownership semantics are also disclosed.

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 required params are front-loaded, and every clause carries information; the trade-off is a single dense semicolon-chained block rather than clearly separated sections.

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

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

No output schema exists, so the description must carry behavior, prerequisites and delivery semantics — and it does, including the offline queue and the cross-tool boundary with canvas_action. 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?

With only 50% schema description coverage, the description compensates well: it names where session_id comes from (open_canvas or list_sessions) and explains content's fence syntax (canvas-md / canvas-html / canvas / subtitle text) plus the speak flag. Only 'title' is left unexplained.

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 (push content to a canvas session's screen) and immediately distinguishes scope from siblings by naming canvas_action for side-effecting work. An agent can tell what this tool owns 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?

Explicit routing: use push_screen for display content, use canvas_action for actions with side effects (reports/checks). Also gives a prerequisite (valid Key, no anonymous use) and an ownership rule (never reuse someone else's session_id).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new context: descending order, an explicit auth requirement (valid Key required, anonymous disabled), and the per-event source field (mcp/page/server) plus payload shapes for action_call and push. This goes beyond what the annotations provide.

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

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

Dense but well-front-loaded: purpose first, then parameters, then return-shape and auth details. Every clause carries information (enum values, bounds, payload fields) with little waste, though the single run-on paragraph is heavy.

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 carry return-value context and does so reasonably: it explains the descending ordering, the source attribution field, and the payload contents for action_call and push. Auth and required params are covered, leaving only minor gaps like pagination and date format.

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

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

Schema description coverage is 0%, so the description carries the full burden and largely does: slug is marked required, type/from-to/limit are listed, limit's bound (≤500) is stated, and the type enum values are enumerated. The only gap is the format of from/to (string timestamps), which is left unspecified.

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 with scope: pull events by type across sessions in descending order, and enumerates the type values (chat_user / chat_assistant / track / action_call / page_open / push). The cross-session scope implicitly distinguishes it from get_session_log, but no sibling is named explicitly, so it falls short of a 5.

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

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

The description implies its use case by highlighting the billing/troubleshooting evidence chain in action_call payloads, which hints at diagnostic usage. However, it never states when to pick this over get_session_log, list_actions, or get_stats, leaving the routing to inference.

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

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

Annotations already cover readOnly, idempotent and non-destructive, so the bar is lower. The description still adds real behavioral context beyond them: the owner-scoping rule for non-owned KBs and the crucial workflow constraint that publish_kb is a full replacement where omitted pages disappear. It stops short of describing pagination or size limits on returned content.

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 parameter semantics, with no filler sentences. It is dense in a single block, which slightly hurts scannability, but every clause (alias note, owner rule, publish_kb warning) carries information an agent needs.

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

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

For a 5-parameter, zero-required, alias-heavy read tool with no output schema, the description covers return content ('版本和页面清单', '那一页的原文'), scoping rules, and the update-safety workflow. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100% (baseline 3), and the description still adds value by specifying which parameters combine in which case (name only vs name+page vs plus owner) and by tying owner to the ownerKey value shape from list_kbs. The alias parameters path/kbName are left 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?

States a specific verb+resource ('读一个知识库') and immediately differentiates it from siblings by explaining that name alone returns version+page list and name+page returns page content, contrasting with publish_kb. An agent can tell read_kb apart from list_kbs and publish_kb without opening a 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 conditional usage: pass only name for the manifest, add page for raw content, add owner for workspace/shared KBs, and read existing pages before updating because publish_kb replaces the whole KB. This is a complete when/how/alternative-avoidance guide.

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

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

Annotations already declare destructive=true, idempotent=true, readOnly=false, openWorld=false, so the safety profile is covered. The description adds real value beyond that: it clarifies that the operation replaces the entire existing assignment, that non-conforming KBs are dropped rather than erroring (reported via kbDropped), and that changes take effect immediately. It does not contradict any annotation.

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

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

Front-loads the core action and replacement semantics, then packs parameter grammar, drop behavior, and effect timing into a single dense paragraph. Every clause carries information, though the parentheticals and multiple semicolon-separated clauses make it slightly heavy.

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 2-parameter mutation tool with no output schema, the description covers the essentials: value format, authorization prerequisite, [] semantics, dropped-entry feedback (kbDropped), and immediate effect. It omits what happens on an invalid slug or an overall error/return shape, which is a minor gap given annotations already carry the destructive/idempotent profile.

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

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

With only 50% schema coverage (slug has no schema description), the description compensates well: it marks slug as required and, more importantly, defines the value grammar for kbs — bare library name for owned KBs, list_kbs ref (e.g. ws:xxx/库名) for workspace/shared KBs — plus the [] empty-list semantics. Only minor detail on slug validation is absent.

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 adds the critical scope qualifier 整体替换 (full replacement), which is not covered by the title alone. This is functionally distinct from every sibling (list_kbs, publish_kb, read_kb, get_staff_config), so an agent can identify 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?

Gives concrete usage conditions: how to format each kbs entry (bare name for own KBs vs. list_kbs ref for workspace/shared KBs), that [] means no KBs, and that unauthorized shared KBs are silently ignored. It references list_kbs as the source of refs but never states explicitly when to prefer this tool over patch_staff_config or get_staff_config for staff configuration.

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