canvas-mcp

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

With no annotations provided, the description carries the full burden and delivers: credit cost per action (5 for report, 2 for detection), that failures are not charged, that repeated same-key calls return cached results without double-charging, and the two response modes (sync data vs job jobId/pollSec).

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 shape, then cost/retry semantics, then orchestration. Every sentence carries information, though the parameter run-on could be tightened.

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

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

For a complex nested-param tool with no output schema, the description fully compensates by explaining the two return-shape modes, how to poll job results, cost implications, and the recommended call sequence.

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), but the description adds meaning beyond the schema by cross-referencing list_actions' JSON Schema for params and clarifying that session_id attaches the action record to an open_canvas session and hostUserId is the host identifier.

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 concrete actions (preflight / list_checks / gen_report / run_detection / resolve_user), making it clearly distinguishable from siblings like list_actions and get_job which it references by name.

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?

Provides an explicit orchestration flow (list_actions → canvas_action(preflight) → canvas_action(gen_report) → get_job), names the alternative tools for discovery and polling, and even clarifies safe retry conditions, leaving little to inference.

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

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

With no annotations, the description carries the full burden and delivers genuinely non-obvious behavior: the state machine, poll cadence, that error values are human-readable and should be relayed verbatim, and that same-parameter retries are futile. Gaps remain (no auth/permission notes, no TTL or invalid-id behavior), but this is well above the annotation-free baseline.

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 verb and state enumeration, then the operational rules. Every clause earns its place; 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 usefully covers return semantics (done carries result, failed carries error) and polling/error-handling rules, which is most of what an agent needs. It omits where job_id originates and the shape of result/error payloads, leaving a small gap.

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

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

Schema coverage is 0% for the single job_id parameter, and the description only restates its function ('by job_id') without format, origin, or where the id comes from (presumably a prior task-triggering call). The name is fairly self-explanatory, so this is minimally adequate rather than compensating for the coverage gap.

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

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

States a specific verb and resource (query a long task by job_id) and enumerates the full state model it can return: queued / running / done(with result) / failed(with error). An agent knows exactly what the tool does and what each outcome means without opening any schema. No sibling tool queries jobs, so no differentiation is needed.

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 operational guidance: poll every 3 seconds, and do not retry with the same parameters. This tells the agent how to use the tool in a loop. It stops short of naming when not to call it or referencing an alternative tool, so it is clear context rather than a full when/when-not routing rule.

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

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

With no annotations, the description carries the full burden and does disclose meaningful traits: requires a valid Key, anonymous access is disabled, only records for the caller's own role/position are readable, and slug provides explicit authorization. It does not cover pagination or error behavior, but the auth and privacy disclosures are substantive.

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 before moving to parameters, prerequisites, and constraints. Every clause adds information, though the run-on structure with multiple colons makes it slightly harder to scan.

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

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

For a read tool with no output schema and 0% parameter coverage, the description supplies purpose, return contents, parameter roles, prerequisites, auth, and privacy boundaries. Only the return format/pagination is unaddressed, which is a minor gap given the enumerated content types.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: both params are declared required, slug is explained as the explicit-auth credential, and session_id is explained as an identifier sourced from list_sessions/open_canvas. This adds real meaning beyond the bare string types in the schema.

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

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

