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

With no annotations, the description itself carries the burden of behavioral disclosure. It states '只读' (read-only) and enumerates the exact aggregation dimensions and output metrics, which reveals the tool's behavior and return characteristics. It does not cover data-source freshness or empty-result behavior, but the core behavioral profile is clear.

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

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

A single dense sentence contains the purpose, aggregation key, full metric list, read-only marker, and intended use. There is no filler or redundant explanation, and the key behavior 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?

For a parameterless tool with no output schema, the description provides a reasonably complete picture: it is read-only, aggregates by agent, and lists all computed metrics. Minor details such as time range or exact output format are unspecified, but they are not critical for correct high-level selection and 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?

The input schema has zero parameters, so no parameter-level documentation is needed; baseline for 0 parameters is 4. The description adds context about what the tool operates on (task records) and what it returns, which further helps the agent understand invocation without requiring additional parameter detail.

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 clearly identifies a specific function: aggregate task records by agent and produce five summary metrics (completion rate, average quality, average duration, average retries, satisfaction). It is not a tautology and is distinct from siblings like agent_list or agent_scan, though it does not name them 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?

It explicitly labels the operation as read-only and states its intended use case ('供任务路由与选型建议' – for task routing and selection recommendations). This gives clear context for when to use it, even though it does not name alternative tools or provide exclusion conditions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers extensively. It discloses that invocation is non-blocking, auto-tracks tasks, retries with exponential backoff (default 2 retries), continues running in the background even if the caller detaches, and persists results to task.result/trace. It also details worker-pool assignment, busy-worker fallback, and the semantics of same_worker/auto_fallback — far beyond what annotations would have provided.

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 quite long, but it is front-loaded with the core purpose and uses labeled Chinese sections (【后台契约】,【默认worker】,【备路】) to organize complex behavioral rules. Dense parentheticals and mixed-language phrasing reduce readability slightly, but most content earns its place given the tool's 17 parameters and intricate dispatch behavior.

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 no output schema and no annotations, the description does a strong job covering return semantics: it mentions the returned task_id for reuse, task.result for final output, and the panel /api/state endpoint for retrieval. It also covers retries, timeouts, worker selection, and fallback. However, a few parameters remain undocumented (model, workdir, task_id, retry timing), and the description never states what exactly the invocation response contains beyond the task_id, leaving some gaps for such a complex tool.

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

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

Schema description coverage is only 41%, so the description must compensate. It does explain many parameters: session_id resumption, max_retries default/disable, timeout_sec for long tasks, plan_mode, same_worker, auto_fallback, fork_on_fail, auto_approval, and capture_trace. However, several parameters — model, workdir, task_id, retry_max_ms, and retry_base_ms — are left unexplained in both the schema and the description, leaving semantic gaps.

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 opens with a specific, unambiguous statement: 'Invoke any registered agent by name to run a task.' It further distinguishes itself from the run_* sibling tools by calling itself the 'Generic path over the Agent Registry' and name-driven, which clearly separates it from per-agent tools like run_codex. The reference to agent_list for discovering names adds practical purpose context.

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 explicitly frames when to use this tool versus alternatives: use the generic name-driven path when a new agent (e.g. qwen) lacks a per-agent tool, and consult agent_list to see available names. It also gives clear operational guidance: pass session_id to resume, set timeout_sec for long tasks, use plan_mode for read-only research, and control fallback with same_worker/auto_fallback. This is strong, actionable 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?

With no annotations, the description carries the behavioral burden. It discloses the output format (name, auto param, capabilities, strengths) and a key behavioral trait: it does not dispatch tasks, only prepares selection data. This is helpful, though it doesn't explicitly state read-only semantics or absence of side effects beyond the dispatch clarification.

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: purpose first, then output format, then usage. The final Chinese sentence ('不自动派单——只备齐选型数据。') is slightly redundant with the preceding 'Use it to pick the right worker' but adds a clarifying negation. Minor redundancy prevents a 5, but it's still 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 simple no-parameter list tool without an output schema, the description covers the essential context: what is listed, the output shape, and how to use it. It doesn't mention potential edge cases (empty list, permissions), but these are not critical for a basic lookup tool. The exclusion of auto-dispatch further completes the mental model.

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 tool has zero parameters, so the schema provides no semantics to clarify. Baseline for 0 params is 4. The description doesn't need to explain parameters, and it doesn't mislead about them.

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 has a specific verb ('List'), a clear resource ('all registered agents (run_* workers)'), and ties it to agent_invoke. It distinguishes this tool from siblings like agent_invoke, agent_scan, and agent_eval by clarifying it's a listing/discovery tool, not an execution or evaluation one.

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

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

