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

Annotations already declare destructive=true and idempotent=true, but the description adds substantive context beyond them: identical IDs query while changed content rejects, close-each-prompt handling for AWAITING_INPUT, pause/query behavior for service UNKNOWN, and a strict host approval-timeout retry rule. It discloses real operational constraints, though several clauses are cryptically worded.

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?

After a serviceable first sentence, the description collapses into a single dense run-on covering parameter shapes, error states, and maintenance policy with no headings or sentence breaks to front-load the essentials. Every clause carries content, but the wall-of-text structure makes the critical routing and parameter information hard to locate.

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?

An output schema exists, so return values need not be explained, and the description does cover error states and many action parameter shapes. It is still incomplete for a 34-value action enum with 0% schema coverage: several actions and the top-level identity fields (action_id uniqueness expectations, experience_refs, view) are not fully specified.

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 burden and largely succeeds by enumerating per-action parameter shapes (select={region,positions}, reorder={region,order}, blind={blind_slot}, buy/sell/use/take={region,position}, select_setup_option={kind,position}, and the positions-v1 form for play/discard). It leaves the top-level observation_id, action_id, and experience_refs semantics only partially implied.

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 gives a specific verb and resource: 'Submit one native action bound to current observation_id, unique action_id...'. An agent understands this dispatches a game action, which is distinguishable from siblings like observe and action_status, though the term 'native action' is jargon that is never defined.

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 guidance is embedded but scattered: 'Choose current visible unlocked candidates; native settings only. Random non-challenge' and the AWAITING_INPUT/Service UNKNOWN recovery flows. However, it never explicitly states when to call act versus action_status, observe, or wait_until_ready, so the agent must infer the 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 cover the safety profile (readOnly, idempotent, non-destructive, non-open-world), so the description earns credit for adding failure semantics instead: session changes or missing records resolve to UNKNOWN, and there is no cross-process exactly-once guarantee. That is genuinely useful context an agent could not get from the 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?

Dense and front-loaded in two short clauses, with the core action ('query... never replay') stated first and the caveats second. No filler, though the compressed phrasing borders on cryptic.

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?

An output schema exists, so return values need not be explained. However, with 0% schema description coverage on two parameters and no explanation of the action_id semantics or the view filter, the definition is under-specified for correct 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%, so the schema documents nothing about either parameter. The description's phrase 'filtered feedback' weakly gestures at the optional view parameter but never explains action_id format, validity, or what view values do, leaving both parameters effectively undocumented.

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

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

States a specific verb and resource ('query an action record in this game session'), but 'action record' and 'filtered feedback' are vague jargon. The 'never replay it' clause hints it is a status read rather than a re-execution, but it does not clearly distinguish it from siblings like observe, act, or health.

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 only usage signal is the embedded 'never replay it', which vaguely implies you should not use this to re-run an action, but no alternative tool is named and no when-to-use context is given. An agent must infer how this relates to act, observe, or health.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds behavior beyond that: hard limits (200 values / 1000 population), the sampling semantics of hypergeometric ('uniform sampling without replacement'), and explicit rejection behavior for unknown/nonfinite values, zero divisors, extra fields and limit breaches — all useful for anticipating errors.

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 with zero filler, but the structure is a semicolon-chained run-on and leads with a constraint rather than the purpose, which front-loads the least orienting information. Every clause does earn its place, so waste is minimal.

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

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

For a 2-parameter tool with an output schema and full annotation coverage, the description supplies the missing pieces: operation-to-input mapping, size caps, sampling semantics, and rejection rules. It stops short of stating error/return format, but the output schema reasonably covers returns, leaving only minor ambiguity about whether the operation list is exhaustive.

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

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

Schema coverage is 0% and the schema is nearly empty (operation is an unconstrained string, inputs is a free-form object), so the description carries the entire semantic burden and does so well: it maps each operation to its exact input shape ({values:[numbers]}, {n,k}, {population,successes,draws,min_successes,max_successes}). This compensates fully for the schema 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 enumerated operations (sum/difference/product/quotient/mean/median/variance_population, combination, hypergeometric) make it unambiguous that this is a pure arithmetic/statistics evaluator, and it is trivially distinguishable from the action-oriented siblings (act, run_plan, launch_game). However, the description never states a purpose sentence up front — it opens with a constraint ('Explicit public numbers only'), so the agent must infer 'calculates math' from the operation list.

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 strong negative guidance: 'Explicit public numbers only', 'No game/network reads, action recommendation, expressions or arbitrary code' — effectively delineating when this tool is and is not appropriate. It lacks a positive 'use this when...' statement or comparison to an alternative, but no sibling covers the same math domain, so the absence costs little.

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 cover safety (destructive/readOnly/idempotent/openWorld), and the description still adds substantial context: authorization source, no-force-kill constraint, preconditions, the 0-30s expected duration, operation_id-based deduplication, and the uncertain-response retry rule ('permits querying the identical operation only'). This is well beyond what the annotations supply.

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 authorization condition is front-loaded and every clause carries operational weight (preconditions, duration, dedupe, retry). It reads as a dense run-on that is harder to scan than separated sentences, but there is little pure 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?

