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

The description goes well beyond the annotations by explaining that nothing_to_capture_reason is optional, that blank reasons are still refused, that unattributed_in_window is reported as a measure rather than a gate, and that the server cannot provide the required summary or next_focus. It also clarifies the only server-initiated lifecycle case. No statement contradicts 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 description is front-loaded with the purpose and organized into clear blocks: purpose, parameter behavior, required inputs, and lifecycle boundary. The historical rationale about the old XOR check is somewhat longer than strictly necessary, but it supports the blank-reason rule. It is dense and structured, though trimming the design history would make it leaner.

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 lifecycle operation with an output schema and annotations, the description covers the essential decision factors: when it may be invoked, what must be supplied, and what is reported rather than enforced. The remaining gaps are the lack of an explicit distinction from brain_session_abandon and the undocumented expected_focus_revision parameter. Still, an agent has enough context to call the tool correctly in most 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?

With only 33% schema coverage, the description compensates meaningfully by explaining the optionality and refusal semantics of nothing_to_capture_reason and by emphasizing that summary and next_focus are required because the server cannot derive them. It does not explain expected_focus_revision or add much beyond what the schema already provides for the other parameters.

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

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

The description opens with a specific verb and resource: 'End a session from an explicit user command, on judgement alone.' This makes the core operation clear. However, it does not explicitly contrast itself with the sibling tool brain_session_abandon, so the agent must infer how ending differs from abandoning a session.

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 invocation context: only an explicit user command, never a hook or auto-close, may invoke this lifecycle boundary. It also states that callers must supply a summary and next_focus. It does not name alternatives or exclusion conditions relative to sibling session tools, which prevents 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?

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?

This is an annotation contradiction. The description frames the operation as a lifecycle mutation ('resume', 'lifecycle boundary'), and the input schema mentions guarding 'any session mutation', while annotations declare readOnlyHint=true. An agent cannot trust whether this tool changes session state.

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 and trigger front-loaded and the important system-level restriction stated immediately after. There is no filler; 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 trigger restriction is clear, but the tool is incomplete for a lifecycle operation: the reader is not told what resuming actually changes, whether the session must already be open, or how expected_client_key mismatch is handled. The annotation contradiction further undermines the safety profile, so the presence of an output schema does not make this definition sufficient.

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 minimal semantic value by indicating session_id should refer to an open session, while expected_client_key is already well described in the schema. It does not explain what happens on a client-key mismatch or where the expected client key comes from, but the parameter-level meaning is at least minimally viable.

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 (resume), object (an open session), and trigger (an explicit user command). It distinguishes this from lifecycle siblings by emphasizing the user-command boundary, but it does not explicitly name an alternative tool or detail what resuming entails, so it falls just 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?

The description explicitly says this is for an explicit user command and that hooks and auto-close must not invoke this lifecycle boundary, giving clear when and when-not guidance. It does not mention how to handle a non-open session or when to prefer a sibling tool such as brain_session_start, so it is not fully 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.