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

Well beyond the readOnlyHint annotation, the description discloses that the 'latest' field is fetched from GitHub at most once per day (a rate-limited network call), and that the tool records state when returning notified=false. Those are exactly the non-obvious traits an agent needs. The internal bookkeeping write is in mild tension with readOnlyHint but is framed as non-destructive notification tracking, so it reads as disclosure rather than contradiction.

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?

Almost every clause carries real information, but it is delivered as one dense run-on paragraph with stacked nested parentheses (profit: 利用枠…（…）・…（…）), which makes it hard to scan. Splitting the status fields from the version fields into separate sentences would cost nothing and gain a lot.

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 full return-value burden and largely succeeds: it names each field group and explains the ambiguous ones (version sub-fields, profiles null semantics). Only the dense packaging and the missing 'call before start_session' framing keep it from a 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?

Zero parameters, so the baseline of 4 applies. The description instead spends its words on output-field semantics — what null means for pauseAtPct and for profiles in start_session versus send_message — which is useful but belongs to the return contract, not parameter interpretation.

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 read operation and enumerates the specific payload: per-window usage rate and reset time, free memory, running-conversation count, canStartNew plus reason, and watchIntervalMin. That is far more specific than a tautology, and no sibling (list_sessions, report, wait_events) covers this status surface. It loses a point because the purpose statement is buried under an equally long version-field enumeration, so the primary 'what' is not front-loaded.

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

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

There is no explicit 'call this when…' or 'use X instead' routing; the reader must infer that this is the pre-flight check before start_session. What guidance exists is operational rather than selection-oriented: pauseAtPct null means do not stop on quota, and the notified/reloadNeeded/updateAvailable combination dictates telling the user. Implied rather than stated usage earns a middle score.

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, so the safety profile is covered; the description adds substantial behaviour: that pending and finished managed sessions have their status deliberately not read, the tri-state meaning of due (true/false/null=unknown), that finished TODOs appear only with includeArchived, and the exact status vocabulary including activeFlags. This goes well beyond the annotation, though propagation/latency behaviour of status is unstated.

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

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

Purpose and default scope are front-loaded in the first clause, and every subsequent clause carries new semantics (statuses, TODO tri-state, handoff head). It is a dense single paragraph that runs together return shape, semantics, and permission notes, so it is efficient but slightly hard 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?

With no output schema, the description carries the burden of describing returns, and it does cover status values, activeFlags, the todos array with due, and handoff — enough to interpret the response. It still omits what a session item actually contains (ids, names, timestamps), so an agent can't fully predict the payload shape.

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% (cwd and includeArchived documented, scope and limit not), so the description must compensate — and it does for the highest-risk parameter by spelling out both scope values and their defaults, plus extending includeArchived's meaning to finished TODOs in managed mode. limit's default/purpose is left entirely to the schema.

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

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

