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 only says 'Call a tool by name' and does not mention potential side effects, error behavior, dynamic execution risk, or that it can invoke arbitrary tools with arbitrary consequences. This is a significant gap for an execution 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?

Two sentences, zero filler, action stated first. The second sentence provides essential context (use after search_tools) without redundancy. Excellent front-loading.

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 2-parameter tool, the description covers the core action and usage context. However, without an output schema or annotations, it omits return value behavior and error handling, which an agent might need when invoking arbitrary tools. It is adequate but not comprehensive.

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 schema already documents both parameters. The description adds marginal value by linking parameters to 'given arguments' from search_tools, but does not enrich semantics 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 clearly states a specific verb ('Call') and resource ('a tool by name with the given arguments'), and differentiates itself from discovery tools by positioning it as the execution step after search_tools. This makes it unambiguous against siblings like brain_find_tool.

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

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

The phrase 'Use this to execute tools discovered via search_tools' gives clear context of when to invoke it (after discovery) and implies it is not for searching. It does not explicitly exclude session-management siblings, but the usage context is sufficient for a generic dispatcher.

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 well: it discloses the hard result cap (up to 5), relevance ranking, the summary fields returned, and the exact-name mode that escalates to a full schema. It does not address auth or rate limits, but for a read-only search those are minor.

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 in the first sentence, and the following sentences add return-format and mode details with no redundancy. Every sentence earns its place for a 1-param tool.

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

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

An output schema exists, so return values need not be re-explained, and the single parameter is fully documented. The description is complete enough to invoke the tool correctly, with only the downstream relationship to brain_call_tool left implicit.

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

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

Schema coverage is 100% for the single query param, so the schema baseline is 3. The description adds real meaning by explaining that the same field drives two behaviors (natural language vs. exact tool name), which the schema alone does not convey.

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 (search) and resource (tools) with the query modality (natural language), plus the result shape. It is trivially distinguishable from the brain_session_* siblings and brain_call_tool, which handle sessions and invocation rather than discovery.

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 conveys two usage modes clearly: a natural-language query returns ranked summaries, while an exact tool name returns the full input schema. It does not explicitly name brain_call_tool as the downstream step or state when to prefer discovery over direct invocation, but the context is clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, which cover the destructive nature. The description adds the explicit-user-command constraint and notes that only an agent tracer session is server-managed. However, it does not describe consequences (e.g., irreversibility, impact on session data) beyond the annotation.

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

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

Two concise sentences, front-loaded with the primary action and constraint. The second sentence adds relevant context about the agent tracer without bloat.

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

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

For a mutation tool with three required parameters and no output schema, the description is sparse. It does not explain what 'abandon' entails versus brain_session_end, what the response contains, or prerequisites beyond the schema. The annotation and schema cover only part of the operational 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 description coverage is only 33% (only expected_client_key has a description). The tool description provides no parameter information, failing to compensate for the low coverage. An agent receives no guidance on session_id or reason beyond the schema's minimal type constraints.

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 clear action ('abandon a session') and resource, and adds a critical constraint ('only from an explicit user command'). It does not explicitly differentiate from the sibling brain_session_end, but the user-command qualifier hints at a distinct lifecycle 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 gives explicit when-to-use guidance ('only from an explicit user command') and when-not-to-use ('no hook and no auto-close may invoke this lifecycle boundary'). It does not name alternative tools directly, but the constraint is unambiguous.

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

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

Annotations cover the safety profile (readOnly=false, idempotent=true, destructive=false), and the description goes further: it explains the downstream effect that `end` writes only the bound slot and never the project base, enumerates all seven refusal codes, and states the replay rule. This is unusually rich disclosure and consistent with the idempotentHint.

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

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

The key action and trigger are front-loaded in the first sentence, then constraints and refusals follow. The prose is dense with internal jargon and the refusal list is unglossed, but every sentence carries substantive information rather than filler.

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

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

With an output schema present, return values need not be described, and the description adequately covers lifecycle rules, replay behavior, and failure modes. Its one real gap is the near-total absence of input-parameter meaning, which is left to a thin schema.

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

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

Schema coverage is only 33%, with just `expected_client_key` documented inline. The description explains none of the three input parameters (slot_id, session_id, expected_client_key); the only parameter it references, `expected_focus_revision`, is not an input at all. It therefore fails to compensate for the coverage gap.

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

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

The opening clause states a specific verb and resource: 'Bind an open operator session to one focus slot.' It clearly belongs to the session lifecycle family, though it never names a sibling (e.g. brain_session_end/start) to disambiguate which lifecycle call to pick, so it stops short of full sibling differentiation.

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

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

It gives a clear triggering condition ('from an explicit user command') and a negative constraint ('no hook and no auto-close may invoke this lifecycle boundary'), plus once-per-session/replay semantics. What is missing is an explicit comparison to the adjacent lifecycle siblings an agent might otherwise choose.

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

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

Annotations already cover idempotency and non-destructiveness; the description adds that already-attributed artifacts are left in place and that this is not a compulsory step. It does not disclose return behavior, permissions, or failure modes, so with annotations lowering the bar, this is adequate but not rich.

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

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