States a specific verb+resource (retrieve a single session's complete chronological log) and enumerates the content types returned (user messages, AI replies with tokens, tracking events, action calls, screen pushes). This clearly distinguishes it from list_sessions, which is named as the source of session_id rather than as an alternative.

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 tells the agent to obtain a valid session_id from list_sessions or open_canvas before calling, and states the auth/privacy preconditions. It gives strong context but stops short of a formal when-not/alternative clause (e.g., 'for multiple sessions use list_sessions').

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses returned fields and that llmMode only reveals BYOK status without the key, but it does not state permission requirements, side-effect-free read behavior, or any rate/limit context.

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 purpose, then details fields, the parameter, and the key warning in a compact package. The long parenthetical field list is dense but every element is relevant, with little wasted text.

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 helpfully enumerates returned configuration fields, and the pre-modification warning adds important operational context. It is nearly complete for a simple read tool, though slug semantics and permission requirements remain 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 description coverage is 0%, so the description must compensate. It only says 'slug 必填,' which merely repeats the schema's required list and does not explain what a slug identifies, its format, or where to obtain it.

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

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

States a specific verb and resource ('读岗位配置') and enumerates exactly what configuration fields are read, distinguishing it from the mutation sibling patch_staff_config. An agent can tell what this tool returns without opening the schema.

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

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

Explicitly says to read before modifying, and explains the consequence of not doing so ('会用想当然的人设覆盖客户调过的版本'). This gives clear context for when to use it, though it does not name patch_staff_config directly as the alternative.

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

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

With no annotations, the description carries the full burden and does disclose two real behavioral facts: a valid Key is required and anonymous access is disabled, plus the default 30-day window when from/to are omitted. It stops short of stating read-only semantics, pagination/limits, or error behavior.

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

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

Three sentences, front-loaded with the returned metrics, then parameters, then usage routing. Every clause earns its place with no restatement of the tool 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?

There is no output schema, so the description enumerates the returned metrics itself, and it covers the auth requirement and default time window. For a 3-parameter read tool this leaves no material gap an agent needs before calling it.

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

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

Schema coverage is 0%, so the description must compensate, and it does: slug is marked required, from/to are documented as ISO time strings, and the default range (last 30 days) is stated. That is meaning the bare schema does not carry.

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 (aggregate summary for a job over a time window) and enumerates the exact metrics returned: sessions, human turns, events, action calls, tokens, daily curve. This clearly separates it from siblings like get_job, list_sessions, and query_events.

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 ('用户问这岗位最近怎么样/今天多少人来就用它') and an explicit anti-pattern ('不要靠聊天历史猜数字'). It does not name an alternative sibling tool for the case where raw session-level data is wanted, so it stops just 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?

No annotations are provided, so the description carries the full burden. It discloses the returned fields and the workflow ordering, but says nothing about read-only guarantees, auth/permission requirements, or failure behavior for an invalid slug.

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 paragraph, front-loaded with the purpose and return fields, then the constraint. Every clause earns its place; no filler.

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

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

With no output schema and no annotations, the inline field list (id/title/description/cost/credits/anonymous/job/params schema) usefully describes the return shape and is the right thing to include. Only the slug's meaning and possible error modes remain uncovered.

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 single param has 0% schema coverage, so the description must compensate. It confirms slug is required but never explains what the slug identifies (job vs template) or its format, leaving a real gap even though the schema independently marks it required.

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 (this job's, by-template, available actions), and names the fields it returns. It is clearly distinct from siblings like canvas_action and list_templates without needing their schemas.

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

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

Explicitly instructs to call it before canvas_action and not to guess action names, because action sets differ per job. This is a precise when-to-use plus a named downstream alternative.

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

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

No annotations, so the description handles the behavioral load. '列出' clearly signals a read-only list, it enumerates the exact return fields, and it establishes the tool as the authoritative source for slugs (warning against hallucination), which is a meaningful behavioral contract for an agent. It doesn't cover auth or pagination, but for a zero-parameter list tool 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?

Three short, front-loaded clauses: purpose and return fields first, usage/routing second, parameters last. No wasted words; the only redundancy is '参数：无', which is harmless.

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

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

For a simple zero-parameter list tool with no annotations and no output schema, the description is nearly complete: it states purpose, usage, the authoritative slug contract, and the fields returned. The only missing element is return shape/pagination detail, which is minor for this 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?

With zero parameters and schema coverage 100%, the baseline is 4. The description redundantly states '参数：无', matching the empty schema, and adds no parameter meaning because none exists.

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 / 名称 / 模板 / 画布链接). It also differentiates itself as the authoritative slug source for all sibling position tools, so an agent can tell why to call it rather than get_job or list_templates.

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 says to use it when the user asks '我有哪些岗位' and mandates that all subsequent position-operation tools must obtain slugs from this call rather than memory. This gives both the trigger condition and a strong routing prerequisite, leaving little 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?

No annotations are provided, so the description carries the full burden. It discloses authentication requirement ('需要有效 Key，匿名不开') and default ordering ('最近优先' – most recent first), which are useful behavioral details. However, it doesn't describe pagination semantics in depth (e.g., what nextCursor looks like, max pages) or rate limits, leaving some behavioral gaps for a read-heavy list tool.

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

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

The description is compact and front-loaded: it starts with the resource and returned fields, then parameter explanations, then a usage tip, and finally the auth requirement. Every sentence earns its place, and there is no filler.

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

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

Given 6 parameters with zero schema description coverage and no output schema, the description is fairly complete: it covers the required param, all optional params, pagination via cursor, ordering, and auth. It could be improved by stating the return type more explicitly (e.g., a list of objects with those fields) or noting max limit behavior, but it is largely sufficient for an agent to call correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It explains each parameter: slug is required (岗位的slug), q searches by host user identifier fuzzy, from/to are date range filters, limit controls count, and cursor is for pagination via nextCursor from the previous page. This adds significant meaning beyond the bare schema definitions (which have no descriptions), though it doesn't specify date format for from/to.

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?

Description states a specific resource (访客会话列表/visitor session list for a job) with clear output fields (session_id, host user identifier, turns, time). It distinguishes itself from siblings like get_session_log and query_events by focusing on a per-job session listing. However, it doesn't explicitly name a sibling it is not.

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?

Provides a clear use case ('想看最近都服务了哪些人' – to see who was served recently) and the follow-up step (use session_id to view details via get_session_log). This gives strong contextual guidance, though it doesn't state when NOT to use it or compare directly to alternatives like query_events.

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

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

No annotations are provided, so the description carries the full burden. It discloses the returned fields (templateId / 名称 / 说明 / canOpen / missingHandlers / 动作清单) and a critical behavioral rule: canOpen=false means not openable and must not be recommended. That is exactly the kind of constraint an agent needs. It stops short of permission or rate-limit notes, but for a no-param read tool this is strong.

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 usage, then return shape, then exclusion, then the canOpen caveat, ending with 参数：无. Every sentence carries information. It is slightly dense but no sentence is wasted.

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

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

For a zero-param list tool with no output schema and no annotations, the description covers what it returns, when to use it, when not to, and the canOpen constraint. That is sufficient for correct invocation. Minor gap: no mention of ordering or pagination, but none is implied.

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

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

Parameter count is 0, so the baseline is 4. The description correctly notes 参数：无, which is accurate and leaves no ambiguity.

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 explicitly distinguishes from the sibling list_my_staff by naming it. 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?

Explicit when-to-use ('想知道系统能开哪些岗位'、用户要开通新岗位时) and when-not ('别用它找已开好的岗位'——那是 list_my_staff). The exclusions and alternative are named directly.

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

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

With no annotations, the description carries the full burden and does so: it discloses that the session is already established at return time, that push_screen can pre-deliver cards to users who have not yet opened the link, that content is back-filled on open, and that chat/tracking are attributed to the same session_id. That is substantive behavioral context beyond the schema.

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

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

Front-loaded with purpose, then parameters, then return value and the deferred-push workflow, so an agent can stop reading at any level. It is dense and slightly long, but nearly every clause adds actionable information rather than repeating the schema.

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

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

There is no output schema, yet the description explicitly states the return payload {url, session_id}, instructs the agent to persist session_id, and explains the session lifecycle across push_screen and get_session_log. Nothing required to call it correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it flags slug as required, marks hostUserId as 'strongly recommended' because session ownership and offline re-push depend on it, and explains that app selects the canvas page (aicare-kf). This goes beyond the terse schema descriptions.

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

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

Starts with a specific verb+resource: generating a canvas link plus a session ID for a position, and immediately scopes it ('when the user needs a visible interface'). It is clearly distinguishable from siblings like push_screen and get_session_log, which it names as downstream consumers rather than alternatives.

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

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

Gives a concrete trigger condition ('用户需要看得见的界面' – viewing reports/commodities/doing detection) and clarifies the ordering relationship with get_session_log and push_screen. It does not state explicit exclusions or when another sibling should be preferred instead, 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?

With no annotations, the description carries the full burden and does so well: it declares this is a write, that it mutates the customer's job configuration, and that changes are immediately live. It does not cover auth/permission requirements or response shape, so not a 5.

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

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

Front-loaded with the action and the patch-only rule, then the field list, then the required-params and safety note. The field enumeration is dense but earns its place; slightly list-heavy but no filler sentences.

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

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

For a 2-param mutation tool with nested objects, no annotations and no output schema, the description covers required params, mutation semantics, immediacy, and field shapes. Missing return-value or error behavior, but that is a minor gap here.

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

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

Schema coverage is only 50% (slug has no description, patch is loosely typed), but the description compensates: it states both slug and patch are required and fully documents the patch fields, including shapes and enums (layoutStyle split|pip|classic, contextMode inline|webhook, promotionConfig and productSources object structures).

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: partial (patch) modification of the 岗位配置, and enumerates exactly which fields can be changed. It is clearly distinguished from the read counterpart get_staff_config by name and by the word 局部修改, though it never explicitly names the sibling as an alternative.

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 real operational guidance: it is a write operation on the customer's job, changes take effect immediately, and the agent should restate the change to the user before calling when intent is unclear. No explicit when-not or alternative-tool routing, which keeps it below 5.

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

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

With no annotations, the description carries the full behavioral burden and does so: online sessions render immediately, offline (or never-opened) sessions are queued as pending and auto-pushed on the next open by that session or by the same-position same hostUserId. It also states the auth requirement (valid Key, anonymous not allowed) and the ownership constraint on session_id.

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, then online/offline behavior, then warnings; essentially every sentence earns its place. It is delivered as one dense run-on paragraph rather than being broken into scannable segments, which slightly hurts readability but not content economy.

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 or annotations exist, so the description must cover everything, and it does: inputs, rendering semantics, deferred-delivery behavior, auth, and the ownership caveat. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is only 50% (title and session_id undocumented), and the description compensates fully: it marks session_id and content as required, names session_id's source, and explains content's fence syntax (canvas-md cards, canvas-html full documents, canvas JSON blocks, out-of-fence text as subtitles) plus speak=true reading subtitles and title being optional. This adds real meaning beyond the schema.

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

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

States a specific verb and resource: pushing content onto the screen of a canvas session, and immediately distinguishes itself from canvas_action (side-effect actions such as reports/checks). An agent can tell what this does and what it does not do without opening the schema.

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

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

Explicitly names the alternative for side-effect work (canvas_action), tells where session_id comes from (open_canvas or list_sessions), and gives a when-not rule: do not reuse someone else's session_id because screens belong to sessions, not people. Alternatives and exclusions are both present.

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?

无注解时描述需承担全部行为披露。它说明了需要有效 Key、匿名不可用（认证要求），以及返回结果包含 source 字段标识发起者，并具体描述了 action_call 和 push 的 payload 结构，揭示了部分返回内容的细节。但仍未说明速率限制、分页行为或完整返回格式。

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

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

描述紧凑，用短句列举了关键信息：功能、类型枚举、参数、返回特征、认证要求。没有冗余填充，信息密度高。但将多个不同性质的信息（参数、返回结构、认证）堆叠在一个段落中，结构感稍弱。

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

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

工具无输出 schema，描述需要传递足够的返回信息帮助代理理解结果。它提到了 source 标识和某些 payload 字段，但缺乏对整体返回形状（如事件列表的通用字段）的说明。参数整理在 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 覆盖率为 0%，5 个参数中只有 slug 在描述中明确标注为必填，type、from/to、limit 的参数含义和格式完全未在描述中说明。描述的补充信息非常有限，仅提到 limit ≤ 500，但未补充 from/to 的格式预期或 slug 的指代。基线 3 因低覆盖率应提高要求，此处描述未充分补偿。

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

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

描述清晰表达了具体动作和对象：跨会话按类型拉取事件，倒序排列。列出了所有可用的 type 枚举值（chat_user/chat_assistant/track/action_call/page_open/push），有助于限定用途。但未明确区分它与兄弟工具 get_session_log、list_sessions 等的关系，代理需要自行推断。

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?

描述隐含了使用场景：按事件类型查询，且有计费和排障的提示，但没有明确说明何时应该使用此工具而不是 get_session_log 或 list_sessions。没有列出排除条件或替代方案。

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