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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds useful context by clarifying the scope of destruction ('current round' only) and equating it to a known UI action, which helps an agent understand it does not delete the session.

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, front-loaded sentence that conveys the action, target, effect, and a familiar UI equivalent with zero wasted words.

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

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

For a simple one-parameter mutation tool with full annotation coverage and no output schema, the description is nearly complete: it states what it does, the prerequisite ('running session'), and the limited scope of the interruption. Only minor details like idempotency or behavior on non-running sessions are absent.

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

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

Schema coverage is 100%, so the single 'session' parameter is fully documented by the schema. The description adds no additional semantics about the parameter beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific action: sending an abort to a running session to stop its current round, equivalent to the UI Stop button. It clearly distinguishes the effect from deleting a session, but does not explicitly name or contrast with any sibling tool.

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

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

Usage is implied: call it when a session is running and you want to interrupt the current round. There is no explicit when-not guidance or mention of alternatives (e.g., piweb_delete_session for full termination).

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=true and openWorldHint=true, so safety is covered; the description goes further and itemizes what state is exposed (streaming or not, context occupancy, model, queued messages). It does not discuss freshness, cost, or whether the snapshot is cached, which keeps it out of 5 territory.

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 compact sentence with the two branches front-loaded in the order the agent will decide between them; every clause carries information and there is no boilerplate.

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 return-value burden and does name the fields of interest (running/waiting, streaming, context usage, model, queued messages). It stops short of exact field names or shapes, but is sufficient for a read-only, single-parameter state query.

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

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

Schema coverage is 100% and the single param is self-documenting, so the baseline would be 3. The description earns extra credit by pairing each parameter state with a distinct result shape (global snapshot vs. detailed per-session state), which tells the agent why to pass or omit session rather than just how.

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 resource (agent run state) and explicitly splits behavior into two modes: no-session global snapshot vs. per-session detail. It is clear what the tool returns, but it never distinguishes itself from overlapping siblings such as piweb_status, piweb_list_sessions, or piweb_get_session, so an agent must still infer which one to pick.

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 mode-selection guidance: omit session for the global view of running/blocked conversations, pass session for one session's detail. There are no exclusions or named alternatives, so it falls short of routing the agent against competing sibling tools.

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?

Beyond the annotations, the description discloses two behavioral traits: it consumes one model call (cost/latency) and it persists the result to disk. The openWorldHint and idempotentHint annotations align with this, and readOnlyHint=false is consistent with writing a name. It stops short of saying what happens to an existing name, which idempotency partially covers.

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

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

Two compact sentences, front-loaded with the action and the mechanism, then the equivalence and cost caveat. No filler.

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

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

For a single-parameter tool with no output schema, the description covers mechanism, effect (persisted name), and cost, which is enough to call it correctly. A note on whether an existing name is overwritten would make it fully complete.

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

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

Schema description coverage is 100% and the single 'session' parameter is already documented as '会话 id / 名称'. The description adds no format, id-vs-name disambiguation, or validation detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource: it invokes pi's title generation so the model names the session from conversation content and writes it to disk. The phrase '等价于侧边栏的自动命名' makes the automatic nature clear, implicitly distinguishing it from the manual piweb_rename_session sibling, though that sibling is never named.

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

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

Usage is implied (call it when you want an auto-generated session name) and the cost warning '要花一次模型调用' is a useful selection consideration. However, there is no explicit when/when-not guidance and no alternative (e.g. piweb_rename_session) is named for the manual case.

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

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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower. The description adds real behavioral nuance: that omitting message skips dispatch entirely, and that the tool returns a real sessionId. It does not discuss failure modes when cwd is invalid, but the schema notes the directory must already exist.

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

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

Three tight sentences, front-loaded with the core action and the return-value promise, followed by the mode distinction and the optional-parameter hint. No filler, though the parenthetical for sessionId and ensure_session adds slight nesting.

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

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