An output schema exists, so return values need not be described, and the description still covers authorization, preconditions, timing expectations, failure rejection cases, and retry semantics. An agent has everything needed to decide and call correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning; it explains that observation_id must be the latest and that operation_id deduplicates retries and governs safe re-query after an uncertain response. Only timeout_s is left semantically unexplained, which keeps it short of a 5.

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

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

States a specific verb and resource ('close the verified Balatro window and confirm exit') and explicitly bounds the action ('without force kill'). It is trivially distinguishable from siblings like launch_game or recover_lost_session 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 explicit when ('explicit user close request or standing authorization ... in docs/balatro-ai/maintenance.md') and when-not ('Reject active runs/UNKNOWN'), plus a full precondition gate: known current profile, latest observation_id, ready, normal results or idle main menu, no pending actions. Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description still adds genuine domain context: the profile-mismatch-is-informational note tells the agent mismatches are not actionable failures, and "Performs no game action" disambiguates it from action-oriented siblings.

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 with no filler, and the statement of what is read comes first. The noun list is somewhat jargon-dense but 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?

An output schema exists, so return values need no explanation. For a zero-parameter read-only diagnostic tool, the description covers what is read and its non-side-effecting nature; the only gap is the absence of explicit routing against sibling diagnostics.

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

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

Zero parameters, so the baseline is 4. There is nothing for the description to compensate for, and the schema is fully self-describing.

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

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

Names a clear verb (Read) and enumerates the specific artifacts returned: connection state, fixed versions, native profile, and historical test-profile comparison. It does not explicitly contrast itself with siblings like observe or action_status, but the resource content is distinctive enough to identify the 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?

Override implicit context, but no explicit when-to-use. "Performs no game action" hints at a safe diagnostic use case, and "A profile mismatch is information only" tells the agent not to react to mismatches. However nothing says when to prefer this over observe or action_status.

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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing that a permitted launch opens an independent activity window, that closing/failing that viewer never controls gameplay, and exactly what it displays. It also states the durable operation_id dedup semantics and enumerates what the tool will NOT do (no game clicks, pending-action deletion, paths, commands, process IDs).

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?

Extremely dense and run-on, mixing launch behavior, window policy, timeout, dedup, and negative constraints into long clauses. Much is load-bearing, but the front-loading is weak and phrases like "No game clicks, pending-action deletion, paths, commands or process IDs" are cryptic fragments rather than clean structure.

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?

An output schema exists, so return values need not be explained, and the description still covers the already-running/UNKNOWN branches, the lifecycle of the activity viewer, the timeout bound, and dedup behavior. Reasonably complete for a launch tool, though the failure/timeout outcome path 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 0%, so the description must compensate, and it does for both parameters: timeout_s is bounded ("0-30 seconds") and operation_id's dedup/query-only semantics are spelled out. This adds material meaning the bare schema lacks.

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 (launch the game) tied to a concrete Steam AppID and defines the core behavior "launch normally and wait for MCP." It implicitly contrasts with the already-running path, but does not explicitly name the obvious sibling (close_game) to disambiguate.

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 conditional guidance for one branch ("If already running, verify/show its window; UNKNOWN allows only restoring that window") and notes the dedup query path. However, it never states when to prefer this over siblings like run_plan, wait_until_ready, or recover_lost_session, so selection is left to inference.

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

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: unknown profiles are reported, hidden information such as deck order and seeds is excluded, and server_time is wall-clock metadata rather than thinking time. Some phrases remain ambiguous, keeping it from a 5.

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

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