Explicitly says 'Use it to pick the right worker for a task' and adds the exclusion '不自动派单' (doesn't auto-dispatch), which signals the agent should not use this to trigger work. It doesn't name alternatives explicitly, but the reference to agent_invoke and the dispatch exclusion make the usage boundary 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?

With no annotations provided, the description carries the full burden and does so thoroughly: it discloses the registry write, detection methods for bin vs endpoint types, the specific env vars checked for qwen, the return content, and the downstream rejection behavior. This is strong transparency for a side-effecting tool.

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

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

Three information-dense sentences with no filler: the first establishes purpose, scope, and side effect; the second covers detection logic and return values; the third explains downstream impact. Every sentence earns its place and the material points are 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?

The description is complete enough for an agent to select and invoke the tool correctly: it covers what gets written to the registry, how availability is computed, what is returned, and what happens when availability is false. Given the simple optional parameter and absence of an output schema, no critical operational gap remains.

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

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

The single optional refresh parameter is already fully described in the input schema, including that rescans happen by default and the parameter exists only for semantic clarity. The tool-level description adds no parameter detail beyond the schema, so the high-coverage 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?

States a specific action ('识别本地已安装的 worker CLI'), names the exact worker CLIs (claude/codex/qwen/opencode/dsh), and explains the registration side effect (AGENTS[name].available). It also declares the return payload (available + 缺失引导), which clearly distinguishes it from dispatch tools like run_claude and agent_invoke.

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 creates a clear usage context by stating that workers with available=false are rejected by run_*/agent_invoke, implying agent_scan should be used as a preflight check before dispatch. It does not explicitly contrast with sibling listing/evaluation tools like agent_list or agent_eval, so it stops short of full when-not/exclusion 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 no annotations, the description carries the full burden and does so thoroughly. It discloses persistence to memory.json mailbox, immediate wake if the receiver is blocked on inbox_wait, retention for later polling if the receiver is not waiting, optional vector-memory sedimentation, and return of a message id. These are meaningful side effects and lifecycle behaviors beyond what the schema states.

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 dense but front-loaded with the core purpose, and each clause adds a distinct fact: persistence, wake behavior, retention, optional memory side effect, and return id. The '兼容保留' parenthetical and run-on formatting make it slightly harder to parse, so it is not maximally concise.

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 7-parameter tool with no output schema and no annotations, the description covers purpose, persistence, wake semantics, retention behavior, optional parameters, and the returned message id. It omits error handling, ack behavior, and exact response shape, but those are secondary for a straightforward send-to-inbox 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?

The schema documents kind, topic, memory, and priority, and the description adds at least one non-obvious semantic: memory=true triggers automatic sedimentation into vector memory. The required to/from/body are not elaborated, but their meaning is clear from their names, and the description partially compensates for the 57% schema coverage without redundantly restating field definitions.

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 opens with a clear action: '发一条消息到某 agent 收件箱' (send a message to an agent's inbox), and further specifies persistence, wake behavior, optional fields, and return value. It clearly identifies a specific verb and resource, but it does not explicitly distinguish itself from sibling bus_send or the inbox_read/inbox_wait/inbox_ack family, so it stops short of a 5.

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

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

The description provides behavioral context but no explicit when-to-use or when-not-to-use guidance. It mentions real-time wake with inbox_wait, which implies a use case, but it never tells the agent when to prefer agent_send_message over bus_send or how it relates to inbox_read/ack. The '兼容保留' hint is too indirect to count as 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?

No annotations are provided, so the description carries the full behavioral burden. It clearly warns that restore 'overwrites current state' and marks it with DANGER, specifies that snapshots are stored as memory.json.checkpoint.<name> alongside the live file, and clarifies that shared KV/notes are not rolled back. This is thorough disclosure for a tool with destructive potential.

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 dense but organized by operation (save/list/restore), with the danger warning placed immediately before restore instructions. The mixed-language parenthetical about shared memory is information-dense and earns its place because it prevents a wrong mental model of what rollback covers. It is slightly long relative to the simple parameter set, but no sentence is filler.

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

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

Given two simple parameters, full schema coverage, and no output schema, the description provides complete operational context: file locations, naming conventions, danger semantics, and exclusions. The only small gap is that the output/return value (e.g., what 'list' returns or what a successful save/restore returns) is not described, but this is not blocking for an agent deciding whether or how to invoke the tool.

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

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

Schema coverage is 100%, so the parameters are already documented there. The description adds valuable semantics beyond the schema: the sentinel value 'list', a concrete naming example ('pre-promotion-batch'), and the default behavior of restore (false = save a new snapshot). These operational details make correct invocation much easier.

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 multi-action purpose ('Save / list / restore named snapshots of the bridge state') and scopes it precisely to memory.json (task queue + file locks + mailbox). It also clarifies what is NOT included (shared KV/notes externalized to ~/.agents/shared-memory/), which helps distinguish it from the many memory/shared-memory sibling 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?

The description gives an explicit use context: 'For audit trail and rollback before risky bulk operations.' It also explains exactly how to invoke each mode (save via name, list via name='list', restore via name + restore=true), which is strong practical routing guidance. It does not name alternative tools or exclusion cases, but there are no close siblings that overlap with this snapshot functionality.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure, and it discloses nothing. The word 'Process' gives no indication of side effects, permissions, state changes, or failure 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 extremely short, but this is under-specification rather than conciseness. A single word cannot earn credit for efficient structure because it fails to communicate any useful 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 annotations, no output schema, and a one-word description, the tool is completely underspecified. An agent cannot determine what action will be taken, what inputs are expected, or what the result will be.

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 tool has zero parameters, so the schema is trivially complete and there is no parameter semantics burden for the description to carry. The baseline of 4 for zero-parameter tools 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 is a single word, 'Process', which is a tautology of the tool name and provides no verb-resource specificity. It does not state what is processed, what action is taken, or how it differs from any of the 60+ sibling 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?

There is no guidance on when to use this tool versus alternatives. The description contains no context, conditions, or exclusions, leaving an agent with no basis for selecting this tool over siblings like task_fork, workflow_evolve, or run_codex.

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

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

With no annotations provided, the description carries the behavioral disclosure burden and does well: it declares the operation read-only, notes that already-consumed messages are included, and exposes the limit cap. It adds meaningful behavioral context beyond the schema, though it could mention ordering or return 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?

The description is a single efficient sentence with front-loaded scoping ('read-only signal/message stream replay') and compact constraint notes at the end. Every phrase contributes either purpose, filtering semantics, or usage limits—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 simple read-only listing tool with only four scalar parameters and no output schema, the description covers purpose, filter dimensions, included message state, and limit constraints. It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that agent/topic/kind act as filters, that limit controls the count of recent messages, and that agent is required by default. This adds real semantic meaning to otherwise bare schema 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?

The description clearly identifies the tool as a message-bus history reader that lists recent N messages for an agent/topic/kind, explicitly framing it as read-only replay and audit. This distinguishes it from sibling tools like bus_send and inbox_read by emphasizing historical viewing rather than sending or consuming.

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 concrete use cases (panel display, subscriber audit, history replay) and gives a key constraint: agent is required by default, limit must be ≤200. It does not explicitly name alternative tools or say when not to use it, but the read-only framing and parameter constraints provide sufficient 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 no annotations, the description carries the disclosure burden and does so substantively: it reveals broadcast wake semantics, real-time delivery to inbox_wait-suspended receivers, automatic vector-memory sedimentation, and the message-id return value. It stops short of delivery guarantees and failure/queueing behavior, which would push it to 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?

A single dense sentence that front-loads the tool identity, then parameter capabilities, then behavioral effects and return value. No filler, though the packed comma/semicolon structure makes it slightly harder to parse at a glance.

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 7-parameter tool with zero annotations and no output schema, it covers the return value and key runtime behaviors well. It omits explicit routing to sibling tools, semantics for from/body, and failure/async behavior, leaving the agent to infer edge cases.

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 71%, leaving body and from undocumented in both schema and description; the description names all parameters but only adds real semantic weight to to (broadcast) and memory (auto-sedimentation). Much of what it says reinforces schema-entitled behavior rather than filling the coverage gap.

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

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

States a specific verb and resource — message-bus send — and enumerates distinguishing features: memory vector sedimentation, broadcast via to="*", and real-time inbox_wait wake. This clearly differentiates it from siblings like agent_send_message, inbox_wait, and memory_add.

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 'full-capability' framing and feature list (broadcast, memory, kind/topic/priority) imply this is the advanced send variant, but no sibling is named and no when-not-to-use condition is given. An agent must infer when to choose bus_send over agent_send_message or memory_add rather than being told.

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

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

No annotations are provided, so the description carries the burden. It discloses that get can output raw JSONL or condensed flow, and that grep matches keywords in titles. However, it doesn't disclose side effects (likely none), auth requirements, or what happens with invalid actions. The description adds some behavioral context but not deep 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?

The description is compact and front-loaded with the core purpose, then details the action modes and the raw flag. It packs a lot of information into a few sentences without redundancy. Minor structural awkwardness in the parenthetical about raw, but overall 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 tool with 4 parameters, 100% schema coverage, and no output schema, the description covers the main usage modes and the key behavioral nuance (raw vs condensed). It doesn't describe return format, but the absence of an output schema and the action-based design make the description reasonably complete for an agent to invoke 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 100%, so the schema already documents all four parameters. The description adds context about how raw and keyword behave per action, which is helpful, but it doesn't go beyond what the schema already provides in terms of parameter meaning. Baseline 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 clearly states the tool's purpose: to run DSH chat sessions and inspect their history, with actions list, grep, and get. It distinguishes itself from siblings by naming the DSH domain and the specific actions, though it doesn't explicitly contrast with other run_* tools like run_codex or run_claude.

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 provides explicit usage guidance: 'Use when asked to recall/show what a DSH chat session did.' It also explains the action modes and the raw flag for get. It doesn't explicitly say when not to use it or name alternatives, but the context is clear enough for an agent to select it for DSH session history tasks.

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

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

No annotations are provided, so the description carries the full burden — and it delivers. It discloses that the lock is advisory, non-blocking (returns ok:false with the current holder), auto-expires after 30 minutes by default, and normalizes paths to absolute.

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 sentences, each adding a distinct fact: purpose, return contract, auto-expiry, and path normalization. No redundant phrasing or 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?

The description covers purpose, return behavior, expiry, and normalization, which is strong for a tool with no output schema. It is missing explicit agent_name semantics and a hint about file_lock_release for early release, but these are minor gaps.

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 adds meaning for file_path (normalized to absolute) and ttl_sec (default 30min expiration), but it says nothing about agent_name, leaving that parameter's purpose ambiguous.

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 opens with 'Acquire an advisory file lock' — a specific verb and resource — and immediately states the concurrency-prevention purpose. It is clearly distinguishable from siblings like file_lock_release and file_lock_list, whose names alone signal different actions.

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 'prevent two agents editing the same file concurrently' gives a clear scenario for when this tool is appropriate. However, it does not explicitly name alternatives or state when not to use it, such as when shared memory would be a better coordination mechanism.

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

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

No annotations are provided, so the description carries the full burden. It discloses the 'non-expired' filter, which is the key behavioral trait. However, it does not clarify what the output looks like, whether locks are scoped globally or per-workspace/process, or the empty-list case. Meaningful enrichment beyond the bare action is limited.

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 zero waste. The action and scope are front-loaded in the first sentence, and the diagnostic intent is appended tersely in the second. Every word 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?

With no output schema and no annotations, the description must explain return expectations, and it does not—an agent cannot know what is returned per lock (IDs, filenames, holders) or the global scope. For a diagnostics tool that is a notable gap, though the zero-parameter simplicity keeps the shortfall modest.

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 tool has zero parameters, so the schema carries nothing to document and the baseline is 4. The description adds the 'non-expired' qualifier, which serves as the closest thing to filter semantics, giving some value beyond the empty 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 ('List') and precise resource ('currently held (non-expired) file locks'), with the 'non-expired' qualifier adding important scope. The 'For diagnostics' phrase signals intent. Naturally distinguishes from siblings file_lock_acquire and file_lock_release, which are clearly different actions.

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?

'For diagnostics' is a thin tag rather than substantive guidance. It hints at purpose but does not state when to use this tool versus alternatives, nor gives exclusions. Confusion with the lock siblings is low since acquire/release are unambiguous, but the description provides no real routing help.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully adds that the lock is advisory and cooperative, and that the released holder is returned. However, it does not mention error behavior when the lock is not held, whether release is idempotent, or what happens if the file path 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?

The description is two short sentences with no filler. The core action is front-loaded, and the advisory-lock caveat is useful supplementary context that earns its place.

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

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

For a single-parameter tool with no output schema and no annotations, the description covers the main action, the return value, and an important behavioral caveat. However, it omits error scenarios and path semantics, which an agent might need to use the tool robustly. It is adequate but not 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 0%, and the description does not explain the file_path parameter beyond the implicit meaning that it identifies the lock to release. There is no mention of path format, whether it must match the path used during acquisition, or any constraints. The description fails to compensate for the schema's lack of detail.

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 ('Release') and a specific resource ('a previously acquired file lock'), and clearly distinguishes this from sibling tools like file_lock_acquire and file_lock_list. An agent can understand exactly what this tool does without additional context.

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 'previously acquired' implies the lock must have been obtained first, giving the agent clear contextual guidance. It does not explicitly name alternatives or exclusions, but the purpose is sufficiently clear that an agent can infer when to use it versus related lock 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?

With no annotations, the description carries full behavioral disclosure and delivers: idempotency, no-op instead of error for already-consumed, non-owned, or expired cases, and the postcondition that consumed messages disappear from inbox reads/wait. This goes well beyond a generic 'ack' verb.

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, each adding essential information: the core effect, the authorization/idempotency rule, and the observable consequence. There is no filler or duplication of schema details.

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 description covers the lease precondition, idempotent behavior, failure-to-error distinction, and postcondition. An agent has enough to decide when to call it and what to expect.

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

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

Schema coverage is 0%, so the description must explain the params. It does so by identifying ids as an array associated with an agent and linking them to the consumed state. It could be more explicit that ids are message ids and that agent identifies the consuming/owning agent, but it adds meaningful semantics beyond bare names/types.

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 action—marking message ids as consumed and releasing a lease—and clearly separates it from read/wait operations by stating consumed messages no longer appear in inbox_read/inbox_wait. This distinguishes it from its closest siblings without 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?

It explicitly states the precondition: only the reader that won the lease may ack, and it lists the idempotent no-op cases. It does not explicitly name alternatives or say 'use after inbox_read/inbox_wait,' but the intended context is clear from the lease and inbox references.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals that the read does not consume messages, that messages are filtered to those not leased by others, and that a 60s lease is granted or renewed to prevent concurrent double-processing. These are important side effects beyond what the schema shows.

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 with the core operation and scope. Each sentence adds meaningful detail: return contents, FIFO ordering, non-consuming behavior, required ack, lease behavior, and the real-time alternative. There is no wasted text.

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

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

Even without an output schema, the description explains what is returned ('id + 信封(kind/topic/priority)'), the single required parameter, the lease side effect, and the necessary follow-up action. For a one-parameter list/read tool, this is sufficiently complete to invoke correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the lone 'agent' parameter. It does this by stating that the messages listed belong to a specified agent ('某 agent 未消费'), making the parameter's role clear. It could more explicitly define agent format or ownership semantics, but the meaning is recoverable.

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 uses a specific verb ('列' / lists) and a specific resource ('某 agent 未消费且未被他人租约占用的消息'), while explicitly positioning itself as a non-consuming read. It also distinguishes itself from inbox_ack and inbox_wait, making its role clear relative to 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 states that after reading, the caller must confirm with 'inbox_ack {agent, ids}', and it explicitly says '实时唤醒用 inbox_wait' for real-time wakeup needs. This gives concrete direction on when to use this tool versus the 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?

With no annotations provided, the description carries the full disclosure burden and does so thoroughly: async blocking, event-driven non-blocking behavior, immediate return with 60s lease for pending messages, suspend-and-wake on bus_send/agent_send_message, timeout behavior, filter subscription semantics, exact return shape, and pointer to inbox_ack. No contradictions with annotations 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?

The description is dense but every clause adds operational information: state branches, timeout bounds, filters, return message fields, and follow-up ack tool. It is front-loaded with the core '实时唤醒读' concept, though the single long paragraph could be clearer with light structuring.

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?

Despite lacking an output schema and annotations, the description specifies the full return payload ({items, timed_out} with item fields), timeout default and ceiling, filter options, and the required follow-up ack. An agent has the information needed to invoke, interpret, and complete the consumption flow.

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 75%, and the description clarifies the undocumented required 'agent' as the target mailbox ('读某 agent 消息'), and explains that kind/topic act as subscription filters for wakeup/return rather than mere post-hoc filters. It restates some schema-provided details (wait_ms default/max), so it does not fully exceed the schema, but it compensates for the missing agent semantics.

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 operation: '读某 agent 消息' on the message bus with real-time wakeup semantics, and distinguishes itself by describing branch behavior (immediate return vs suspend-wait) and pointing to inbox_ack for consumption. This clearly separates inbox_wait from siblings like inbox_read or bus_history.

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 clear context: use this when you want to block until a message arrives or timeout, with configurable filters and timeout bounds. It does not explicitly enumerate when to prefer inbox_read or bus_history, but the blocking-versus-immediate and consumption-via-ack wording makes the intended use evident.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not state whether the listing is recursive, whether hidden files are included, whether it follows symlinks, what the output format is, or whether it has any side effects. 'List all files' is a bare statement with no behavioral detail.

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 short and front-loaded, which is good, but it is under-specified rather than concise. Every word is generic and adds no value beyond the tool name. It earns a middle score because it is at least readable and not bloated, but it fails to use its brevity to convey useful 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 tool with two undocumented parameters, no output schema, and no annotations, the description is severely incomplete. An agent cannot know what parameters to pass, what the output looks like, or how this tool behaves in edge cases. The description is not sufficient to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It does not explain what the two parameters are, what values they accept, or how they affect the listing. The phrase 'all files' is actually misleading if any parameters filter the result, and no parameter semantics are provided.

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 is a tautology: 'List all files in the current directory' merely restates the tool name 'list_files' without adding any specific verb, resource, or scope beyond what the name already implies. It does not distinguish this tool from siblings like read_file, project_search, or memory_list, and provides no information about what kind of files, where, or in what format.

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 no guidance on when to use this tool versus alternatives. It does not mention that this is for the current working directory only, nor does it suggest when to use project_search or read_file instead. The only implied usage is 'when you need to list files,' which is minimal and not actionable.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses the embedding model, that content/category/source are stored, and details the auto-category construction logic. It omits duplicate-handling and return behavior, but it provides more mechanism-level transparency than most similar tools.

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?

Every sentence earns its place: the action, the storage model, the category rule, and the intended use case. It is dense but not bloated, with the core action 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?

For a 5-parameter write tool with no output schema or annotations, the description covers the essential context: purpose, storage semantics, category behavior, and usage. Missing return-value or duplicate/overwrite details are notable but do not prevent 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 coverage is only 40% (only cwd and scope have descriptions), so the description must compensate. It does explain category auto-construction, the role of content as knowledge, and that source is stored, but leaves source's format and content's structure unspecified, limiting the compensation.

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 opens with a specific verb and resource: 'Add a memory to the shared vector store'. It further distinguishes itself through the semantic embedding mechanism and 'findable by meaning, not just keywords', which clearly separates it from keyword-oriented siblings like shared_memory_set or memory_search.

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 states when to use the tool: to 'sediment cross-agent knowledge (learnings, gotchas, decisions)' that need semantic recall. It stops short of naming alternatives or explicitly saying when not to use it, so it earns a 4 rather than a 5.

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

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

With no annotations present, the description carries the full behavioral transparency burden. It clearly discloses the destructive nature, idempotency, the '0 deleted if no match' behavior, the no-op for no args, and the explicit guarantee that a full-table delete is impossible. It could add permission or side-effect details, but the core behavioral profile is well covered.

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, with the core action stated first. Every sentence adds distinct value: mode selection, return value, idempotency, and safety no-op. There is no filler or 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 3-parameter destructive tool with no annotations and no output schema, the description is remarkably complete. It covers all invocation modes, precedence, return information, idempotency, and the most dangerous edge case (accidental full deletion). Nothing essential for an agent to call the tool 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?

The input schema already provides 100% parameter documentation, so the baseline is 3. The description adds valuable semantics beyond the schema by explaining the mutual-exclusion priority relationship among id, category, and category_prefix, and by giving a concrete batch prefix example. This extra context meaningfully improves the agent's ability to choose parameters correctly.

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 opens with a specific verb and direct object ('Delete memories from the vector store'), making the tool's core function unmistakable. It then enumerates the three modes, which distinguishes it cleanly from sibling memory tools like memory_add, memory_search, and memory_stats by showing exactly what this tool does differently.

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 strong usage guidance for when to use each mode: single row by id, exact category, or category prefix for batch cleanup, with examples like 'test:'. It also states the priority order and the no-op safety behavior. It does not explicitly contrast with alternative sibling tools, but there is no overlapping delete tool among the siblings, so the guidance is sufficient.

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

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

With no annotations provided, the description carries the full burden. It discloses the return format (id, category, source, content preview), explicitly notes no embeddings are returned, and implies read-only behavior. It could state read-only explicitly, but it's clearly a list operation with no side effects mentioned.

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 2-3 sentences, front-loaded with the purpose, then filters, then return format, then the alternative. Every sentence carries information 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?

Given no output schema, the description covers the return structure (id, category, source, content preview). All parameters are explained, filtering options are detailed, and the alternative tool is mentioned. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the category_prefix example and the '%' append behavior, and clarifies the limit/offset defaults and cap. It goes beyond the schema by giving practical usage guidance.

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 clearly states the tool lists memories in the vector store, specifies the return payload (metadata + content preview, no embeddings), and explicitly contrasts with memory_stats ('Use memory_stats for counts/breakdown'), distinguishing it from 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 provides concrete usage context: filtering by exact category or prefix with an example ('project:<PROJECT>:'), pagination via limit/offset, and directs to memory_stats for counts/breakdown. This gives clear when-to-use and when-not-to-use 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 no annotations, the description carries the burden and it does well: it discloses dry_run=true default as preview-only, requires dry_run=false to write, states the category-change side effect, and describes the return value. It does not cover failure modes or permission expectations, which is a minor gap for a mutation tool.

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

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

All information is packed into four purposeful sentences, front-loaded with the verb and effect. The dry-run warning and to_scope enumeration are concise; no filler or repeated schema 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?

For a three-parameter mutation tool with no annotations and no output schema, the description covers the full call sequence: how to get the id, what to_scope values are valid, the safe default behavior, the actual update switch, and the return payload. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds non-obvious behavior: 'platform:auto' falls back to global when content guessing fails, and dry_run semantics are tied to the preview/update workflow. It also ties id to memory_list. This is useful meaning beyond the bare schema.

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

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

States a specific verb and resource ('promote a memory') and the precise effect ('Changes one memory's category from project:X to platform:Y or global'), which distinguishes it from memory_add/delete/search/list siblings. The 'so future searches find it under the wider scope' phrase reinforces the purpose.

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

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

Gives an explicit trigger ('Use when an Agent/user judges a project-specific memory is actually cross-project common knowledge') and a prerequisite ('Find the id via memory_list first'). It lacks an explicit when-not or a named alternative among siblings, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses the lazy-loading of the ONNX model and sqlite-vec on first call, the default scope-filtering behavior, and the optional min_length filtering. These are meaningful behavioral traits that an agent would not know from the schema alone.

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 dense and front-loaded: it opens with the core semantic search capability, then covers scope filtering, optional parameters, lazy-loading behavior, and the relationship to project_search. Every sentence adds distinct value with no filler or 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 read-only search tool with no annotations and no output schema, the description covers the invocation semantics, default behavior, optional filtering, and alternative tooling. It does not enumerate the exact fields returned for each memory, but 'top-k memories by cosine similarity' plus the schema's parameter definitions give an agent sufficient grounding to call it 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?

With schema coverage at only 50%, the description substantially compensates by explaining the semantics of scope (auto-infer vs. 'global' vs. explicit project), category (exact-match filtering), min_length (with a concrete example value), and cwd (project inference). It also clarifies top_k via 'Returns top-k memories'. This goes well beyond the sparse schema descriptions.

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

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

The description states a specific verb and resource: 'Semantic search over the shared vector memory store' using a named embedding model and sqlite-vec KNN, returning top-k memories by cosine similarity. It also explicitly distinguishes itself from the sibling keyword tool project_search, making its role clear among many memory-related 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?

The description explains when to use this tool versus project_search ('Complements keyword search... for recall across agents') and gives concrete operational guidance on scope filtering, category, and min_length. It does not explicitly list exclusions or 'don't use when' scenarios, but the context is clear and actionable.

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

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

With no annotations provided, the description carries the full burden. It discloses a key behavioral trait: 'Lazy-loads ONNX+sqlite-vec on first call,' which implies a potential performance cost and side effect. It also implies a read-only operation via 'stats,' though it doesn't explicitly state no mutations. This is good coverage for a simple stats tool.

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

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

The description is concise: two sentences, front-loaded with the core content (what stats are provided), then usage context, then a behavioral note. Every sentence earns its place with zero waste.

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 the tool's simplicity (no parameters, no output schema, no annotations), the description covers the return values by listing the stats fields, the usage scenario, and the lazy-load behavior. It does not explain error handling or exact output formatting, but that is not critical for a stats tool. It is sufficiently complete for an agent to call it 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?

The tool has zero parameters, so the baseline is 4. The description correctly omits parameter details since there are none, and it does not need to add anything beyond the schema, which is already empty.

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 clearly states what the tool does: provides vector memory store stats including total count, per-category breakdown, embedding dimension, and model path. It uses a specific resource ('vector memory store') and implies a retrieval action ('stats'), making it distinguishable from sibling memory tools like memory_search or memory_add.

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 explicit usage context: 'For diagnostics and before/after bulk operations.' This tells the agent when to invoke it, though it does not explicitly name alternatives or state when not to use it. However, the context is clear and sufficient for a diagnostics tool.

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

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

With no annotations, the description carries the full burden. It discloses that ripgrep is used with a grep fallback and that output is in file:line:match format, which are useful behavioral traits. However, it does not state whether the operation is read-only (though 'search' implies it), nor does it mention performance implications, .gitignore handling, or exit behavior on no matches.

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 sentence with zero waste, front-loading the action and result format. Excellent conciseness and structure for the information provided, though it trades completeness for brevity.

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 4 parameters and no annotations or output schema, yet the description covers only the core action and result format. It omits critical details about parameter semantics, scope, and edge cases, making it insufficient for an agent to call the tool reliably.

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 explain parameters. It does not mention pattern, max, glob, or path at all, leaving agents without any understanding of how these affect the search. The only implicit hint is the word 'pattern' in the schema, but the description provides no added meaning.

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 clearly states the tool searches a project using ripgrep (or grep fallback) and returns matches in file:line:match format. It distinguishes itself from siblings like memory_search and read_file by indicating project-wide search, but it doesn't explicitly name an alternative nor detail scope (e.g., recursive, respects .gitignore).

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 guidance is provided on when to use this tool versus alternatives. The description simply states what it does without mentioning scenarios such as 'use for regex search across project files' or contrasting with memory_search or read_file. An agent is left to infer usage from the name and context.

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

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

With no annotations, the description carries the behavioral disclosure burden. It usefully discloses path confinement and out-of-root rejection, which is important for safe invocation. However, it does not explain how limit/offset affect the read, what happens for binary or missing files, or any error behavior, leaving meaningful 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?

The description is compact and front-loaded: the core action and output characteristic come first, followed by the important path-isolation constraint. Every sentence carries essential information without 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?

Given four parameters, no output schema, and no annotations, the description is incomplete for reliable invocation. It explains path restrictions but does not define line-number pagination semantics, offset behavior, or workdir usage, so an agent may still be unsure how to call the tool for non-trivial reads.

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, but it only clarifies that file_path is confined to BRIDGE_WORK_ROOT/caller workdir. The semantics of limit, offset, and workdir are not explained anywhere, and the description does not mention them, leaving the agent without enough information to set them correctly.

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 ('Read file content with line numbers') and identifies the resource (file), so an agent can tell this is a file-reading tool. It does not explicitly contrast itself with siblings like list_dir or dsh_read, but the 'line numbers' detail helps differentiate it from a plain directory listing or data-store read.

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 'For letting the other agent inspect a file' implies a use case, giving some context for when the tool is appropriate. It does not mention alternatives or state when not to use it, so the agent must infer the exact selection criteria.

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

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

With no annotations, the description carries the full burden, and it delivers: it discloses the three-layer arbitration algorithm, expert weighting rules, fallback to qwen when all workers are busy, and the exact return format (winner, arbitration layer, weight details, reason). It also states it does not create tasks, making side effects clear.

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 but uses numbered layers (①②③) to structure the arbitration logic, front-loading the purpose. It is comprehensive without being bloated, though it could benefit from bullet points for 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?

The description is complete for an agent to call correctly: it explains the return values (since there is no output schema), specifies the required candidate count, details the fallback behavior, and names the intended caller. 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 100%, so baseline is 3, but the description adds meaningful context beyond the schema: it explains the ≥2 candidate requirement, the expert weight mapping (claude=3/codex=2/others=1), optional confidence weighting, and the arbiter selection fallback—all of which are not in the schema.

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

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

The description clearly states the tool arbitrates conflicts when multiple workers give different answers, using a specific verb ('仲裁') and resource ('多 worker 对同一问题给出不同答案'). It also distinguishes itself from siblings by explicitly noting it only arbitrates and does not create tasks, and by specifying its intended caller (Orchestrator).

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 explicitly states when to use it: '供 Orchestrator 合并多 worker 并行产出时调用' (for Orchestrator when merging parallel outputs from multiple workers). It also clarifies a negative constraint ('只裁决不建任务'), which helps rule out misuse, though it does not name alternative tools explicitly.

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

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

With no annotations, the description carries the full disclosure burden and handles it well: non-blocking execution, auth env injection, automatic task tracking, session resume semantics, and a precise retry policy (triggers on 429/rate-limit/timeout, default 2 retries/3 attempts, max_retries=0 to disable). This is substantial behavioral context far beyond a minimal 'calls Claude CLI' statement.

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 verb+resource+purpose in the first sentence, then dense telegraphic fragments ('Injects auth env. Non-blocking. Auto-tracks task.'). Slightly long, but every sentence carries distinct, non-redundant information 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?

For a 12-parameter async tool with no output schema and no annotations, the description covers the core execution flow, retry behavior, and session contract. It omits the overall return contract (only the session id is mentioned as returned), how callers retrieve results, and the semantics of workdir/timeout_sec/model. The high complexity sets a high bar that is partially met.

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 25%, so the description must compensate. It meaningfully explains session_id (resume semantics, new id captured and returned) and max_retries (disable flag, default attempt count), and implies backoff timing for the retry_ms params. But roughly 8 parameters (model, task_id, workdir, timeout_sec, etc.) remain semantically opaque in both schema and description.

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 ('Async call') plus a concrete resource ('Claude CLI (claude -p headless)') with a clear task purpose ('run a task') and domain ('For reasoning/architecture'). The named CLI and the async/non-blocking qualifier let an agent distinguish it from sibling run tools (run_codex, run_qwen) without opening their schemas.

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

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

Gives clear context that this tool is for reasoning/architecture work, which orients an agent toward the intended scenario. However, it never names sibling alternatives (run_codex, run_qwen) or states when-not-to-use, so the routing guidance is contextual rather than explicitly exclusionary.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It transparently explains async non-blocking behavior, automatic retries with exponential backoff on 429/rate-limit/timeout, session resumption semantics, and that the new session id is captured and returned. It also notes max_retries=0 to disable retries. This is substantial context, though it does not disclose return value structure or file-modification side effects.

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 tight and efficient, with each clause carrying distinct information: purpose, async nature, session resumption, and retry behavior. It front-loads the action and then layers key details without redundancy. No filler or unnecessary text.

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

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

For a tool with 13 parameters, no annotations, and no output schema, the description could offer more on how task tracking works (e.g., role of task_id, how to check status) and what the return payload contains. It covers the most important behavioral aspects (async, retries, session resumption) well, but leaves workflow integration details to sibling tools and some parameters ambiguous.

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 46%, so the description must compensate. It adds meaningful semantics for session_id (resume prior session, new id returned) and max_retries (default 2 retries, 3 total attempts, 0 disables), and indirectly clarifies retry_base_ms/retry_max_ms by describing exponential backoff. However, several parameters (prompt, task_id, workdir, model, auto, timeout_sec) are not explained in the description, leaving gaps that the low schema coverage cannot fill.

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: 'Async call Codex CLI (codex exec) to run a task.' It further scopes the tool to 'batch codegen/patches' and emphasizes 'Non-blocking', which clearly distinguishes it from sibling tools like run_claude, run_qwen, and run_dsh. An agent can tell exactly what this tool does and when it is the right choice.

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 explicitly says 'For batch codegen/patches' and highlights 'Non-blocking' and 'Async', which gives clear context for when to use this tool. However, it does not explicitly name alternative tools or state when not to use it, so it lacks a full exclusionary guideline but still provides strong usage signals.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that it can REALLY write files, runs bash/pwsh, is non-interactive with no approval stall, is non-blocking, auto-tracks tasks, has no resume despite accepting session_id, and retries on 429/timeout with exponential backoff. This is far beyond minimal behavioral 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?

The description is dense but every sentence earns its place: purpose, backend rotation, sandbox boundary, async behavior, no-resume caveat, retry policy, and security warning. The core purpose is front-loaded in the first sentence, and the critical security constraint is placed at the end for emphasis.

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 description covers safety, retry behavior, async execution, and no-resume semantics well, but it does not explain how results are returned or how an agent should retrieve the output of the tracked task. With no output schema and no annotations, and 11 parameters, this is a meaningful gap despite the otherwise rich description.

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

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

Schema coverage is 55%, and the description adds meaningful semantics beyond the schema: it explains that workdir is the sandbox boundary, clarifies max_retries as 3 total attempts by default and 0 to disable, and notes session_id is accepted but starts a fresh run. It does not explain timeout_sec, retry_base_ms, retry_max_ms, or task_id, so it does not fully compensate for all undocumented 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?

Opens with a specific verb+resource: 'Async call DeepSeek DSH CLI (dsh --profile headless) to run a task.' It clearly distinguishes from siblings by emphasizing provider-rotatable backends, non-blocking execution, and workspace-write sandbox behavior, which sets it apart from run_codex, run_claude, and run_qwen.

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 clear operational context: use it for async, non-interactive tasks that need real file writes and bash/pwsh execution inside workdir. It also provides an explicit guardrail: 'Pass a bounded isolated workdir, never the main repo / a sensitive volume.' It stops short of explicitly naming when not to use it versus specific siblings, but the context is strong enough.

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 zero annotations, the description carries the full behavioral burden and delivers extensively: async/non-blocking execution, automatic task tracking, auto-edit approval mode that lands write_file to disk, session resumption semantics with id capture, and automatic retry with exponential backoff on 429/timeout (default 2 retries, 3 attempts). This far exceeds the sparse schema's 31% coverage.

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 and use cases before behavioral details; nearly every sentence carries distinct information about invocation, sessions, or retry policy. Minor defects: the mixed-language 'qwen 端点' typo and slight redundancy where the OpenAI-compatible endpoint is mentioned twice.

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 13-parameter async tool with no output schema, the description covers invocation-critical behavior well: async semantics, session id capture/return for resumption, retry tuning, and file-landing approval mode. It omits semantics for several undocumented params and the task-tracking mechanism, but an agent can invoke the tool correctly with what is provided.

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 31%, so the description must compensate — and it does for the key params: session_id (resume with preserved context), max_retries (set to 0 to disable retries), and auto (maps to --approval-mode auto-edit). However, model, task_id, workdir, timeout_sec, and prompt have neither schema descriptions nor description coverage, leaving notable gaps.

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 operation and resource ('Async call Qwen CLI (qwen --auth-type openai, Qwen Code) to run a task'). Names two concrete use cases — docs/PPT writing and image analysis — and explicitly maps one to a sibling complement ('complements vision_analyze'). An agent can tell this apart from the other run_* 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?

Provides clear context for when to use the tool ('For writing/iterating docs & PPT', 'image analysis (complements vision_analyze)') and a comparative differentiator ('qwen has real resume via --resume, unlike opencode'). Stops short of explicit when-not-to-use statements or routing to the run_codex/run_claude siblings.

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

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

With no annotations, the description carries the full behavioral disclosure burden and succeeds: it states the 0-100 score range, default threshold 80, degrade_band default 10, the exact failing interval [th-band, th), the three verdict outcomes, writeback to quality_score, and the evaluator default. This is unusually transparent.

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 leads with the core purpose, then packs decision logic, defaults, side effects, and usage routing into a few dense sentences. Every sentence earns its place and there is no filler.

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

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

For a moderate 6-parameter gate tool with no output schema, the description covers the scoring logic, verdict semantics, defaults, writeback, and downstream usage. The only minor gap is an explicit statement of the return format, but the outcome descriptions are detailed enough for an agent to act on the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: the passing/failing decision rule, the interval formula for degraded release, default values, and the quality_score writeback behavior tied to task_id. It extends the schema without repeating it verbatim.

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 opens with '质量门禁' and specifies a clear verb+resource pair: an LLM-as-judge scores an artifact against criteria. It also differentiates itself from plain LLM execution siblings by framing the tool as a downstream quality gate, so an agent can tell it apart without opening the schema.

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

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

It explicitly states '可作任务下游 gate', giving a concrete when-to-use context: after a task produces an artifact, this tool can gate it. It does not name sibling alternatives or give when-not-to-use exclusions, which keeps this from a 5.

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

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

With no annotations, the description carries the full behavioral burdenMK. It discloses the hard-interception behavior, the 'hit means blocked and not auto-releasable' rule, and the return of a list of matched patterns. It could go further by stating the all-clear behavior or any side-effect-free guarantee, but the core behavior is transparent.

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 names the behavior first, then gives the hit rule, return value, and usage context in three sentences. Every sentence contributes directly to safe invocation.

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 schemaaintx, the description gives enough context: what is scanned, how the blocklist works, what happens on a hit, and when to use the tool. It does not explicitly describe the safe/no-hit outcome, but that is reasonably inferable from the conditional wording.

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, so the schema already documents content and blocklist well. The description adds only minor extra clarity by noting blocklist entries can be strings or regex, which mostly repeats the schema's '正则/子串' wording.

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 clearly states a specific verb and resource: it pre-scans text or artifacts against a blocklist and hard-blocks on hits. It conveys the safe-scanning purpose and the blocked/not-auto-release outcome, which helps distinguish it from generic tooling, though it does not explicitly name an alternative sibling.

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 explicitly states when to use it: as a gate before automated approval, with output intended for small-model or human fallback judgment. It gives clear usage context but does not mention exclusions or name alternative scanning tools, so it falls just short of a 5.

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

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

No annotations are provided, so the description must carry the behavioral disclosure burden. It explicitly discloses the read nature of the operation and the return behavior when the key is absent ('Returns empty string if missing'). It does not describe error handling, side effects, or concurrency behavior, but for a simple read operation the key behavioral traits are made clear.

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 short sentences, with the core action 'Read a value from shared memory by key' front-loaded. The second sentence adds a useful edge-case behavior. No extraneous information is included.

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 read tool with no annotations and no output schema, the description covers the essential elements: action, parameter, and missing-key behavior. It does not explain how to obtain keys or whether values are typed, but these are not required for correct invocation of this tool. The description is sufficiently complete for the tool's simplicity.

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 input schema lists only 'key' as a required string with no property description, and schema coverage is 0%. The description adds that the key identifies the value to read, but does not provide format, length, encoding, or example. While this is minimal compensation, it clarifies the parameter's role beyond the bare schema 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 specific verb ('Read'), a resource ('a value from shared memory'), and a lookup mechanism ('by key'). It distinguishes from sibling tools such as shared_memory_set (write) and shared_memory_list (key enumeration) through the word 'Read' and 'by key'. No ambiguity remains about what the tool does.

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

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

The description implies that the tool is for retrieving an individual value by key, but it does not explicitly state when to prefer this over shared_memory_list or shared_notes_read. There is no mention of alternatives or exclusions. The appropriate usage context must be inferred from the sibling tool names and the 'by key' phrase.

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

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

With no annotations, the description carries the burden of disclosing behavior. The verb 'list' implies a non-mutating read operation, and 'currently stored' suggests a snapshot of keys. However, it does not disclose ordering, size limits, namespace scope, or whether any metadata accompanies the keys.

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 front-loaded sentence with no redundancy. Every word contributes to clarifying what the tool does.

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

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

For a zero-parameter read-only list tool, the description is mostly sufficient, but it lacks disambiguation from sibling tools like memory_list and does not clarify the return format. Given no annotations or output schema, slightly more context would improve completeness.

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 input schema has zero properties, so there are no parameters to document. The baseline for a zero-parameter tool is 4, and the description does not need to add parameter-level detail.

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 uses a specific verb ('List') and identifies the resource ('keys' in 'shared memory'). It is distinct from shared_memory_set and shared_memory_get, but it does not explicitly differentiate itself from the sibling memory_list, which may occupy a similar conceptual role.

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 provides no guidance on when to use this tool versus alternatives, and it does not mention any exclusions or distinguish shared memory from the broader memory_* family. An agent would have to infer its use solely from the name.

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

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

With no annotations, the description must carry the disclosure burden. It does state that the operation is a store (state-changing) and that the data lands in shared memory, but it does not mention overwrite behavior, persistence, or limits. The main gap is whether setting an existing key replaces the old value.

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 contains all essential information with no filler. Every part contributes to understanding the tool's 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 simple set operation with two self-explanatory string parameters, the description is nearly complete even without an output schema or annotations. The only notable omission is the overwrite behavior for an already-existing key.

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 description adds almost no parameter-level meaning beyond the parameter names themselves. It does not explain key naming conventions, value size, or encoding, leaving the two simple string parameters without semantic guidance.

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 uses a specific verb ('Store') with an explicit resource ('a key/value pair in shared memory') and immediately distinguishes the tool's scope by noting the memory is visible to both Codex and Claude. This separates it from siblings like shared_memory_get and shared_memory_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?

The phrase 'visible to both Codex and Claude' clearly identifies the intended use case: cross-agent shared state. It provides clear context for choosing this tool over more local memory variants, though it does not enumerate exclusions or name alternatives explicitly.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It explicitly discloses append-only behavior and automatic timestamping, which helps an agent avoid assuming overwrite semantics. It does not cover failure modes or permissions, but for a simple append operation this is meaningful 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?

The description is one compact sentence with no filler. The core behavior is front-loaded, and the tag guidance is directly actionable.

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 two-parameter append tool, the description covers the essential action and tag convention. Still, with no annotations and no output schema, it leaves unspecified what the tool returns and when it should be preferred over closely related siblings.

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 gives a concrete tag format ('handoff:<id>') and identifies note as the content being appended, but it does not describe note's format, length limits, or the effect of omitting tag.

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 ('Append'), a specific resource ('shared notes'), and key behavior ('append-only'). It clearly distinguishes this from sibling shared_notes_read and other memory operations.

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 tag convention 'Use tag like handoff:<id>' gives relevant format guidance, and the append-only wording implies a writing operation rather than a read. However, it does not explicitly state when to use this tool versus shared_notes_read or shared_memory_set.

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

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

With no annotations, the description carries the full behavioral burden, but it only states the operation and parameter. It does not disclose return shape, tag-matching semantics, whether no tag returns all notes, or any error or permission 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?

Two short sentences with no filler. The primary action is front-loaded and the optional parameter is stated directly, so every word earns its place.

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

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

For a simple read tool with one optional parameter, the description is minimally viable: an agent can invoke it with or without a tag. However, with no output schema or annotations, it omits the return format and tag-matching details, so it is not 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?

Although schema coverage is 0%, 'Optional tag filter' does add meaning to the tag property by stating it is optional and used to filter results. It stops short of defining exact matching behavior, but for a single optional string parameter it provides a workable baseline.

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 action ('Read'), a concrete resource ('shared notes'), and an optional narrowing tag filter. This is enough to distinguish the tool from shared_notes_append, shared_memory_get, and 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?

There is no guidance about when to use this tool instead of related read tools or when the tag filter should be supplied. The only hint is the word 'Read', which leaves selection between shared_notes_read, memory_search, inbox_read, and read_file to inference.

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

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

With no annotations, the description carries the full burden. It discloses the state transitions (approve → completed and releases dependents; reject → back to running for redo), records the approver, and explicitly notes that it rejects a non-awaiting task. This is strong behavioral context, though it does not mention error details or whether the operation is idempotent.

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 sentences, front-loaded with the phrase 'DAG acceptance gate' which immediately orients the agent. It uses compact parentheticals for outcomes and includes the edge-case behavior in the second sentence. Zero filler, every word 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?

The description covers the core flow and the reject condition, which is the heart of the operation. However, it leaves `note` and `attempt_id` semantics undefined, and does not mention what the response looks like or any potential side effects beyond releasing dependents. Given the tool's complexity (5 params, state transitions), this is adequate but not 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 0%, so the description must explain parameters. It explains `decision` (approve/reject) and `approver` (recorded), and `task_id` is self-evident from context. However, `note` and `attempt_id` are not explained at all, leaving their purpose and format ambiguous. The description adds value for two key params but fails to cover two others.

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 clearly states the tool's purpose: it is a DAG acceptance gate that acts on tasks in `awaiting_approval` state, with two decision outcomes (approve→completed, reject→back to running). It distinguishes itself from siblings by specifying the exact state and the binary decision, making it 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?

The description explicitly states the precondition (task must be in `awaiting_approval`) and the behavior when that precondition is not met ('Rejects a non-awaiting task'). However, it does not explicitly name alternatives like `task_decide` or `task_complete`, leaving some routing to inference. The condition is clear but exclusions are 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?

With no annotations, the description correctly carries the burden and discloses the state transition, claimant recording, and rejection behavior. However, it leaves important behavioral details ambiguous: what 'blackboard auto-claim' means, concurrency/locking behavior, and what happens on success or failure are not specified.

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 sentences with no filler: first the core action, then the transition/effect, then the rejection condition. It is front-loaded and every phrase earns its place, though 'blackboard auto-claim' is slightly 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?

For a mutating lifecycle tool with no annotations and no output schema, the description covers the essential trigger, precondition, and transition. However, the ambiguity of 'blackboard auto-claim', the optionality of agent_name, and the lack of success/failure semantics leave meaningful gaps for an agent deciding whether and how to invoke 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 0%, so the description must compensate. It associates task_id with 'by id' and implies agent_name through 'records claimant', but it never explicitly names agent_name as the claimant or explains whether it is required. Some meaning is added, but the parameter semantics remain under-specified.

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

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

The description opens with a specific verb and resource: 'Claim a pending task by id.' It then clarifies the exact state transition (pending→running) and side effect (records claimant), which makes the tool's purpose unmistakable and distinguishes it from lifecycle siblings like task_complete or task_fail.

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 provides a clear precondition: the task must be pending, and it explicitly states that non-pending tasks are rejected. This gives an agent actionable guidance on when to call the tool, though it does not explicitly name alternative sibling tools for other states.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses the state transition and the semantics of the optional agent_name field in a handoff scenario. It does not cover edge cases like idempotency or behavior when the task is not running, but the core behavioral character is transparent and 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?

The description is two sentences with no filler. The main action and state transition are front-loaded, followed by the parameter nuance. Every sentence earns its place.

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

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

For a straightforward state-transition tool with only three params and no output schema, the description covers the essential invocation context: the transition, the result, and why agent_name matters in handoffs. It does not describe return values or error conditions, but the tool is simple enough that these are not critical gaps.

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 that result is the completion output and agent_name records who completed, with a concrete handoff example. task_id is not described explicitly but is obvious from the tool name and required status, making the description reasonably compensatory despite 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 description clearly states the action ('Mark a running task completed with result') and the exact state transition ('Transitions running→completed'). This distinguishes it from sibling tools like task_fail and task_claim by specifying the completion transition, so an agent can tell what this tool does without opening schemas.

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

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

The description gives clear context: use this on a running task and provide a result. It even illustrates the handoff scenario ('A claims, B completes') to explain when agent_name is useful. However, it does not explicitly state exclusions or name alternatives such as task_fail for failed tasks, stopping short of a full when-to-use/when-not-to-use guide.

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

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

With no annotations, the description carries full behavioral burden and does so thoroughly: it discloses the returned task_id, defines dependency DAG semantics (non-claimable until every dependency is terminal), and explains the approval gate lifecycle (awaiting_approval, blocking downstream nodes, release only via task_approve). This goes far beyond a generic 'create' statement.

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 purpose, then expands into the non-obvious behaviors. It is slightly wordy, especially the approval-gate paragraph with 'Explicitly new approval-criteria + require_approval', but it does not contain filler and each sentence adds 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?

Given the tool's complexity (DAG construction and human approval gates), the description covers the essential call semantics and return value. Small gaps remain: 'terminal' is not defined and no guidance is given on how dependencies refer to existing task IDs. Overall, an agent could invoke it for standard and approval-gate cases.

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 13%, so the description must compensate. It explains the four non-obvious parameters: deliverable (artifact path), acceptance_criteria (verification method), dependencies (DAG, blocking behavior), and require_approval (approval gate). The remaining parameters (title, priority, assigned_to, description) are self-explanatory or covered by the schema enum.

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 opens with a specific verb and resource: 'Create a new task in the task queue,' and states the return value (task_id). This clearly distinguishes it from siblings like task_claim, task_complete, and task_approve, which target different lifecycle stages.

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 provides clear context for when to use the tool (creating a task, optionally with a dependency DAG or an approval gate). However, it never names alternatives or states when not to use it—for example, it doesn't mention that task_depend could add dependencies to an existing task, so exclusions are absent.

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

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

With no annotations provided, the description fully covers behavioral details: it writes escalation.decision, decider, and decided_at, transitions the task to 'running', only affects escalating tasks, is idempotent, and logs the decider for audit. This is strong disclosure beyond the schema.

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

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

The description is a single dense sentence that front-loads the core purpose, then packs in state constraints, side effects, idempotency, and audit behavior. Every clause carries useful information with minimal waste.

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 3-parameter tool with no annotations and no output schema, the description provides enough context: the exact state transition, preconditions, idempotency, and audit trail. An agent can correctly decide when to call this tool and what effect to expect.

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 67%, with 'choice' and 'decider' already described in the schema. The description adds the audit purpose of 'decider' and the state transition, but does not significantly enrich parameter semantics for task_id beyond what the schema implies.

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 clearly states the tool's action: issuing a decision for an escalating task, writing decision fields, and returning the task to 'running'. It distinguishes itself from siblings like task_escalate by focusing on resolving escalation rather than creating it.

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 explicitly limits usage to the escalating state and notes that already-decided tasks are rejected. It does not name alternative sibling tools, but the state condition and idempotency rule provide clear guidance on when the tool applies and when it does not.

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

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

With no annotations provided, the description carries full behavioral burden and does so thoroughly: it discloses overwrite semantics, cycle rejection, the terminal-task restriction, the fact that status is unchanged, that no dispatch occurs, and that the reason is written to the audit log. This gives the agent a clear model of side effects and guardrails.

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 dense but purposeful; every clause contributes either usage context, a constraint, or behavioral clarification. It is not as crisp and front-loaded as it could be, but the complexity of the operation justifies its length.

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 graph-modifying tool with no annotations and no output schema, the description covers the main invocation concerns: when to use it, what it does, what could reject it, and what it does not do. It stops short of describing return values or error response shapes, but those are optional in this context.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the set semantics with the 'original dependencies + new predecessor' example, but the schema already explains that set is the complete overwritten dependencies array, task_id is the target, and reason is for audit logging. The added value is illustrative, not substantive.

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—overwriting an existing task's dependencies to recompute the dependency graph—and clearly identifies the resource being modified. The concrete S3'/S2.5 example and the statement that it is a pure dependency-graph adjustment distinguish it from sibling tools like task_fork or task_create.

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 explicitly explains when to use the tool: after forking a patch branch, to insert a new predecessor and repoint dependencies. It also states when it cannot be used (terminal tasks, cycles), but it does not name direct sibling alternatives or contrast them explicitly.

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

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

With no annotations, the description carries the full burden and delivers substantial behavioral disclosure: the state transition semantics (`escalating` blocks running and is non-terminal), the persistence of question + options, the auth gate (current attempt_id required; handoff/forged tokens rejected, preventing stale submissions), and the lifecycle (monitoring aggregates reports with raised_at age; resolution via task_decide returns the task to running). This far exceeds schema-level information.

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 is front-loaded ('决策上浮 worker 遇方案选择/疑问…') and the paragraph is information-dense with no filler. It is one long run-on sequence that packs state semantics, auth rules, and lifecycle into a single flow, which is efficient but could benefit from light structuring. Every clause earns its place.

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

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

For a stateful human-in-the-loop tool with no annotations and no output schema, the description covers the state transition, blocking behavior, auth requirement, non-terminal nature, monitoring, and resolution path via task_decide. Missing are the return value on success/failure and edge cases such as re-escalating an already-escalating task — minor gaps for a tool of this 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 75% — question, options, and attempt_id are already documented in the schema. The description adds context about how these params are used (persisted for the human decision) and the '防迟到' rationale for attempt_id, but task_id remains undocumented in both, and the added param-level meaning is marginal beyond the schema. Baseline 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 trigger and action: escalate a decision upward when a worker faces方案选择/疑问, transitioning the task to `escalating` state and storing question + options. It names the exact resource (task) and effect (running blocked, waiting for human decision), and differentiates itself from the sibling task_decide by describing the complementary resolve-downward flow.

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 usage context is explicit: use when a worker encounters a choice/uncertainty requiring human judgment. It also sketches the workflow — user answers, then task_decide issues the decision, then the task returns to running — which tells the agent how this tool fits alongside siblings. It stops short of explicitly stating when not to use it versus alternatives like task_fail or task_approve, so a 4 rather than a 5.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It states the core state change and that a reason can be provided, but it does not disclose whether the failure is reversible, whether dependent tasks are affected, or any side effects. This is thin for a mutation tool.

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

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

A single sentence that is verb-first, informative, and includes an example. Every word earns its place; there is no redundant restatement.

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 mutates task state, has no annotations, no output schema, and an undocumented schema, yet the description only covers the basic action. Missing guidance on when to fail versus complete or escalate, and on the role of the result field, leaves the context incomplete for reliable selection and 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 description must compensate. 'with reason (e.g. could not complete)' gives meaning to the optional result parameter, and 'task' implies task_id. However, it doesn't explicitly map these to the schema parameter names or discuss requiredness beyond what the schema already provides.

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 verb 'Mark' plus resource 'task failed' is specific and immediately distinguishes this from siblings like task_complete or task_escalate. The parenthetical reason adds useful context. However, it doesn't explicitly name an alternative tool, so it falls just short of the top score.

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 provides no when-to-use or when-not-to-use guidance. It does not mention alternatives such as task_complete, task_escalate, or task_interrupt, leaving the agent to infer selection solely from the tool name and sibling list.

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

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

With no annotations provided, the description carries full behavioral disclosure. It explicitly mentions the atomic supersede operation, that the parent does not rewrite history, and that it returns the new subtask id. It does not cover error cases or the subtask's initial state, but the core behavior is transparent.

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, compact paragraph that front-loads the primary action (forking) and key effects. It is slightly verbose in Chinese but efficiently conveys essential information without unnecessary 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 forking operation with no output schema, the description covers the essential behavior, return value, and the parent's state change. It does not explain error conditions or the status of the created subtask, but given the tool's complexity and the presence of many related siblings, this is adequate.

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 67% (two of three parameters documented). The description adds minimal parameter-level meaning beyond the schema: it mentions inheritance of fields but does not elaborate on fork_title or the exact semantics of reason beyond what is already in the schema. With high coverage, baseline 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 clearly states the tool spawns a subtask from a running task, inherits deliverables/dependencies/acceptance criteria, and atomically marks the parent as superseded. It is distinct from sibling tools like task_create (which creates independent tasks) and task_supersede (which only marks a task superseded without forking).

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 provides a clear use case: '用于探索不同执行路径/决策变更' (for exploring different execution paths or decision changes). It does not explicitly name alternatives or give when-not-to-use conditions, but the purpose is sufficiently clear for an agent to decide when to apply it.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the tool mutates state (refreshes heartbeat fields, appends a note), requires a current claim-issued attempt_id, rejects old/forged tokens, and prevents late overwrites. These are meaningful behavioral details beyond a generic 'heartbeat' label.

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 dense but not bloated: each of the three sentences contributes purpose, usage boundaries, or token/race semantics. It is front-loaded with the core actionasia. Minor structure improvements could be made but no sentence is wasted.

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

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

Given no output schema and no annotations, the description covers the essential selection and invocation information: what it does, when to call it, required attempt_id auth, and side effects. It does not describe return values or error behavior for non-running tasks, but for a mutation-style heartbeat tool the provided context is sufficient for safe use.

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 67%, with note and attempt_id already described in the schema. The description adds value by explaining attempt_id as a claim-issued capability token that is rejected if stale or forged, and by clarifying note is a milestone appended to progress_log. task_id has no schema description, but the tool description implies it identifies the running task, so this is mostly compensated.

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: heartbeating a running task by refreshing last_heartbeat_at and heartbeat_n, and appending the note to progress_log. It clearly differentiates this from the server's automatic run_* subprocess heartbeat, and the mention of milestone reporting separates it from other task_* 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?

The description explicitly says when to use the tool: for active milestone reporting by a master/worker, or to manually keep alive a long task with no stdout. It also explicitly says when not to use it: the server already auto-heartbeats running run_* processes. This is clear context and an explicit exclusion, leaving no ambiguity.

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

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

With no annotations, the description carries the full burden and is exceptionally transparent. It discloses the precise kill mechanism per OS, the transition to interrupted state, preservation of partial output and session_id, and the running-state requirement. This provides deep behavioral insight beyond a generic 'interrupts a task' statement.

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, front-loaded with the core action and resource. Every clause adds operational value: mechanism, state change, preserved data, constraints, and use case. There is no filler and no repetition of schema 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 destructive mutation tool with no annotations and no output schema, the description is remarkably complete. It covers what happens, how it happens, when to use it, and the constraints that govern valid invocations. The only omission is an explicit return value, but that is not essential for correct invocation and no output schema exists to document it.

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

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

Schema coverage is 50%: only the 'by' parameter has a description. The tool description indirectly clarifies task_id by stating the task must be currently running and terminal tasks are rejected, which is useful. However, it does not explicitly map parameters to these constraints or add any new meaning to 'by' beyond the schema, so it only partially compensates for the undocumented task_id.

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 opens with '中断一个 running 任务' (interrupt a running task), then specifies the exact mechanism (kill worker subprocess tree via taskkill /T /F on Windows or SIGTERM→SIGKILL on Unix) and the resulting state (interrupted, preserving partial output and session_id for task_resume). This clearly distinguishes it from siblings like task_fail or task_complete by emphasizing interruption and resumability.

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 states when to use the tool ('适合长任务卡死/跑偏时人工叫停' – suitable for manually stopping long tasks that are stuck or off-track) and provides the key constraint that only running tasks can be interrupted while terminal-state tasks are rejected. It mentions task_resume as the continuation path but does not explicitly contrast with alternatives like task_fail for cases where resumption is not desired.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does disclose that batch operations are atomic, defines the effects of reassign/fail/supersede, and notes the no-parameter backward-compatible behavior. Yet it omits permissions, reversibility, and preconditions such as which task statuses are eligible for batch mutation, which is significant for a tool that can write.

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 dense but highly organized: 'List tasks' is front-loaded, followed by labeled groups for filters, sorting, pagination, and batch operations. There is no filler, and each segment 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?

This is a complex tool with 9 parameters, no annotations, and no output schema. The description covers the main listing and batch behaviors well, but it leaves gaps around output format, error behavior, and batch-action preconditions (e.g., whether completed or failed tasks can be reassigned). For a mutation-capable tool, more context would be expected.

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 89%, so the baseline is 3. The description adds value beyond the schema by clarifying that batch actions are atomic, that batch_agent is the target for reassign, that batch_reason applies to fail/supersede, and that omitting parameters returns all tasks. These details supplement rather than repeat 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 opens with 'List tasks', a specific verb+resource, and immediately enumerates filters, sorting, pagination, and batch operations. It is clear in scope, but it does not explicitly differentiate itself from sibling tools like task_reassign, task_fail, or task_supersede, even though its batch_action overlaps with them.

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

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

The description provides practical usage guidance: it explains filter semantics, sort options, pagination via limit/offset, requires task_ids for batch_action, and notes that no parameters returns all tasks for backward compatibility. However, it never states when to prefer this tool over the single-task sibling tools, nor when batch_action should be avoided in favor of those 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?

With no annotations, the description carries the full burden of behavioral disclosure and does so thoroughly. It explains token revocation, handoff generation, stale-attempt rejection, clearing of claimant, and how a new owner clears handoff state. It also discloses the terminal-task refusal behavior, which is exactly the kind of consequence an agent needs to predict.

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 long and dense but front-loads the core action and follows with necessary technical detail. Every sentence contributes semantic value; the '≈dsh handoffId' and token-window jargon add precision but also complexity, so it is not maximally concise.

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 a complex state-machine behavior, no output schema, and no annotations, yet the description covers transitions, side effects, rejection mechanics, takeover flow, usage context, and terminal refusal. The main gap is that it does not state what the caller sees on success or on terminal refusal (return value/error), which 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?

The input schema describes 'note' but not 'task_id', and schema description coverage is 50%. The description's prose implies the task being released but adds no explicit parameter-level guidance about task_id or how to use note; the note's audit purpose is already in the schema. The behavioral detail (must be pending/running, terminal refused) indirectly constrains valid values, so it is minimally adequate but not compensatory.

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 pair: 'Release a pending OR running task back to unclaimed' and clearly describes the state transition (running→pending). It is distinct from sibling task tools because it focuses on handing off ownership for takeover, but it does not explicitly name alternatives or differentiate itself from task_supersede/task_escalate/task_claim.

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 a clear when-to-use condition: 'Use when the current implementer is stuck/lost/gave up and you want an uncontested take-over.' It also gives an important exclusion: 'Terminal tasks refuse (can't resurrect).' However, it does not mention alternative sibling tools or explicitly say when not to use this versus those.

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

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

With no annotations, the description carries the full disclosure burden and does so well: it explains true-resume behavior, fresh-run fallback for non-supporting agents, task_id reuse, workflow/dependency retention, override semantics, and non-resumable terminal state. It omits status transitions and error conditions, but the core behavioral profile is clear.

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 dense but each clause contributes: eligibility, reuse inputs, engine behavior, identity retention, overrides, and exclusion. It is front-loaded with the core purpose, though the single-paragraph structure could be improved with separation of behavior from parameters.

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 9 parameters, no annotations, and no output schema, this description covers the main resume semantics but not enough to be fully complete: it omits behavior for plan_mode/max_retries/timeout_sec, potential errors, and what happens when resuming a task that is still active or already claimed. It is adequate for the primary use case but has clear gaps.

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 33%, and the description compensates for task_id, prompt, session_id, workdir, model, and agent by explaining reuse and override behavior. However, plan_mode, max_retries, and timeout_sec remain undocumented in both schema and description, leaving a clear gap for a 9-parameter tool.

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 opens with a specific action and target: resume an interrupted/failed/superseded task, reusing the original prompt, session, workdir, and agent. This clearly separates it from siblings like task_create or task_interrupt, and it also states the terminal-state exception (completed cannot be resumed).

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 when-to-use conditions (interrupted/failed/superseded), a when-not condition (completed), and engine-specific guidance (claude/codex/qwen preserve context; DSH/opencode restart fresh). It does not explicitly name sibling tools as alternatives, so it falls short of a full 5.

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

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

With no annotations provided, the description carries the full burden. It discloses the main side effect (writing to memory) but does not explain whether the original task is modified, whether duplicates are avoided, what permissions are needed, or what happens on failure.

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 concise sentences with no filler. The core action is front-loaded and the downstream benefit is stated efficiently.

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 there are no annotations, no output schema, and five parameters, the description is too thin to fully support correct invocation. It does not mention return values, side effects on task state, or parameter roles beyond the high-level purpose.

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 20%, so the description should compensate for the undocumented cwd, scope, source, and task_id parameters. It only implies that task_id refers to a completed task and mentions memory_add, without explaining how each parameter is used.

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 clearly states a specific action: distilling a completed or result-bearing task into a knowledge point and writing it to vector memory via memory_add. It distinguishes itself from generic memory tools by tying the behavior to task completion, though it does not explicitly name sibling alternatives.

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

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

It gives clear context for when to use the tool: after a task is completed or already has a result, to enable later memory_search reuse. It lacks explicit exclusions or comparisons to task_complete or memory_add, but the intended trigger is reasonably 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?

With no annotations, the description carries the full burden. It discloses the status transition ('Transitions any non-terminal status→superseded') and the recorded fields (superseded_by and reason). It doesn't disclose validation behavior (e.g., if superseded_by references a non-existent task) or idempotency, but the core behavioral facts are present.

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, zero fluff. The action is front-loaded, and the usage guidance follows logically. Every sentence earns its place.

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

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

For a simple mutation with no output schema, the description covers the intent, effect, and alternatives. It doesn't mention edge cases like behavior when the task is already terminal (though 'non-terminal' implies it) or permission requirements, but these are minor given the tool's simplicity.

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

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

Schema coverage is 0%, so the description must compensate. It explicitly mentions superseded_by and reason, providing meaning beyond raw parameter names. task_id is self-evident. It adds value by explaining the role of superseded_by as the replacing task's ID, though it could be more explicit about each parameter's format.

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

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

The description clearly states the action (mark a task superseded) and the resource (task), with a specific effect (status transition to superseded) and recorded fields. It explicitly contrasts with completed/failed, distinguishing it from sibling tools like task_complete and task_fail.

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 says 'Use this instead of completed/failed when a task didn't finish but was overtaken', providing clear when-to-use and when-not-to-use guidance, along with named alternatives. This leaves no ambiguity for an 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?

No annotations are provided, so the description carries the full burden. It discloses the model used (Qwen3-VL-235B-A22B-Instruct), the default prompt behavior (5-part Chinese report), the key runtime requirement (read from opencode.json qwen provider), and the critical limitation (cannot decode high-density barcodes). This is substantial behavioral context beyond the schema.

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

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

The description is dense but front-loaded with the core purpose and the critical barcode limitation. It packs a lot of information into a compact space. Slightly long, but every sentence earns its place.

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

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

For a 5-param tool with no output schema, the description covers the key behavioral aspects: model, default prompt, input requirements, and limitations. It doesn't describe the return format, but the default prompt description implies the structure of the output. The barcode limitation is critical context that is well covered.

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 adds context about the default prompt and model, but the parameters themselves are already well-documented in the schema. The description doesn't add significant meaning beyond what the schema provides.

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 ('analyze') and resource ('an image'), and explicitly distinguishes itself from a barcode decoder: 'NOT a barcode decoder — high-density barcode VALUES must be decoded by a real decoder (ZXing/Dynamsoft), the VLM cannot.' This clearly differentiates it from siblings like safe_scan and run_qwen.

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 clear context for when to use this tool: for image analysis with a VLM, and explicitly says when NOT to use it (for barcode decoding). It doesn't name alternative sibling tools explicitly, but the exclusion is strong and actionable.

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