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 provided, the description carries the behavioral burden. It discloses that the tool returns definitions rather than executing tools, indicates relevance ranking, and references the list_tools output format. It does not explicitly state lack of side effects, but the search/return framing makes the read-only behavior clear enough.

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 action is front-loaded and the return behavior is described in the second sentence. 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 one-parameter, output-schema-bearing search tool, the description is complete: it states the query source, the result type, ranking behavior, and output format. No critical invocation 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 description coverage is 100% and the single 'query' parameter is already described as a natural language query. The description adds no additional semantic detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific action ('Search for tools') and resource ('tool definitions'), and adds that results are ranked by relevance. This differentiates it from session lifecycle tools and brain_call_tool 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?

The description implies its use case: natural-language discovery of tools, as opposed to session manipulation or direct tool invocation. However, it does not explicitly name alternatives or state when not to use it, such as preferring list_tools for browsing all tools.

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

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

Annotations 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?

Annotations already declare destructiveHint/idempotentHint/readOnlyHint=false, so the safety profile is covered. The description goes beyond them with substantive behavior: nothing_to_capture_reason is now optional, a blank-string reason is still rejected, `unattributed_in_window` is reported as a measure and cannot gate the close, and summary/next_focus are server-underivable requirements. It stops short of 5 because it never says what happens to the session record after the close or whether the operation is reversible.

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

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

The purpose is front-loaded in the first sentence, which is good. But several sentences are rhetorical justification for a design decision ('a check is hollow the moment the thing it checks can influence its own signal', 'saying nothing and saying " " are not the same act') that consumes space without changing how an agent calls the tool.

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

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

An output schema exists, so return values need not be explained, and the description covers the lifecycle constraint, the required-judgement inputs, and the revision-slot trap. It is nearly sufficient for a 6-parameter destructive lifecycle tool; the missing piece is an explicit statement of how to choose this over brain_session_abandon.

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%, so the description must compensate, and it does for the two least-obvious parameters: expected_focus_revision is pinned to the SLOT revision from bind/resume/relay and explicitly not started_focus_revision, and nothing_to_capture_reason's new optionality plus blank-refusal rule is spelled out. summary, session_id, and nothing_to_capture_reason's value shape remain undocumented in both places, keeping it below 5.

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

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

The opening sentence gives a specific verb+resource ('End a session') and adds the operative scope ('from an explicit user command, on judgement alone'), which an agent can act on. It does not, however, name or contrast against the obvious sibling brain_session_abandon, so the boundary between the two lifecycle endings is left to inference.

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

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

It states both a positive trigger (explicit user command, agent judgement) and an explicit prohibition ('no hook and no auto-close may invoke this lifecycle boundary'), which is real when/when-not guidance. The gap is that it never names the alternative tool (brain_session_abandon) for the case where a session should be terminated without a summary/focus.

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 only supply the safety profile (destructive, idempotent); the description adds the substantive behavior: single-transaction CAS semantics, that stale revisions or a closed slot change nothing and leave the session open, the 70% shrink guard and its refusal code, the replayed/terminal_conflict outcomes, and the guard-mod environment gate. This is far beyond what the annotations convey.

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

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

Long but front-loaded, with labeled cases (Bound/Unbound/Shrink Guard) that let an agent scan rather than parse prose. Most sentences carry operational payload, though the trailing paragraph about the agent tracer is loosely tied to the call itself.

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, 11-parameter lifecycle tool with an output schema, it covers transaction shape, guarded failure modes, and revision hand-off to the successor's next call. Remaining gaps: no explanation of `summary` or `nothing_to_capture_reason`, and the handover length figure differs from the schema constraint.

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 18% across 11 parameters, so the description must compensate, and it does for the critical ones: `expected_slot_revision` vs `expected_focus_revision` (base revision), `handover` content and its replacement semantics, `knowledge_ids` capture, `new_client_key` successor identity, `allow_focus_shrink` operator-only rule, and `initiator`. Gaps remain for `summary` and `nothing_to_capture_reason`, and it states a 4,000-character handover cap that conflicts with the schema's 10,000 maxLength.

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 ('relay an open session onto its slot, or its project base') and unpacks it into the concrete lifecycle it performs: capture, end, restart via a successor. It explicitly distinguishes itself from the sibling `end` ('unlike `end`, which closes anyway'), so an agent can route between them 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?

Gives explicit branching conditions: bound sessions require `expected_slot_revision`, unbound sessions require `expected_focus_revision`, and it names the failure modes that select differently. It also states when the tool may be invoked by a guard mod (operator-enabled, env flag on). It doesn't frame the choice against alternatives like `brain_session_capture` or `brain_session_resume` beyond the `end` contrast, so not 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?

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 cover idempotency, destructiveness, and read-only hints. The description adds value by disclosing that this is a controlled lifecycle boundary and that the server only opens/closes agent tracer sessions on its own. This is behavioral context beyond what annotations provide, with no contradiction.

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

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

Two sentences with no filler. The main action and trigger are front-loaded, and the second sentence earns its place by preventing incorrect automatic 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?

The output schema and annotations cover return values and safety traits, so those gaps are acceptable. However, the required project_key parameter is left unexplained, and the relationship between 'start/replay' and the sibling brain_session_resume is not clarified. This is a meaningful gap for an agent deciding which session tool to call.

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 description adds no parameter-level meaning. The schema describes client_key well, but project_key has no description and is required; the description does not compensate for that gap. With 50% schema coverage, the description should have provided at least some project/session context.

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 ('Start or replay') and the resource ('a concurrent session'), plus the specific trigger ('from an explicit user command'). It does not explicitly distinguish itself from sibling brain_session_resume, and 'replay' vs 'resume' creates some potential overlap.

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

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

The description gives explicit when-to-use context: only from an explicit user command. It also gives a clear exclusion: no hook and no auto-close may invoke this lifecycle boundary. It does not name alternatives like brain_session_resume, but the trigger guidance is strong.

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