The purpose is front-loaded in the first sentence, and the remaining sentences add relevant constraints without obvious padding. Some wording is dense and jargon-heavy, but the overall structure is efficient.

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 state-observation tool with an output schema and strong read-only annotations, the description covers observation scope and data exclusions well. It is incomplete because it omits any explanation of the view parameter, which is the only input an agent must choose.

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% and the single parameter "view" is never mentioned or explained in the description. With no schema-level description to compensate, the description should clarify what view values mean or what compact/default does, but it does not.

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: "Read the player-visible state of the current identified native profile." It also clarifies scope by excluding hidden information. However, it does not explicitly differentiate this tool from siblings such as action_status or act, 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?

Usage is implied by the game-observation context, but there is no explicit when-to-use guidance or comparison to alternatives like action_status or act. The mention that server_time is usable for run timing is a partial usage clue, but not a 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 already declare readOnly/idempotent/non-destructive, yet the description adds substantial beyond-schema behavior: revision is an update counter with no retained history, views differ in what they omit, full returns a Chinese Markdown guide, and query is literal and capped at 80 characters. This is genuine added context, though pagination and scoping rules are stated in dense fragments rather than cleanly.

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 run-on wall of semicolon-separated clauses with a confusing opening sentence that spends space on environment chatter rather than the tool's function. Key facts are present but not front-loaded or organized, hurting 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?

Given an output schema exists, return-value detail is less critical, yet the description still specifies per-view outputs and omits fields appropriately. Combined with the parameter and behavioral coverage for a 6-param, 0%-coverage schema, an agent has enough to call it correctly, though the muddled purpose statement leaves a small gap.

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

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

With 0% schema description coverage across 6 parameters, the description carries the full burden and largely succeeds: it explains kind (experience vs TEST), view modes, query length/format, offset continuation ('continue with next_offset'), note_ids semantics (omitted = all, [] = none), and revision meaning. Some fields remain under-specified (exact accepted view/kind strings are not enumerated).

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 tool clearly reads notes/experience topics and the description implies a read operation, but the opening ('Actually read disk, local experience over read-only baseline; TEST is separate') is cryptic and never states plainly what read_notes does. It never names its write counterpart write_note, so differentiation from siblings is left to inference.

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?

Offers concrete sequencing guidance ('Read EXP-GENERAL-GUIDE first, then relevant topics') and disambiguates views (index = previews only, strategy = actionable rules, content/full = audit). It stops short of an explicit when-not-to-use or a direct pointer to a sibling, so it lands below the top tier.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, openWorld=false, and the description meaningfully extends these: identical recovery_id/parameters hit the durable receipt (explaining idempotency), no game action/replay/save read occurs, and RETIRED is explicitly not success. It also states the authoritative rejection cases. It stops short of explaining what state is written or how the receipt is returned.

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 text is a dense, run-on block of jargon-heavy conditions with no front-loaded statement of purpose; the reader must parse every clause before knowing what the tool does. Several sentences ('A missing record alone never proves non-submission', 'RETIRED is not success or a normal loss') are important but buried rather than structured.

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?

An output schema exists, so return values need not be explained, and the description does supply substantial precondition and semantics context. However, it omits any clear statement of the tool's own operation and leaves all three parameters undocumented, which is insufficient for a 3-required-parameter mutation tool with 0% schema coverage.

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 all three required parameters, so the description must carry the burden and largely does not. It hints that recovery_id is the key that makes calls idempotent and that observation_id must be a 'fresh observation', but action_id is never explained and no format or provenance is given for any parameter.

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 never plainly states what the tool does (e.g., 'records a retirement decision for a lost session and returns the durable receipt'). Almost every sentence is a precondition, warning, or exclusion, so the agent must infer the core operation from phrases like 'Retire only after...' and 'query the durable receipt'. The name recover_lost_session is not clarified or distinguished from siblings such as action_status or observe.

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 explicit gating conditions: 'Retire only after actual session change and confirmed record loss, with known current profile, fresh observation and ready', plus exclusions ('Reject live old sessions, stale observations or unknown profiles') and a mandated prerequisite step ('First query action_status and observe'). Alternatives are named only as precondition steps, not as competing tools, so it stops short of a full when/when-not/alternative map.

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 idempotentHint=true and destructiveHint=false, and the description is consistent with them while adding substantive context: revision-guarded writes via expected_revision (first 0), unique write_id dedup, size caps of 2000 UTF-8 bytes / 200 chars per item, and an explicit scope exclusion ('No strategy generation or game action'). It does not say what a conflicting revision does or what is returned, so it stops short of full transparency.

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?