The opening sentence names a specific verb and resource (会話の一覧と状態を返す) and immediately distinguishes the two modes by what each returns, so the agent knows this is a list-plus-status read. It does not name a sibling (e.g. read_session for a single conversation's detail), so the boundary with siblings is left implicit.

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 when each scope applies: managed for supervisor-tracked conversations plus TODO/handoff, all for this PC's conversations in newest order, and ties cwd to scope=all. It also pre-empts a likely doubt by saying the tool may be called from a non-supervisor session — but no explicit 'use X instead when…' routing to read_session or wait_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?

The description usefully discloses ordering (newest-first), the default unread filter, and the limit cap. However, it also states that the call advances a read marker ('読んだ印を進める'), a state mutation, while the annotations declare readOnlyHint=true — conflicting signals about whether calling this changes anything. The primary read nature is consistent, but the cursor side effect is not reconciled with the annotation.

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

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

Three short clauses, zero padding, with the core action and the default behavior front-loaded. Every sentence corresponds to a decision the caller has to make.

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 read tool with no output schema, the description covers filtering, ordering, and count, which is most of what is needed. It omits what a report record contains and whether the marker advances when all=true is used, which matters given the sibling 'report' tool that presumably writes them.

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

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

Schema description coverage is 0%, so the description carries the full burden and does it well: it explains that 'all' toggles between unread-only (the default) and everything, that results come newest-first, and that 'limit' bounds the count. Only the interaction between all=true and the read marker, and the limit bound of 500, are left to the schema.

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

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

The description gives a specific verb and resource ('作業の会話からの報告（report）を読む') and scopes reports to work conversations, which separates it from the session-reading siblings like read_session. It stops short of naming a sibling it must not be confused with (e.g. report vs read_reports), so it is clear but not fully differentiated.

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

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

It explains the selection logic between the two modes — default returns only unread and advances the marker, all=true returns everything newest-first up to limit. That is useful parameter-selection guidance, but there is no explicit when-to-use/when-not-to-use versus alternatives in the sibling set (read_session, list_sessions, report).

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 readOnlyHint annotation, the description discloses truncation behavior (long text is cut keeping the tail), platform-specific semantics (Codex is per turn, Claude Code returns recent claude logs), and a special mode that returns the line hitting usageLimit. These are operational traits an agent cannot infer from the annotations or 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?

Four dense sentences, front-loaded with the core action and use case, followed by operational caveats. Every sentence carries information, though the platform-specific notes are somewhat compressed.

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, the description explains what content is returned, how it is truncated, and platform differences. The only notable omission is any explanation of the required threadId parameter, which is likely obvious but left unstated.

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

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

With only 33% schema description coverage, the description partially compensates by tying `turns` to Codex only and implying truncation via `maxChars`. However, `threadId` is never explained and `maxChars` semantics (default 6000, tail-keeping) remain implicit, so the gap is only partially filled.

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 the recent exchanges of a conversation, including request text, AI replies, state, errors, and questions. An agent can tell this apart from siblings like list_sessions or send_message without opening any schema.

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

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

Gives a clear context for use: to distinguish whether a session crashed, is waiting for a decision, or has finished. It does not name an alternative tool for the cases where this one is not appropriate, so it falls short of 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?

Annotations only mark this as a write operation (readOnlyHint=false), but the description adds meaningful behavioral detail: each kind has distinct semantics (e.g., question requires waiting for user judgment, done includes results and remaining work). It does not cover auth or rate limits, but it clearly describes what gets written and the different reporting modes.

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: the first sentence states the purpose and caller context, and the second enumerates the kinds with concise definitions. No redundant sentences; every element serves a clear purpose.

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 write-only reporting tool with no output schema, the description provides enough to call it correctly: it explains the kinds, the waiting behavior for 'question', and the expected content. It could mention how the report is delivered or whether it blocks for other kinds, but no critical information 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 50%, and the description compensates by thoroughly explaining the kind enum values and what each implies (e.g., question should contain question, options, and recommendation; done should contain results and remaining work). It also indirectly guides what to put in the required text parameter per kind, though from/threadId are left to the schema.

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

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

States a specific verb and resource: writing a report to a supervisor (監視役へ報告を書く). Context is scoped to 'work conversations' (作業の会話が使う), which helps distinguish it from general messaging tools, but it does not explicitly name a sibling like send_message for contrast.

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

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

The description gives usage context (work conversations) and defines when to use each kind (progress, question, done, blocked), which is helpful. However, it never explicitly compares to alternatives like send_message or read_reports, so the agent must infer that this is the reporting channel rather than a general message.

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 tell us this is a mutation (readOnlyHint=false); the description supplies the behavioral detail the annotation lacks: queuing vs. starting a turn, the Codex-only steer restriction, and that model/effort changes persist to later continuations (with per-runtime caveats). It says nothing about what the call returns or failure handling, which is a moderate gap.

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

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

The key mode behavior is front-loaded, but the second half is a dense parenthetical chain of runtime-specific caveats (Codex/Claude Code, '預かって届けるときから') that is hard to parse. Every claim is relevant, but the packaging costs readability.

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

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

For a mutation tool with no output schema, the description covers the important state transitions and the side effects of changing model/effort. What an agent gets back and how errors surface are not covered, which is the main remaining hole.

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

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

Schema coverage is 50%, and the description compensates well: it defines the meaning of mode values including the default, and explains that profile/model/effort change the model for this request onward, with model and effort taking precedence (matching the schema notes). Only message and threadId, which are self-evident, go unexplained.

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

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

The opening clause names a specific verb and resource: sending a message/request into a conversation. It is clearly distinct from siblings like start_session or read_session, though it never explicitly names 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?

It spells out how mode="auto" behaves (queue on a running conversation vs. start a new turn on a stopped one) and when mode="steer" applies (interrupting a running turn, Codex only). It stops short of routing between this tool and siblings such as start_session or wait_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?

readOnlyHint=false already signals a mutation. The description contributes beyond that by disclosing that the underlying Claude Code session is not actually renamed—only the monitor's record changes—which prevents a false assumption. It says nothing about permissions, persistence, or failure behavior when threadId is invalid.

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 with the purpose first and the important caveat parenthetically attached. Nothing extraneous, though the caveat could be clearer about impact on the caller.

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

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

For a mutation tool with no output schema, 0% parameter coverage, and an unaddressed sibling overlap with update_session, the description leaves too much to inference for reliable invocation.

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% for two required parameters. The description implies 'name' maps to the conversation name but never explains what threadId identifies or its format, so it fails to compensate for the documentation 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?

The description names a specific verb and resource (rename the conversation's name) and adds a genuinely useful caveat that it only changes the observer's record, not the Claude Code session itself. It does not, however, distinguish this from the sibling update_session, which appears to overlap.

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

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

There is no guidance on when to use this versus update_session, no prerequisites (e.g., must the session exist or be active), and no when-not-to-use conditions. The agent must infer the selection from the name alone.

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 description adds substantial behavior beyond the readOnlyHint=false annotation: the new conversation is independent and continues after the current conversation ends, resource shortages cause refusal with a reason unless force=true, names must not collide with managed conversations, and via="app" returns appStart/record values instead of starting the session. This is exactly the kind of mutation and side-effect context an agent needs before invoking start_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?

The description is front-loaded with the core action and then covers profile/model precedence, persistence, resource gating, name uniqueness, and the app-mode fallback. It is dense but appropriately sized for a 13-parameter tool with complex behavior. Some parenthetical elaboration could be trimmed, but most sentences carry operational value.

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 13-parameter tool with no output schema, the description covers the important behavioral contract: resource gating, force override, name uniqueness, conversation persistence, and app-mode return values. It does not describe the normal successful return shape, which leaves a small gap. Given the rich schema coverage, this is still a fairly complete definition.

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 very high at 92%, so the schema already documents most parameters. The description still adds meaningful semantics around the key interactions: profile comes from get_usage, model and effort override profile, force bypasses resource checks, and via="app" changes the tool's behavior. It does not explain every parameter, but it improves understanding of the most consequential ones.

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 first sentence states a specific verb and resource: creating a new work conversation and sending its first request, with name, working folder, model, and effort named. It also distinguishes this from continuing the current conversation by saying the new conversation runs separately and persists after this one ends. The special via="app" behavior further clarifies that this tool may not start a session directly in Claude Code desktop mode.

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 usage context: prefer a profile from get_usage that matches the work type, model/effort override profile, and force=true bypasses resource gating. It also describes the via="app" default and the appStart/record handoff. It does not explicitly compare against siblings such as send_message or update_session, so it stops short of full when/when-not guidance.

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

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

With only readOnlyHint=false available, the description carries meaningful behavioral context: the turn stops, the conversation persists, a management state is recorded, and paused_usage affects later wait_events behavior. It does not describe interruption timing or error behavior, but it adds substantial value beyond the annotation.

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

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

The description is compact and front-loaded: it states the stop action first, then clarifies persistence and continuation, then explains markAs. Every sentence adds useful information without repetition.

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

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

For a two-parameter mutation tool with no output schema and minimal annotations, the description covers the key behavioral outcomes and the non-obvious markAs option. It leaves threadId semantics and return/error behavior implicit, but the essential context for correct invocation is present.

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 markAs thoroughly, including the default and the special paused_usage semantics, but threadId receives no added meaning beyond its name.

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 precise verb and scope: it stops the currently running turn, not the conversation itself. It also explicitly distinguishes the outcome from deletion by saying the conversation remains and can be continued with send_message.

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 usage guidance for markAs, including the default paused state and the paused_usage case tied to quota recovery and wait_events. It also names send_message as the continuation path, though it does not compare against other session-management siblings such as update_session.

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 single readOnlyHint=false annotation, the description discloses the deferred-execution model (conditions fire as todoDue / roomAvailable through wait_events) and the consequential auto=true behavior ('そろったら聞かずに進める'). The subtle version/restart semantics ('足した会話を開いたまま新しい会話を始めただけでは数えない') are exactly the kind of side-effect detail annotations cannot convey.

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

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

The purpose and action list are front-loaded and the quoted action labels give the dense block visible structure. It is still a single long paragraph with no line breaks, and the when.type catalogue could be tabled, so it is efficient but not maximally 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 an 11-parameter tool with a nested when/start object and no output schema, the description covers actions, trigger semantics and event delivery thoroughly. Missing are the return shape after add (an id for later update/done/remove) and the meaning of note/cardAt, which an agent may need to use the tool fully.

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 82%, so the baseline is 3, and the description adds real meaning on top: all seven when.type values get operational definitions that the bare enum does not provide, and the pr/cwd/repo relationship is spelled out. It leaves gaps for note, by, cardAt and start's internal shape, so it does not fully compensate for the remaining uncovered parameters.

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

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

The opening states a concrete verb+resource ('TODO（あとでやること）を書く') and immediately enumerates the four actions with the parameters each takes, so an agent can tell what the tool does without opening the schema. It also names the sibling that owns the read path ('一覧は list_sessions の todos'), which cleanly separates it from adjacent 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?

Each action carries a when-to-use clause (e.g. remove = '間違えて足したとき'), and the long when.type catalogue explains the exact trigger condition for every scheduling mode, including pitfalls ('ディスクに入っただけでは数えない'). It does not, however, contrast this tool against other workflow tools like report or wait_events beyond noting that wait_events surfaces due items.

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=false annotation already marks this as a mutation tool. Beyond that, the description states what it mutates (state.json), discloses a non-obvious side effect (setting done also marks the linked TODO as done, todosDone), and explicitly says the conversation is untouched. It does not cover permissions, reversibility, or what a call returns.

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

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

The purpose is front-loaded, and no sentence is padding. But the middle of the description becomes a run-on list joined by ・, mixing field names with behavioral rules about the TODO cascade, which makes it harder to scan. Splitting that list into short labeled clauses would improve it.

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

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

The tool has 12 parameters, no output schema, and low schema coverage, so the description must do a lot. It covers status semantics and the done-to-TODO cascade well. But it remains silent about whether the update is partial or full, what state.json returns, and what the meaning of several parameters is, so the definition is not yet complete for a tool of this size.

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 only 25%, and the description explains 5 of the 12 parameters: status values (pending=保留, paused=手で止めた, paused_usage=利用枠で止めた), note, area, todo, and the via app case. That goes beyond the bare enum values. But cwd, name, model, effort, profile, remove, and the required threadId are left undefined in both the schema and the description, so the 25% coverage gap is not closed.

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 target: rewrites the supervisor's record (state.json). It enumerates the fields that can be set (status, note, area, todo link) and closes with a sharp scope boundary, 「会話そのものには何もしない」, which distinguishes this tool from send_message and stop_session. It never names a same-purpose sibling such as set_session_name, so the differentiation is partial.

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 usage guidance only for one case: adding a desktop app conversation to management via the record value returned by start_session. It does not say when this tool is chosen instead of set_session_name (which might also set a name), how the tool relates to stop_session, or whether calls can be partial updates. The guidance is implied 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?

Far exceeds the readOnlyHint annotation: explains that no model is used while waiting, that intervalMin is capped by config, that only one call may run at a time (a new call aborts the previous), that stored state counts across calls, and that reports return immediately. These operational traits are not derivable from annotations or 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?

All content is packed into a single dense paragraph with heavy parenthetical nesting, making it hard to scan. The opening term '見回り' (patrol) is vague before the specifics arrive, so it is not ideally front-loaded despite containing rich 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 complex, non-obvious polling tool with no output schema, it explains the return signals (idle, stuck, waiting, timedOut, roomAvailable, todoDue, repeat) fairly thoroughly. Minor slack remains—some signals (e.g. roomAvailable/room) are only briefly glossed—but overall it is adequate 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 coverage is already 100%, so the baseline is 3, but the description adds real meaning: it clarifies that wait=false yields only immediately-visible events, and that intervalMin cannot exceed the configured watchIntervalMin. It doesn't reiterate defaults redundantly.

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 (waits until events occur, then returns them) applied to a well-defined resource: conversation state changes, reports, approvals/input waits, memory/quota, and TODO conditions. It also distinguishes itself from siblings by noting send_message/start_session/update_session reset the stuck counter, so an agent can separate it from the messaging/management tools.

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

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

Gives clear usage context: wait=false for the desktop-app watcher polling once per event, idle=true as the signal to stop patrolling, stuck=true as the signal to stop. It also states the one-at-a-time/abort-previous rule. It does not explicitly contrast against siblings like read_reports, leaving some routing to inference.

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