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?

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 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 declare destructiveHint=true and idempotentHint=true; the description adds material context beyond them — that this edits a *customer's* job config (cross-tenant impact), that changes take effect immediately, and that confirmation is advised when intent is uncertain. No contradiction, though it omits rollback/reversibility details.

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 verb and scope, then the field list, then required params, then the caution. The dense enumeration is information-dense rather than padded; every clause carries calling-relevant content.

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 nested mutation tool with no output schema, it covers field semantics, required params, write/immediacy semantics, and a confirmation heuristic. Minor gaps remain around the slug identifier's format and error/return behavior, which the missing output schema shifts onto the description.

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 50% (patch described generically as '要改的字段', slug undocumented), but the description compensates by listing allowed keys with shapes and inline enum options (layoutStyle split|pip|classic, contextMode inline|webhook). Only slug's meaning 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?

Names the exact operation (局部修改岗位配置) and enumerates every patchable field, so the agent knows precisely what this mutates. It is clearly distinguished from read siblings like 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?

Explicitly states patch should contain only fields to change, priming partial-update semantics, and adds a genuine operational guardrail ('if unsure the user really wants it, restate first'). It never names the read alternative (get_staff_config) for verification, so it stops short of full when/when-not 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?

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.