Purpose and usage are front-loaded in the first paragraphs, but the explanation includes redundant historical context ('No longer a compulsory ritual' followed by the derived-capture explanation) and a final lifecycle sentence that is tangential. It is readable but not 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 side-effecting 3-parameter tool with no output schema and with annotations, the description provides enough usage context to call correctly, including scope and idempotent ownership behavior. It lacks explicit statements about return values or errors and uses jargon like 'derived capture' and 'receipt' without definition, so completeness is only moderate.

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 describes only expected_client_key; the description adds meaning for knowledge_ids as durable artifacts and specifies their suitability (outside window/connection/project), plus the 'never steals' rule for already-attributed IDs. It does not discuss session_id or expected_client_key beyond schema, so it only partially compensates for the 33% schema description coverage.

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

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

The first sentence identifies a specific action ('Attach durable artifacts') and trigger ('from an explicit user command'). Later text narrows the scope to artifacts the derivation could not see, which differentiates it from automatic capture, though it does not name 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 explicitly states when to use the tool: for artifacts created outside the session window, on another connection, or in another project. It also says when it is not needed, because derived capture attributes normal session artifacts and `end` no longer requires a receipt. It stops short of naming sibling alternatives, but the when/when-not guidance is strong.

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?

Despite rich annotations (destructive, idempotent, openWorld=false), the description adds substantial behavior the annotations cannot convey: the 70% shrink guard, the specific error codes raised (base_focus_shrink, slot_focus_shrink, focus_shrink_override_refused), the CAS on expected_focus_revision, and the fact that a stale revision is recorded as a conflict but still closes the session. It also clarifies that unattributed_in_window is a report and never a gate, and that the nothing_to_capture_reason rule was relaxed.

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

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

The purpose is front-loaded and the prose is dense with actionable detail, but it is well overlong and repeats the shrink-guard logic already present in the parameter descriptions. Passages like the justification of why the ledger XOR reason check was removed are rationale rather than invocation guidance.

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 high-stakes mutation with an output schema available, the description supplies everything an agent needs: required inputs, guard thresholds, override authorization, failure codes, and conflict semantics. Return-value format is correctly left to the output schema.

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

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

With schema coverage at 43%, the description does real work: it defines what next_focus replaces for bound vs unbound sessions, distinguishes expected_focus_revision (slot revision) from started_focus_revision, and explains the operator-only nature of allow_focus_shrink. It adds less meaning for summary and nothing_to_capture_reason, which the schema largely covers.

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

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

The opening line states a specific verb and resource ("End a session") plus the trigger condition (explicit user command). It also distinguishes this lifecycle boundary from automatic machinery ("no hook and no auto-close may invoke this"). It never names the obvious sibling alternative (brain_session_abandon), so sibling differentiation is only partial.

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

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

It gives a clear when-to-use rule (explicit user command, on judgement alone) and an explicit when-not (no hook, no auto-close may call it). It also describes the preconditions for the override path (active /brain-admin elevation) and the compare-and-swap requirements. It stops short of routing the agent between end, abandon, and relay.

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

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

Annotations already declare readOnlyHint=false, so the mutation is known. The description adds that this is a lifecycle boundary and only for explicit commands, but it does not explain what 'refresh' does to the session (e.g., extends timeout) or any side effects. It adds some context but not deep 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?

Two sentences, zero wasted words. The main purpose is front-loaded, and the critical usage constraint is stated immediately after. Perfectly 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 mutation with no output schema, the description is somewhat bare. It does not specify behavior for a closed session, failure modes, or the return value. The agent can infer that the session must be open from the phrase 'open session', but it is not explicitly guaranteed. Given the simplicity, 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 coverage is 50%: session_id has only a format, while expected_client_key has a detailed description. The tool description itself does not elaborate on either parameter. Since the missing session_id is self-explanatory (a UUID), the description does not need to compensate much, but it still adds no meaning beyond the schema.

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

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

The description uses a specific verb ('refresh') with a clear resource ('an open session') and immediately distinguishes itself from siblings by stating it is the only lifecycle boundary invoked by explicit user command, not by hooks or auto-close. This fully differentiates it from brain_session_start/end/resume.

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 ('from an explicit user command') and, more importantly, when not to use it ('no hook and no auto-close may invoke this lifecycle boundary'). This gives the agent a clear decision rule, even though alternatives are not named directly.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safe read-only nature is established. The description adds meaningful behavioral context beyond those annotations: the server only auto-opens/closes an agent tracer session, and hooks/auto-close must never invoke this boundary. This is valuable context, though it does not describe list ordering, pagination, 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?

Two short sentences with no filler. The primary action is front-loaded, and the critical invocation restriction is placed in the supporting sentence. 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?