Information density is high and the tool's function is front-loaded, but the text is a chain of clipped fragments and bracketed jargon ('read actually reads disk; omit other parameters', 'expected_revision(first 0)') that demands parsing. Several sentences would need rereading, which is a structure cost even if little is wasted.

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

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

An output schema exists so return values need not be described, and the description covers the hard parts of a stateful read/write tool: preconditions, revision safety, dedup by ID/content, invalidation triggers, and size limits. The remaining gaps (mode value set, revision-conflict behavior) are minor given the overall coverage.

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% and no parameter has an enum, so the description carries the full burden and largely meets it: mode read/write semantics, content sub-keys (objective, priorities[1-4], recheck_when[1-4], experience_refs up to 6 read EXP-XXX@rN), observation_id freshness, expected_revision initial value, and write_id uniqueness. It still never enumerates the legal mode strings or types, leaving some inference to the agent.

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 identifies a specific resource (run memory) and distinguishes its two modes: 'read actually reads disk' versus the write path with its required fields. It is telegraphic and the opening phrase 'Model-authored short run memory' is a little opaque, but an agent can tell this is a read/write store for the current run rather than the generic read_notes/write_note siblings.

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 real preconditions ('Only confirmed start_run/continue_run, actionable current run, no pending action') and lifecycle rules ('Revise on material changes, read after compression', 'Run/profile/session changes invalidate reuse but retain history'). What is missing is an explicit contrast with adjacent tools like write_note or read_notes, so the routing to a sibling 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?

Annotations already declare the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description's real value is the added behavior: polling semantics, the 10s default / 30s cap, and the explicit warning that readiness does not equal action completion. That caveat is a genuinely useful behavioral disclosure beyond the 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?

Three short, information-dense sentences with no filler. The core operation is front-loaded, followed by timing bounds and then the readiness caveat, which is the right order of importance.

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 an output schema present, explaining return values is not strictly required, and the description still summarizes states (ready, timeout, disconnected, unsupported) for quick scanning. It is nearly complete for a 2-optional-param, zero-required tool; only the view parameter's effect is left unexplained.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It partially compensates by giving the timeout default (10) and cap (30), but never explains the 'view' parameter or its 'compact' default, nor the relationship between 'normal UI' and view modes.

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: 'poll read-only until normal UI is actionable', which tells the agent exactly what operation occurs. It does not name or contrast itself with siblings like observe or action_status, so the agent must infer the boundary, but the purpose itself is unambiguous.

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 only implied — the polling/readiness framing suggests calling it after launch or before an action, and the caveat 'readiness alone does not confirm an action completed' clarifies interpretation. There is no explicit when-not or pointer to an alternative sibling, leaving routing to inference.

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

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

Beyond the annotations (idempotentHint=true, destructiveHint=false), the description discloses substantive behavior: full-content replacement rather than merge, old versions not copied, and receipts deduplicating write IDs without retaining prior strategy content. This explains what happens to prior data, which the annotations alone do not. It stops short of stating auth requirements or failure/rejection behavior.

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

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

Roughly fourteen packed sentences that mix the core write semantics with migration notes, TEST run-ID conventions, Chinese-guide scope, and receipt behavior. The purpose is in the first sentence but immediately diffuses; several clauses ('TEST remains separate', 'Formal run IDs start n5-') do not help an agent invoke this tool.

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?

An output schema exists, so return values need not be explained, and the description does note the default strategy response omits audit fields. For a 6-parameter, nested-object, revision-controlled write, though, key parameter meanings (note_id, kind, view) and the exact create path (expected_revision=0) are left unclear.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning. It partially does: content's sub-fields (sources, facts, interpretation, conditions, counterexamples, confidence, revision_reason), expected_revision ('updates require current expected_revision'), and write_id (receipt dedup) are addressed. But note_id, kind, and view are never explained, leaving the compensation incomplete.

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 conveys a specific verb and scope (atomic replace of a note's local current content under revision control) rather than a tautology. However, it never clearly names the resource as a 'note' matching write_note, and it buries the core purpose under tangents about Chinese guides, migrations, and run-ID conventions. An agent must read several sentences to extract the essential action.

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 conditional guidance: '0 creates; updates require current expected_revision', 'Before amending, explicitly read content/full', and 'Legacy local data requires the maintenance migration'. These imply when the tool applies, but no sibling alternative is named (e.g., read_notes) and the create-vs-update branch is stated obliquely rather than as an explicit rule.

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