There is no output schema, and the description compensates by naming the returned sessionId. The wait_seconds blocking semantics are left to the schema, which documents them fully. For a 6-param creation tool this is nearly complete, missing only error/edge-case behavior on an invalid cwd.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by grouping the optional model knobs (provider/modelId/thinking_level) and pointing at piweb_list_models as the source of valid model values, which the schema text does not say.

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

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

States a specific verb and resource (新建 pi 会话) with the scope qualifier 在指定项目目录下, and immediately discloses the return value (真实 sessionId). It also disambiguates its two modes against the related ensure_session semantics, so an agent can distinguish it from piweb_get_session / piweb_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?

Explicitly states the two usage modes: with message it sends the first prompt, without message it only creates the runtime. It also routes the agent to piweb_list_models for valid model values. It stops short of stating when to prefer this over piweb_send_message for an existing session, but the context is clear.

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 readOnlyHint=false, but the description adds non-obvious behavior: the deletion cascades to sub-agent sessions and is irreversible, plus a mandatory confirmation gate. These are real consequences beyond what the structured fields 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?

A single tightly-packed sentence with the destructive consequence front-loaded in the parenthetical and the confirmation requirement last. Every clause earns its place with zero filler.

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

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

For a destructive, no-output-schema mutation tool, it covers what is destroyed (sub-agent sessions), that it cannot be undone, and the guard condition. Only the permission/auth requirements and post-delete state are left implicit.

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

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

Schema description coverage is 100%, so both parameters (session, confirm) are already documented in the schema. The description's mention of confirm=true duplicates that; it adds no new format or semantics for the session identifier. Baseline 3 applies.

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

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

The description states a specific verb+resource (删除会话/delete session) and scopes it with the cascade and irreversibility detail. It does not, however, distinguish itself from siblings like piweb_abort_session, which an agent might conflate with terminating a session.

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

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

It clearly states the precondition that confirm=true must be explicitly passed or execution is refused, which is genuine usage guidance. It does not say when to prefer this over alternatives such as piweb_abort_session (stop running) versus permanent removal, leaving that inference to the agent.

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

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

Annotations declare readOnlyHint=false and idempotentHint=true; the description corroborates this by stating it writes to local disk and returns the path, and adds a latency warning for large sessions ('大会话导出要几秒') that annotations do not convey. It does not mention overwrite behavior or failure modes, but the added side-effect and performance context is genuinely useful.

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

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

A single compact sentence that front-loads the core action and artifact, with the latency caveat appended. No redundant restatement of the title or schema.

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

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

For a two-parameter tool with no output schema, the description covers the action, the file artifact, the returned path, and expected latency. Only minor details such as overwrite handling or error behavior are absent.

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

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

Schema description coverage is 100%, so both parameters (session id/name and out_path with its default) are already fully documented in the schema. The description adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (export), resource (session), and concrete artifact (single-file offline HTML written to local disk, path returned). This clearly separates it from read-only siblings like piweb_get_session or piweb_read_file, which do not produce a file artifact.

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 parenthetical '可离线翻阅/分享' implies the use case (offline reading/sharing), but there is no explicit when-to-use versus piweb_get_session or when-not guidance. Usage is only inferable.

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 declare readOnlyHint=false and openWorldHint=true but say nothing about what happens to the source; the description explicitly states 原会话不受影响 and that the branch is copied 整体, which clarifies the non-destructive fork semantics. It does not mention that repeated calls are non-idempotent (creating duplicate sessions), which is the one remaining behavioral gap.

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

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

Three short sentences, front-loading the core action and immediately following with the guarantee about the original session. The final sentence restates the use case already implied by the first, so it is mildly redundant but not wasteful.

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

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