The description fully covers the unusual invocation policy, which is likely the highest-risk aspect of this tool. However, with no output schema and no parameter descriptions, the agent still lacks context about what a session entry contains, which status filters mean, and what the list response looks like. Adequate for basic invocation but with meaningful 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%, and the description does not compensate for any of the four parameters. The schema provides names, types, defaults, and the status enum, but meanings like 'stale', 'abandoned', and 'closed_inactive' are left unexplained, and project_key semantics are not addressed. With zero coverage, the description should add parameter context but does not.

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

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

The description states a clear verb and resource ('List sessions') and adds a distinctive policy constraint: it runs only on explicit user command. It does not explain what kinds of sessions are returned or how this differs from sibling read tools, but the core purpose is unambiguous.

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

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

The description gives an explicit when-to-use condition ('only in response to an explicit user command') and an explicit when-not-to-use condition ('no hook and no auto-close may invoke this lifecycle boundary'). It does not mention sibling alternatives, but the trigger and exclusion are clear enough for an agent to decide.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, and the description corroborates and enriches all three: the handover REPLACES the whole slot body/base, equal replay yields `replayed=true`, and it discloses error names, CAS semantics, the 70% shrink guard, env-var gating, and elevation requirements. It adds substantial behavioral context beyond the annotations.

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

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

The purpose is front-loaded but the body is dense and repetitive, restating the operator-only /brain-admin override rule in two separate paragraphs. For a 12-parameter lifecycle tool the length is defensible, but the redundancy costs conciseness.

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

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

Given an output schema is present, the description needn't document return values, and it still explains replay and conflict outcomes. Between the description, schema, and annotations, an agent has the CAS, permission, and guard behavior needed to call this 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 only 33% schema description coverage, the description carries the load: it defines `handover` replacement semantics (max 4,000 chars), the distinction between `expected_slot_revision` and the BASE `expected_focus_revision`, `allow_focus_shrink` operator-only behavior, and `briefing` full vs compact. It omits meaning for `summary` and `nothing_to_capture_reason`, so it does not fully compensate for the coverage gap.

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

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

States a specific verb+resource (relay a session onto its slot or project base) and enumerates the composite effect: capture, end, restart. It explicitly differentiates from siblings, e.g. contrasting its stale-revision behavior with `end` and noting the capture of `knowledge_ids`, so an agent can place it against brain_session_end/brain_session_capture 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?

Clearly splits the two forms and the condition selecting each: bound sessions send `expected_slot_revision`, unbound send `expected_focus_revision`. It also names the guard_mod/operator gating condition. It lacks a crisp top-level 'use relay instead of capture+end+start when...' statement, so usage is well-contextualized but not framed as an explicit choice against all alternatives.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, yet the description calls this a "lifecycle boundary" that the server "opens or closes," and the schema states the client-key pair must match "before any session mutation." Resuming a session is an intentional state change, so the description directly contradicts the readOnly annotation.

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

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

Two short sentences with the primary action stated first and the lifecycle constraint second; no filler. Slightly cryptic phrasing ("agent tracer") costs it a point but the structure is sound.

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

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

An output schema exists, so return values need not be explained, and the description covers the invocation precondition (explicit user command). However, for a mutating lifecycle operation it omits what state changes on resume, error behavior for a closed/unknown session, and any detail on the undocumented session_id parameter.

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 50%: expected_client_key is well documented in-schema, but session_id carries no description anywhere. The description adds no meaning about either argument (e.g., which session UUIDs are valid, what happens if the client key mismatches), so it fails to compensate for the coverage gap.

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

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

The description names a specific verb (resume) and resource (an open session) and scopes it to explicit user commands, which separates it from the lifecycle-start path in siblings like brain_session_start. It does not name any sibling explicitly, so differentiation still requires inference from names alone.

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?

"From an explicit user command" gives a clear when-to-use trigger, and the second sentence effectively says when NOT to use it (no hooks, no auto-close). It stops short of naming the alternative to call for a brand-new session, so the routing guidance is good but not complete.

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

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

Annotations already declare write/idempotent/non-destructive, so the description correctly focuses on non-obvious behavior: replay semantics, the briefing size cap, and the fact that no hook or auto-close can drive this lifecycle boundary. That is meaningful context beyond the structured fields, though permission/auth requirements are not 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?

Front-loads the core action in the first sentence and each subsequent sentence carries distinct content (briefing behavior, lifecycle constraints). The third sentence is somewhat dense but not wasteful.

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

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

With an output schema present, return values need not be explained, and the description covers the mutation's key semantics and the lifecycle restriction. The only notable gap is the undocumented `project_key` parameter.

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%, so the description must compensate. It does explain the `briefing` semantics well ('full' detail vs. compact counts/IDs capped at 4,000 chars, focus only in session.started_focus), but `project_key` remains undocumented 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 and resource ('Start or replay a concurrent session') and adds a scope qualifier ('from an explicit user command'). It is fairly distinguishable from siblings, though the boundary against brain_session_resume (vs. 'replay') is not made explicit.

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

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

Gives a positive trigger ('from an explicit user command') and a clear exclusion ('no hook and no auto-close may invoke this lifecycle boundary'), which is real when/when-not guidance. It stops short of naming which sibling to use for the non-explicit cases.

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