For a two-parameter creation tool with no output schema, the description covers what is created and that the source is untouched, which is adequate to invoke it. It omits what the call returns (presumably the new session's identifier), which an agent would need to continue working with the fork.

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% for both parameters (session required, name optional), so the schema carries the parameter burden. The description adds no format, id-vs-name, or naming-collision guidance beyond what the schema already says, making the baseline 3 appropriate.

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

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

The description names a specific verb and resource: copying the session's current branch wholesale into a new session, and anchors it to a familiar UI concept (sidebar Fork). An agent can tell it produces a new session from an existing branch, though it never names the nearest sibling (piweb_create_session) it differs from.

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

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

The phrase 「从这条线另开一条道」 implies the intended use case (branch off without disturbing the existing line), but there is no explicit when-to-use, when-not-to-use, or comparison against piweb_create_session. Usage is inferable rather than stated.

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 are sparse (readOnlyHint=false, openWorldHint=true), but the description discloses meaningful side effects and defaults: it marks the session as read locally, defaults to the last 30 messages, includes tool summaries, and shows thinking only as a preview unless include_thinking='full' is used, which is noted as slower. It does not cover auth or rate limits, but adds substantial context beyond annotations.

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

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

The description is a single dense paragraph that front-loads what the tool does, then covers session identifiers, pagination, thinking behavior, and read marking. Every sentence carries information, though it could be slightly more scannable.

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

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

For a 9-parameter tool with no output schema and minimal annotations, the description covers the most important behavioral defaults and side effects. Remaining schema-level details like format, max_chars, and tool_result_chars are documented in the schema, so the definition is reasonably complete.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters. The description largely repeats schema facts (session id/prefix/name/snippet, default 30 messages, default read marking) and adds only slight nuance about include_thinking='full' fetching the complete chain.

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: reading a session's conversation content, with defaults for the last 30 messages and tool-call summaries. It is clearly distinguishable from listing/searching/watching siblings by what it returns, but it does not explicitly name an alternative tool.

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

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

Gives operational guidance for pagination ('要读更早的历史用 offset 往前翻') and for fetching full thinking chains, which implies how to use the tool. However, it never states when to use this tool versus siblings like search_sessions, list_unread, or watch_session, nor any exclusions.

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?

The readOnlyHint annotation already establishes this is a safe read operation, lowering the bar. The description adds that the output is a full patch, but does not disclose that the patch may be truncated at max_chars (only the schema hints at this), so it adds modest behavioral context beyond annotations.

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

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

Two short sentences, front-loaded with the core purpose before the usage hint. Efficient with essentially no filler, though the second sentence mixes two distinct use cases.

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

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

For a simple read-only inspection tool with no output schema, the description conveys the nature of the return value ('完整 patch') and its intended use. The only minor gap is not mentioning truncation behavior, which is left to the schema.

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

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

Schema description coverage is 100%, so cwd, path, and max_chars are already documented in the schema. The description contributes no additional parameter meaning, making the baseline 3 appropriate.

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

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

The description states a specific verb+resource: viewing the complete git patch of a single file ('看某个文件相对 git 的完整 patch'). This is clear and concrete, but it does not explicitly differentiate from siblings like piweb_git_status or piweb_read_file.

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 two concrete usage contexts — copy the patch into a session so an agent can edit, or use it to verify that an agent's changes are reasonable. That is real when-to-use guidance, though it names no alternative tool or exclusion condition.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral detail about what the tool surfaces: branch/repo root, changed files and their status codes, and added/deleted line counts. It still omits operational details such as error behavior or handling of untracked files.

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

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

The description is two tight sentences: the first front-loads what is returned, and the second states the operational purpose. Every clause earns its place with no 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?

For a simple read-only git status tool with no output schema, the description adequately explains return content and intended use. It is only slightly incomplete because it does not distinguish git status from git diff, a sibling that an agent may need to choose between.

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

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

The schema already documents the single required parameter cwd as an absolute project path, with 100% schema description coverage. The description only repeats '某个项目目录' and adds no syntax, path constraints, or edge-case guidance beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb and resource: viewing the git status of a project directory, and lists the concrete output (branch/repo root, changed files with status codes, added/deleted line counts). It does not explicitly distinguish itself from the sibling piweb_git_diff, which likely overlaps in inspecting changes.

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

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

It gives clear context for use: '用来验收 agent 到底动了什么' (to verify what an agent changed). It does not state when-not to use it or name piweb_git_diff as an alternative for detailed diffs, so it stops short of explicit routing guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds real behavioral context beyond that: it prefers git ls-files and skips .gitignore, which directly affects which files appear in the result. It stops short of saying what happens outside a git repository or what the returned entries look like.

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 clauses, well front-loaded: what it lists, how it lists, then why you'd use it. Nearly every clause earns its place; only the filter sentence is mildly redundant with 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?

For a simple read-only list tool with no output schema, the description conveys the resource and the mechanism sufficiently. It could be stronger by stating the return shape (a path list) or the non-git-repo fallback, but nothing critical for invocation is missing.

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

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

Schema description coverage is 100%, so all three parameters (cwd, limit, filter) are already documented in the schema. The description's '可带 filter 做模糊匹配' merely restates the schema's filter definition and adds no format or matching-rule detail beyond it. Baseline 3 applies.

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

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

States a specific verb+resource (list files under a project directory) and even the mechanism (git ls-files, .gitignore skipped). It is distinguishable from piweb_read_file by framing itself as the discovery step ('用来定位某个项目里有哪些文件可读'), though it never names that sibling explicitly.

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

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

The closing clause implies intended usage – locate which files exist/are readable before reading them – but gives no explicit when-to-use/when-not guidance and never names piweb_read_file as the follow-up alternative. Usage is inferred rather than stated.

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?

readOnlyHint=true and openWorldHint=true already establish the safety profile, so the description doesn't need to restate that it is a read. It does add real value by disclosing what the call surfaces — available models, the default model, and thinking levels — which is behavior beyond the annotations and, with no output schema, otherwise unavailable.

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

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

Two tight sentences. The capability and its output content come first, and the usage trigger is packed into the second clause with no filler.

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

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

With no output schema, the description usefully enumerates the return content, and all three optional parameters are covered by the schema. It stops short of mentioning truncation or the limit's effect on results, which is the only real gap for a listing tool of this kind.

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%: cwd, limit (default 60, max 500), and filter are each documented in the schema itself. The description adds no syntax, format, or interaction detail beyond that, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ('列出某个项目目录下 pi 可用的模型') and specifies the returned shape (provider/model form, default model, available thinking levels). That return-content detail cleanly separates it from the mutation sibling piweb_set_model, which the usage clause implicitly routes away from.

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

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

It states exactly when to call it: '新建会话或切模型前拿它选值' — before creating a session or switching models, to pick a value. It gives no explicit when-not condition or named alternative, but the context is unambiguous.

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=true and openWorldHint=true, so the safety profile is covered. The description usefully discloses the aggregation output (running/unread counts, last activity), but says nothing about ordering, pagination, or whether projects with zero sessions are excluded.

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

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

Two compact sentences: the first states the aggregation and its output fields, the second states the intended use. Nothing is redundant, and the core purpose 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?

There is no output schema, so the description correctly compensates by enumerating the aggregated fields returned. Combined with annotations covering read-only safety and a fully documented 2-parameter schema, the definition is nearly sufficient; only ordering/pagination and edge-case behavior remain unstated.

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

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

Schema description coverage is 100%, so limit and min_sessions are already fully documented in the schema, including their defaults. The description adds no format, ordering, or interaction detail beyond that, so the baseline 3 applies.

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

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

The description names a specific verb+resource (aggregate pi-web sessions by project directory) and enumerates exactly what is aggregated: session count, running count, unread count, last activity time. This clearly separates it from piweb_list_sessions, which lists sessions rather than grouping them, though no sibling is named explicitly.

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

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

The phrase 「用来先看『我的活儿都压在哪个目录』」 implies an exploratory/overview use case, which gives the agent some routing signal. However, it offers no explicit when-to-use conditions, no when-not, and does not point to alternatives such as piweb_list_sessions or piweb_list_unread for narrower questions.

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=true and openWorldHint=true, so safety is covered. The description adds a genuinely non-obvious behavior: unread uses this MCP's own read cursor and is NOT shared with the browser's unread markers — an agent would otherwise mis-model the state. It does not discuss result ordering guarantees or pagination beyond what `sort`/`limit`/`force` already state in 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 the two disambiguation rules. For a 10-parameter tool the text is dense but every clause maps to a decision the agent must make; no filler and no restatement of field defaults already in 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?

For a 10-param, no-output-schema tool with only two annotations, the description covers the highest-risk ambiguities (unread cursor, keyword scope, sibling routing). It omits return-shape/ordering description and does not explain `include_subagents` vs `include_empty` intent beyond the schema, which keeps it just short of 5.

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

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

Schema description coverage is 100%, so baseline is 3. The description goes beyond the schema by disambiguating the enum value `unread` (whose cursor semantics the enum name alone hides) and by bounding what `keyword` actually matches. That is real added meaning over the field 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?

Opens with a specific verb+resource (列出/筛选 pi-web 里的 pi 会话) and immediately enumerates the filter axes (项目目录、关键词、状态、时间). It explicitly names two siblings it is not — piweb_search_sessions and piweb_triage — so an agent can route without opening any schema.

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

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

Provides explicit when-to-use-else guidance: keyword only covers 会话名称/首条消息/目录, so full-text search must go to piweb_search_sessions; '哪些会话在等我' must go to piweb_triage. It also scopes the ambiguous status=unread value. This is a routing rule set, not a hint.

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/openWorld, but the description adds genuinely useful behavioral context: the 'unread' notion is driven by this MCP's own read cursor, mutated by piweb_get_session and piweb_mark_read, and is deliberately separate from browser localStorage markers. That is exactly the kind of non-obvious semantics an agent needs.

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

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

Front-loads the purpose with the category legend, then appends two caveats (cursor semantics, alternative tool). Dense but each sentence carries information; 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?

No output schema exists, but the description effectively explains what the three categories mean, which covers the return semantics for a read-only list tool. Combined with annotations, an agent has enough to call it correctly, though pagination/ordering behavior is not described.

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

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

Schema description coverage is 100%, so all three parameters (cwd, limit, since) are already documented in the schema. The description adds no further parameter syntax or format detail, so the baseline 3 applies.

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

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

Specific verb (list) plus resource (sessions needing attention) with a three-way taxonomy of the returned categories (waiting-for-input, new-since-cursor, running-unviewed). It clearly distinguishes itself from piweb_triage and, by implication, from the plain piweb_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?

States the use case (sessions needing my attention) and names piweb_triage as the alternative when judging by conversation outcome. It does not explicitly state when to prefer piweb_list_sessions instead, 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?

With readOnlyHint=false and openWorldHint=true already signaling a mutation, the description adds real value by disclosing that only the MCP-side cursor is modified and the browser's unread markers are untouched. It also explains the reversibility of unread=true, though it doesn't describe any response or side effects on the unread count itself.

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 packs the three behaviors into a tight single sentence plus a scope sentence. Nothing is wasted, though the run-on structure slightly reduces scannability.

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

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

For a two-optional-parameter mutation tool with no output schema and no nested objects, the description covers purpose, both modes, and scope boundaries. It is essentially complete, missing only return/confirmation behavior, which is minor 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 100%, so both parameters are already documented in the schema. The description restates the same semantics (session optional, unread default false) without adding format or edge-case detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: it updates this MCP's read cursor, with clear per-session vs. bulk semantics. It also distinguishes itself by clarifying the scope ('only this MCP's cursor, not the browser's unread markers'), which separates it from sibling read/list 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?

Explicitly describes the two operating modes: supply session to target one conversation, omit it to mark all unread at once, and unread=true to reverse/clear the cursor. It gives clear context for invocation but does not name alternative tools for related jobs.

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 readOnlyHint and openWorldHint; the description adds genuinely new behavior: server-side chunked return, one chunk by default, and the nextOffset continuation contract, plus rejection of binary files. It does not cover permission/session-scoping behavior of session_id, but the chunking contract is meaningful added 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?

Two dense sentences, no filler, front-loading the chunked-read behavior before the continuation hint and the binary exclusion. Every clause carries information.

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

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

Annotations cover the safety profile and the schema fully documents all four parameters, so the description only needs to add operational semantics — which it does via the chunking/continuation contract and binary rejection. Minor gaps remain around return format and session_id scoping, but no output schema exists to help.

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 100% schema coverage the baseline is 3, but the description goes beyond the schema by tying 'offset' to a returned nextOffset value for pagination, which is the actual usage convention an agent needs. It does not clarify max_chars or session_id beyond what the schema already says.

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

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

States a specific verb and resource ('读一个文本文件的片段') and defines the scope precisely: chunked text reads with an offset continuation. It is clearly distinct from piweb_list_files, though it never names a sibling explicitly.

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

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

Gives the continuation pattern (use offset=nextOffset to read the next chunk) and a clear exclusion (binary files are rejected). It stops short of naming an alternative tool or describing when to prefer another read route, so it is context-rich but not fully 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 already declare this is a write (readOnlyHint=false), idempotent, and open-world, so safety and repeat-call semantics are covered. The description adds the useful context that the change is user-visible and equivalent to the sidebar rename. It does not disclose whether the name must be unique, what happens on collision, or the response shape.

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

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

A single short sentence with no filler, and the action plus the UI equivalence are front-loaded. It is appropriately sized but unambitious.

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

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

For a two-parameter mutation with no output schema, the definition covers the essentials and annotations carry the mutation profile. However, gaps remain on naming constraints and failure behavior, which matter for an idempotent renamed operation.

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

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

Schema coverage is 100%, with both 'name' and 'session' documented in the schema, so the baseline is 3. The description adds no format, constraint, or identifier-resolution detail 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 (rename) and resource (session) in one sentence, and ties it to a concrete, recognizable UI action in the pi-web sidebar. It does not differentiate from siblings such as piweb_auto_name_session, which also assigns names, leaving a small ambiguity.

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

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

No when-to-use guidance and no alternatives named. An agent cannot tell from this text whether to prefer this tool over piweb_auto_name_session or how renaming interacts with session lifecycle operations.

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 and openWorldHint, so the safety profile is covered. The description adds genuinely useful traits beyond that: literal (non-regex) semantics, case-insensitivity, a 3-second server time budget, and possible truncation of results.

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 tight sentence with front-loaded purpose, then the caveat (time budget/truncation) and the alternative. No wasted words, though the semicolon-chained clauses are dense.

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

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

No output schema exists, and the description compensates by explaining what is returned (session ids of matched snippets) plus the truncation caveat. Adequate for a read-only search tool; it could add a hint about the snippet/limit behavior on truncation.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description only echoes 'literal search' and adds case-insensitivity, adding marginal value over the structured fields.

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 (literal, case-insensitive search), the precise resource (message bodies across all sessions), and the return shape (session ids of matched snippets). This cleanly distinguishes it from piweb_get_session, which it names, and from piweb_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?

Gives explicit routing: narrow the keyword when there are many hits, or fall back to piweb_get_session for detail. Clear context for when to use it versus drilling in, though it does not state an explicit when-not condition.

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

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

Adds real value beyond the annotations: it discloses the auto-restart behavior, the default non-blocking return, what wait_seconds changes about the response, and warns that the target agent will actually mutate files/run commands. This is meaningful operational context even though the annotations already establish non-read-only/non-destructive.

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, then adds runtime behavior, then the safety warning. It is a bit long but every clause conveys distinct information, with no repetition 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?

For a tool with no output schema, the description explains the two return modes (immediate vs. final assistant reply with wait_seconds). Combined with the 100%-covered schema and annotations, an agent has enough to invoke it safely.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description restates wait_seconds semantics and notes streaming_behavior defaults to pi-web's decision, adding little beyond what structured data provides; baseline 3 applies.

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

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

States a specific verb (发送提示词) and resource (已有会话) and clarifies the equivalence to typing in the pi-web input box. It is clearly separable from read-only siblings like piweb_wait_for_reply and piweb_watch_session.

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 operating context: the session is auto-started if not running, default behavior is fire-and-return, and wait_seconds>0 blocks for the turn. It advises confirming the right session before sending, but does not explicitly name alternatives (e.g., wait_for_reply) for retrieving the answer.

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 declare readOnlyHint=false, openWorldHint=true and idempotentHint=true, so mutation and idempotency are already covered structurally. The description adds a genuinely useful side-effect disclosure: a non-running session will be started as a result of the call, which the annotations do not convey. It omits any note on permissions or behavior on an invalid model 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?

Three short sentences, no filler, with the core effect stated first, the side effect second and the prerequisite lookup last. Every sentence carries distinct information.

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

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

For a three-required-parameter mutation with no output schema, the description covers effect, side effect and prerequisite adequately. It leaves open whether the change applies to an in-flight turn and what an invalid provider/model_id yields, minor gaps for this tool's complexity.

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

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

Schema description coverage is 100%, with each of session, model_id and provider documented inline including examples, so the schema does the heavy lifting. The description adds only the provenance hint (values come from piweb_list_models), which is a mild but real addition beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource (switch the model a session will use next) and anchors it to a familiar UI equivalent, so the agent immediately knows the effect. It also names the sibling piweb_list_models as the value source, distinguishing it from read-only siblings like piweb_list_models or piweb_get_session.

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 directs the agent to call piweb_list_models first to obtain valid provider/model_id values, which is actionable usage guidance. It does not state when not to use it (e.g. mid-turn, or sessions where the model is locked), so it stops short of full when/when-not coverage.

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=true and openWorldHint=true, so safety is covered; the description adds non-obvious value by enumerating the diagnostic fields returned (address, password source, session counts, read/write boundary and writable project roots). It does not describe output shape in detail, but with readOnly annotations and no output schema this is a solid disclosure.

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 purpose, then a colon-delimited field list, then a short usage cue. Dense but every clause adds information; the field enumeration is slightly listy but earns its place by standing in for a missing output schema.

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

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

With no output schema and no parameters, the description must supply the return-value picture, and it does so by naming the diagnostics reported. An agent knows what a successful check yields and what it means for the read-only/writable-root boundary.

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 there is nothing to document; the baseline for a no-param tool applies. No misleading parameter claims are made.

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 ("检查 MCP 到 pi-web 的连接配置") and enumerates exactly what is inspected: address, password source, session totals, running sessions, and read/write boundaries. No sibling tool performs a connection/config health check, so it is clearly distinguishable from the session/file/git 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?

Explicit trigger given: "连不上时先用这个排查" – use it first when the connection fails. Clear usage context, though it does not name which sibling to fall back to after the check passes or what a failed check implies for subsequent calls.

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?

Beyond readOnlyHint/openWorldHint, the description discloses the important behavioral trait that triage is rule-based and model-free ('不经过模型'), so results are deterministic, and that every bucket entry carries its justification ('可复现、可核查'). It does not cover ordering within groups, output size limits, or whether subagent sessions skew counts beyond the schema default.

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 mechanism and the bucket taxonomy, then the use-case pitch and the default window — order is sensible and the emoji list earns its space as the output contract. It is a dense run-on with some redundancy between the bucket definitions and the '这是…最快的一招' closing line.

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?

Seven all-optional parameters and no output schema, but the description supplies the missing output shape (six named groups plus per-entry evidence) and the default scoping, which is exactly what an agent needs to call it blind. Nothing material is left dangling.

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 every parameter is already documented, and the description adds only the default 3-day window and the notion that 'stalled' combines an unfinished turn with idle time (tying loosely to stalled_hours). It says nothing about per_group, cwd prefix matching, or include_empty/include_subagents behavior beyond what the schema states.

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

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

The description states a concrete verb (triage) and the exact rule set applied (last message author + dangling tool calls + idle time), then enumerates the six output buckets with emoji labels. An agent knows precisely what comes back, but no sibling tool (e.g. piweb_list_unread or piweb_agent_state, which plausibly overlap) is named to draw the boundary.

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 explicitly recommends itself for one question — 'how many conversations are waiting on me' — and calls itself the fastest option, which is usable routing guidance. It also states the default 3-day activity window as a usage constraint, but gives no when-not conditions or named alternatives for the overlapping wait/unread tools.

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 are minimal (readOnlyHint=false, openWorldHint=true), so the description carries most of the burden and does add real value: it discloses that the tool polls, blocks until streaming output stops, and returns only the last assistant reply. It does not say what happens on timeout (partial reply? error?) or whether the wait consumes/marks the reply, which are the remaining behavioral gaps.

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

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

Two sentences, no filler, and the mechanism (poll until streaming ends, return final reply) is front-loaded before the recommended workflow. 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?

No output schema exists, and the description does cover the return value ('final assistant reply text'), which is the key missing piece. What it omits is failure/timeout behavior for a long-polling tool with a configurable timeout, which an agent would want to know before relying on it.

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

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

Schema description coverage is 100%, so session, max_chars, poll_seconds and timeout_seconds are already documented with types, bounds and defaults. The description adds no parameter-level detail (e.g., interaction between timeout_seconds and poll_seconds, or what max_chars truncation does to the reply). Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource: poll a session until its current round finishes streaming, then return the final assistant reply text. The blocking/polling semantics are clear. It doesn't explicitly distinguish itself from the sibling piweb_watch_session, which is a plausible alternative for the same session, 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?

Explicitly prescribes the workflow: call piweb_send_message without waiting, then come back to this tool to collect the result. That names both the pattern and the companion tool. It gives no exclusion guidance (e.g., when to prefer piweb_watch_session or piweb_list_unread instead), so it is clear context without alternatives.

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

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

Annotations only say readOnlyHint=false / openWorldHint=true; the description explains why it is not a pure read by disclosing that subscribing to a non-running session spins it up as an idle process, equivalent to opening it in pi-web. It also discloses exactly what is captured during the window and what is returned (accumulated text), which is the key behavioral context an agent needs.

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

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

Three sentences, zero padding: core action first, then the usage cue, then the side-effect warning last. The ordering is front-loaded and each sentence carries distinct information.

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

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

With no output schema, the description still states the return value (accumulated text over the window), explains the collection modes, and warns about the process-start side effect. 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 description coverage is 100%, so all four parameters (seconds, session, until_idle, include_thinking) are already documented in the schema. The description loosely echoes the collection modes ('思考增量' maps to include_thinking) but adds no syntax, default, or interaction detail beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb and resource (subscribe to a session's event stream and collect generated content for N seconds) and states the scope of what is captured (text deltas, thinking deltas, tool calls). The 'where is it now' framing clearly separates it from static siblings like piweb_get_session or piweb_status.

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

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

It gives a concrete when-to-use cue ('适合「它现在跑到哪了」'), which points the agent at live monitoring rather than a snapshot. It does not, however, name an explicit alternative (e.g., piweb_get_session for a one-shot read, piweb_wait_for_reply for blocking) or state when not to use it.

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