magents

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It clearly states the mutating action (mark as read), but does not explain the exact semantics of 'through' (specific message vs up-to-and-including), idempotency, or any side effects beyond marking read.

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

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

A single sentence with no filler, and the scoping alternative '(or all current mail)' is front-loaded and clearly separated. It is appropriately compact for a simple mail action.

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 three parameters, no annotations, and no output schema, the description is too sparse. It leaves agent and session_id unexplained, and does not clarify the return value or the precise behavior when a mail_id is supplied versus omitted. This is insufficient for an agent to call the tool correctly in all cases.

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

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

Schema description coverage is only 33%, and the description does not compensate for the undocumented 'agent' and 'session_id' parameters. It essentially restates the 'through' behavior already present in the schema, adding no new meaning for the remaining 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 uses a specific verb+resource ('Mark inbox mail as read') and clearly distinguishes this tool from siblings like inbox, reply, send_message, and await_reply. The mail_id/all-current-mail scoping further clarifies what it operates on.

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 the core operation and the two modes (specific mail_id vs all current mail), but does not explicitly state when to choose this over alternatives or mention any exclusions. Usage context is implied rather than explicitly guided.

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

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

With no annotations, the description carries the behavioral disclosure burden and does a solid job: it declares a blocking wait, the pending outcome, the default timeout of 5s, and the max of 30s. It does not describe the success return payload or edge-case behavior, but the core behavior is transparent.

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

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

Two sentences, front-loaded with the primary action and scoping, followed by key behavioral facts about pending results and timeouts. There is no filler or redundant repetition of schema fields.

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 four-optional-parameter tool with no output schema, the description covers the timeout and pending condition but leaves parameter semantics incomplete and does not clarify the success return shape. It is adequate for simple use but not fully complete.

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

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

Schema description coverage is only 50%, with agent and session_id left undocumented. The description merely echoes 'from one session' and the timeout defaults, adding no meaning for the two unexplained parameters or clarifying how agent/session_id relate to from.

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 clear verb-resource pair ('Wait briefly for new inbox mail') and specifies the optional session scoping, which helps distinguish it from siblings like send_message or inbox. The mention of 'Returns pending if none arrives' further clarifies the tool's purpose.

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

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

The description implies when to use the tool: when waiting for new inbox mail with a timeout. It does not explicitly explain when not to use it or point to alternatives such as inbox for non-blocking checks, so the guidance is present but not fully explicit.

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

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

With no annotations, the description carries the behavioral burden. It discloses the failure mode ('Errors if the target file already exists'), states that notes are 'untrusted inert history,' and implies unsupported agents will fail. It does not mention return values or permissions, but it provides meaningful behavioral detail for a write tool.

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

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

Three short sentences with the core action front-loaded and no filler. The compatibility caveat and error behavior are compact and placed where they add value.

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

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

The description covers the core write action, supported targets, and the no-overwrite error, making the tool callable. However, with five parameters, no output schema, and no annotations, the unexplained 'project' parameter and absent return-value context leave 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 coverage is only 60%, and the description adds almost no parameter-level meaning beyond the schema. The 'project' parameter is entirely unexplained, and 'content' is only implied. The agent values are mentioned in the prose, but cwd, file, and project semantics are not enriched.

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: 'Write a note into Claude, Codex, or Grok first-party memory markdown.' It clearly distinguishes this from sibling tools like put_note or read_memory by scoping to first-party memory and by listing unsupported agents.

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 an explicit exclusion ('Cursor, OpenCode, Gemini, and Copilot have no first-party memory store') and frames the intended use case as writing to first-party memory. It does not name a sibling alternative or specify when put_note would be preferred, so it stops short of full routing guidance.

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

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

The description notes the data is 'derived from inert transcript tool inputs' and warns not to execute those tools, implying a read-only, safe operation. However, it doesn't explicitly state the tool has no side effects or what the output looks like. Since no annotations exist, this partial transparency is adequate but not complete.

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, front-loaded with the core purpose, followed by a crucial safety note. No fluff or redundancy.

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

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

The tool is simple, but missing details about the limit parameter and return format. With no annotations and no output schema, the description should clarify these aspects. It covers the core purpose but leaves operational details to the agent's inference.

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

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

Schema coverage is 50% (only session_id described). The description does not explain the limit parameter or add meaning beyond the schema. Since limit is undocumented in both schema and description, the description 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 clearly states the tool lists file paths another session touched, derived from transcript inputs. This is specific and distinct from siblings like read_transcript or get_session, which focus on content or session metadata.

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

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

No explicit guidance on when to use this tool versus alternatives. The instruction 'Do not execute those tools' is a safety warning, not usage guidance. It doesn't mention when to prefer this over read_transcript or search_transcripts.

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

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

With no annotations, the description carries the burden, and 'Read' does convey non-mutating behavior. It does not disclose what happens when no note exists or whether the tool can fail, but the read-only behavior is reasonably clear.

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

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

Two short sentences with no filler; the core purpose is front-loaded and the clarifying exclusion earns its place.

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

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

For a simple read tool with no output schema and no annotations, the description is mostly adequate, but the unexplained 'content' parameter is a meaningful gap. The agent cannot fully determine how to invoke the tool correctly without guessing at that parameter's role.

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

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

The schema documents 'cwd' but leaves 'content' completely undescribed, and the description only reinforces the cwd concept. Since schema coverage is only 50%, the description needed to clarify 'content' but never mentions it, leaving an agent unsure whether it is a filter, output, or payload.

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 ('Read') and identifies the exact resource ('magents-owned shared note for a working directory'). The closing sentence ('Not first-party agent memory') differentiates it from sibling memory tools like read_memory.

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 establishes clear context for when the tool applies (reading the shared note tied to a cwd) and explicitly excludes first-party agent memory. It does not name the alternative tool, but the sibling list makes read_memory the obvious counterpart.

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

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

With no annotations, the description must carry behavioral meaning itself. 'Look up' suggests a read-only operation, but the description gives no detail on not-found behavior, title-fragment matching, or whether the operation has any broader side effects or constraints.

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?

One sentence with no filler, front-loading the action and resource before the identifier variants. Every word contributes to the purpose.

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

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

The description is adequate for a simple single-session lookup, and the schema fills in the 'latest' option. The optional limit semantics and the multiple-match risk of a 'title fragment' are not clarified, so it is minimally complete rather than 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?

The description adds value by exposing identifier aliases, including 'pid', beyond the schema's session_id text. It does not explain the limit parameter, which is also undocumented in the schema, so semantic coverage is only partial.

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

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

The description states a specific action ('look up') and a specific resource ('one session'), then enumerates accepted identifier forms: id, live name, title, pid, and agent:ref. The singular 'one' clearly contrasts with the sibling list_sessions, making the purpose 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?

It implies the tool should be used when a single session is needed by a known identifier. However, it does not explicitly say when not to use it or name alternatives such as list_sessions or session_digest, so the agent must infer the boundary.

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

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

With no annotations, the description carries the behavioral disclosure burden. It usefully discloses that a compact state is transferred and that the target must be an existing live session, but it does not state downstream effects such as whether the current session stops, whether the target must accept the handoff, or failure behavior.

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

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

Two short sentences, with the main action front-loaded and the optional-parameter usage note immediately after. There is no filler or duplication beyond the small overlap with the schema.

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 plus fully covered schema is enough to know what arguments to pass and that this is a handoff, but the absence of an output schema and annotations leaves gaps about the lifecycle effect and result of the handoff. It is adequate for simple invocation but not fully self-contained.

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 parameter descriptions already document `to` and `reason`. The tool description only repeats the omit-to-select behavior and adds little semantic information beyond the schema, matching the baseline for fully covered schemas.

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 concrete action ('hand this work') and a specific target class ('another existing live agent'), which clearly separates it from sibling tools like spawn_session or send_message. The instruction to omit `to` for auto-selection also clarifies the primary purpose in one line.

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 a clear usage context: use this when work should be transferred to another live agent, and it explains how to fall back to auto-selection. It does not explicitly list alternatives or exclusions, but the 'existing live agent' wording implicitly rules out spawning or messaging tools.

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

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

With no annotations, the description carries the behavioral burden; it does disclose this is a read operation on an inbox where cross-agent messages land. It does not explain whether reading affects unread state, how since filtering behaves, or any permission/availability constraints, but the read intent is clear.

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

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

Two short sentences, front-loaded with the action and resource; no filler. The typo 'magents' is minor and does not undermine structure.

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

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

For a 4-parameter tool with no output schema or annotations, this description covers only the basic read behavior and session default. It omits the meaning of agent and unread_only, return shape, and filtering semantics, so an agent cannot fully anticipate tool behavior.

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

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

Schema coverage is only 25% and the description only clarifies session_id ('this session or a given session_id'). The agent and unread_only parameters are left unexplained, and since is only documented in the schema. Low coverage means the description should compensate 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?

States a specific verb and resource: 'Read the magents inbox' and adds the key context that cross-agent messages land there. It is clear what the tool does, though it does not explicitly differentiate against sibling tools like read_transcript or get_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 implies usage: read this session's inbox when you need messages left by other agents, optionally for a given session_id. It gives no explicit when-not-to-use guidance or alternatives, so the routing is only inferred.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses key traits: writes a run directory with specific artifacts (sessions, surfaces, usage, phrases, plan.json mapper shards), default scope is all history, and it does not change skills. However, it omits critical mutation details: whether it overwrites existing run directories, permission requirements, and destructive potential. The 'Does not change skills' is a useful safety clarification, but gaps remain for an 11-param write tool.

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

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

Three sentences that are front-loaded: the primary action first, then output artifacts, then safety note. Efficient, though the second sentence is slightly dense with artifacts.

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 an 11-parameter write tool with no annotations, no output schema, and 36% schema coverage, the description is significantly incomplete. It lacks details on most parameters, behavioral constraints like overwrite behavior or permissions, and how the estimator mode differs. The basic purpose and output are covered, but much is missing for correct invocation.

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

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

Schema coverage is 36%, well below 50%, so the description must compensate. It mentions default scope (all history) which relates to time-based params, and describes the run directory output that out parameter controls, but does not explain semantics for cwd, days, agent, batch, limit, since_last, drop_pattern, include_headless, or include_subagents. The schema provides descriptions for only 4 parameters, leaving many undocumented in both places.

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

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

The description states a specific verb+resource: 'Collect compact session records from every local agent for /learn, or estimate the cost of a run.' It distinguishes the dual-mode operation and names the /learn context. No sibling tools overlap this collection behavior, though the description doesn't explicitly contrast with learn_state or session_digest.

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 implies usage ('for /learn') and notes the estimate mode, but doesn't specify when to use collection vs. estimation, or how it relates to sibling tools like learn_state or session_digest. The when is only hinted at through the /learn reference.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it only says the tool 'reads or updates' state. It does not disclose that actions like clear, trash, and restrict are destructive, whether 'undo' makes changes reversible, or what permissions are needed — a significant gap for a mixed read/write tool.

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

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

The two sentences are front-loaded and waste no words, but for a 15-parameter tool with branching actions this level of brevity is under-specification rather than concision. Nothing earns its place beyond the action enumeration.

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 15 parameters, no annotations, no output schema, and 27% schema coverage, the description leaves the agent without enough information to invoke the tool correctly for any action beyond the trivial 'get'. This is completely inadequate for the tool's complexity.

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

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

Schema description coverage is only 27% across 15 parameters, so the description must compensate and does not. Ten-plus parameters (kind, mode, note, path, undo, paths, scope, status, target, run_dir, run_name, item_action) are left entirely unexplained, and the one enum it restates (action) is already documented in the schema.

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

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

States a specific verb pair ('read or update') and resource ('magents /learn state'), plus enumerates the six valid actions, so the agent knows the tool's domain. However, it does nothing to distinguish it from the sibling learn_collect, which also operates on the /learn surface, so it falls short of a 5.

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

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

The description lists the action values but gives no guidance on when to use get vs set vs decide vs trash, and no indication of how this differs from learn_collect or the other sibling tools. The agent must guess which action applies to its situation.

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

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It does not reveal that sessions come from seven different tools, which is implied by the list, nor does it disclose ordering, filtering semantics, or what 'live' means (e.g., active processes vs. recent). It does not mention whether archived sessions are excluded by default, which is a key behavioral detail. The description gives some context via agent names but falls short of the needed transparency.

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

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

The description is a single sentence of about 15 words, which is efficient and to the point. It front-loads the resource type and includes a meaningful ordering note. There is no waste, but it omits essential details that would make it more useful, so while concise, it is not a model of completeness.

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

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

The tool lists sessions across seven tools with seven parameters nine of which are undocumented (43% coverage). There is no output schema, so the agent must rely on the description to know what the response contains. The description does not describe the output format, how to handle pagination (limit), or what 'live' implies. For a list operation with significant filter parameters)Skip, as in previous, this is inadequate.

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 43% (3 of 7 parameters have no description: limit, query, live_only, include_archived). The description does not explain any parameter semantics, so it does not compensate for the uncovered parameters. For the parameters that are described, the schema already provides adequate descriptions, so the description adds no value beyond schema. Baseline is 3 because schema covers a significant portion, but the 43% coverage is a gap that the definition should address.

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 definition names a specific verb ('List') and a clear resource ('sessions') across seven named tools, and adds a scope qualifier ('Live agents first'). It is more specific than a mere restatement of the tool name. However, it does not explicitly distinguish itself from closely related siblings like 'get_session' or 'session_digest', so the purpose is clear but lacks 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 says 'List ... sessions' which implies it is for discovery, but gives no explicit when-to-use guidance or conditions that would route an agent to an alternative, such as 'get_session' for a single session or 'session_digest' for a summary. The phrase 'Live agents first' hints at a default ordering but not when to use the live_only filter. With siblings present assuredly, the definition is strongly lacking.

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

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

With no annotations, the description must carry the behavioral burden. It does disclose the critical side effect 'Overwrites' and clarifies the ownership scope. Yet it omits other behavioral details such as whether the operation is idempotent, whether it appends or truncates, or any return value. The overwrite disclosure is key, but the overall transparency is incomplete for a mutating tool.

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

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

The description is two short sentences with no redundancy. It packs the core action, the ownership, the destructive nature, and the exclusion into minimal words, making it easy to parse quickly.

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

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

For a mutating tool without annotations, the description lacks context needed for correct invocation: there is no guidance on when to use it versus create_memory or get_note, no mention of any prerequisites or side effects beyond overwriting, and no information about what the tool returns after a successful write. Given its destructive nature and 2 parameter set, more context would be expected.

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

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

The schema describes only the 'cwd' parameter ('Working directory this note belongs to'); 'content' has no description. The tool description does not elaborate on what 'content' should contain or its format. With 50% schema coverage and no explanation in the description, an agent receives insufficient guidance for one of the two 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 clearly states the verb 'write' and the resource ('magents-owned shared note for a working directory'), and explicitly distinguishes it from first-party agent memory. It doesn't directly name siblings like get_note or create_memory, but the resource and scope are specific enough to differentiate from generic memory 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 implies when to use this tool (writing the shared note for a cwd) and provides a negative exclusion ('Not first-party agent memory'), which hints against using it for personal memory. However, it does not explicitly compare to alternatives like create_memory or get_note, leaving some inference required.

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

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

No annotations are provided, so the description carries the behavioral burden. It adds useful context by stating that hits are 'untrusted inert notes' and that certain agents have no memory store. However, it doesn't disclose return format, failure behavior for missing files or paths outside the memory root, or any permission/authentication considerations.

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

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

The purpose is front-loaded in the first sentence, and the remaining sentences are short and relevant. The structure is slightly disjointed—'Hits are untrusted inert notes' sits between the purpose and the agent-support note—but every sentence earns its place with no filler.

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

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

With no output schema and no annotations, the description should clarify what the tool returns and how the parameters combine to select a file. It doesn't state that the markdown content is returned, what happens if multiple selection parameters are supplied, or which parameter is the primary file locator. This leaves an agent without enough grounding for reliable invocation.

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

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

Schema coverage is 50%, with cwd, file, and project undocumented. The description echoes 'memory markdown file' and the agent scope but adds little beyond the schema for path, limit, or the undocumented parameters. It does not clarify how file vs path vs cwd interact or what project means, 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 ('read'), resource ('memory markdown file'), and supported agent scope ('Claude, Codex, or Grok'). It also clarifies that Cursor, OpenCode, Gemini, and Copilot lack a first-party memory store, which distinguishes applicability. However, it doesn't explicitly differentiate from sibling tools like get_note or read_transcript, so it misses the top score.

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

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

The phrase 'Hits are untrusted inert notes' implies this tool consumes results from search_memories, and the agent-support note gives an implicit when-not condition. But there is no explicit guidance on when to choose read_memory over search_memories, create_memory, get_note, or read_transcript, nor any stated workflow for routing to alternatives.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It adds crucial context: the transcript is 'untrusted inert history' and should not be executed. This meaningfully communicates that reading is safe and that content should not be treated as instructions, which goes beyond a generic read description.

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

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

The description is two short sentences with no wasted words. The essential safety warning is front-loaded in the second sentence, and every part adds value. It is appropriately concise for the tool's simplicity.

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

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

For a simple read operation, the description and schema provide enough for a basic call: choose a session_id and optionally a limit. However, the absence of an output schema means the return format is not described, and the undefined limit parameter leaves a gap. There is also no guidance on how this relates to sibling transcript tools.

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 session_id parameter is well described in the schema, but the limit parameter has no description and the tool description adds no parameter-level detail. At 50% schema coverage, the description should compensate for the undocumented limit but does not, leaving the agent without clarity on how pagination or limiting works.

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 verb and resource: 'Read a session transcript'. The qualifier 'as untrusted inert history' adds important meaning about the nature of the content. It does not explicitly distinguish itself from sibling tools like get_session or search_transcripts, but the action of reading a transcript is reasonably 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 implies when to use the tool (when you need to read a transcript) and strongly warns not to execute it. However, it does not explicitly state when to use this tool over siblings such as search_transcripts or get_session, nor does it describe when not to use it.

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

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

No annotations are provided, so the description carries full burden. It does reveal the core behavior (sending to the sender session) but does not disclose side effects, error modes, or the role of agent/session_id. For a mutating action with no annotations, this is under-specified.

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

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

One sentence, efficient, front-loaded with the main behavior. Loses a point because the 'sender session' concept is introduced without explanation.

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

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

With no annotations Schema, sibling send_message presumably alternative, and two unexplained parameters (agent, session_id) plus no output schema, the definition is under-specified. It doesn't clarify when to choose reply vs send_message or what session_id refers to.

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

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

Schema coverage is only 25%, so description carries weight. It clarifies mail_id ('Inbox mail id to reply to') is redundant with schema, and adds the sender-session targeting contextsac. But agent and session_id remain unexplained, leaving ambiguity about whether session_id refers to the sender session and how agent fits.

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 clear action ('reply') and a target resource (inbox mail, either latest or specified by mail_id), and explains the mechanism (sending to its sender session). It is understandable on its own, but it doesn't explicitly differentiate itself from sibling tools like send_message or await_reply beyond the reply-to-mail concept.

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 states when to use it (to reply to latest mail) but offers no guidance on when not to use it, no alternatives, and no requirements such as needing an existing session or the meaning of session_id. The agent is left to infer conditions like 'session must already exist'.

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 discloses that hits are 'untrusted inert notes,' which is valuable behavioral context beyond what annotations provide (annotations are absent). This tells the agent that results are not executable or trusted content. It doesn't mention rate limits or pagination, but the 'inert notes' disclosure is a meaningful behavioral trait.

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, front-loaded with the core action and scope, then a useful exclusion note. Every sentence earns its place with no filler.

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

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

For a search tool with 3 params and no output schema, the description covers the main purpose and the trust level of results. It lacks parameter-level detail for 'agent' and 'limit', but the core use case is clear. The sibling list includes read_memory and search_transcripts, so the description's scope statement helps disambiguate, though it could explicitly mention alternatives.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. The description explains the query concept ('search for a phrase') but doesn't detail the 'agent' or 'limit' parameters. The agent parameter is not explained, and limit is not described. With 0% schema coverage, the description should compensate more, but it does clarify the core query semantics.

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

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

The description states a specific verb ('Search') and resource ('Claude, Codex, and Grok memory markdown') and clearly distinguishes the tool's scope from other memory-related tools. It also names which tools have no first-party memory store, which helps an agent understand exactly what this tool covers.

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

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

The description gives clear context on when to use this tool: when searching memory markdown for a phrase. It also provides an exclusion by noting that Cursor, OpenCode, Gemini, and Copilot have no first-party memory store, which implicitly tells the agent not to expect results for those. However, it doesn't explicitly name alternative tools like read_memory or search_transcripts for other use cases.

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

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It clearly states the scope of the search (which AI tools are included) and the query parameter, but it does not disclose search behavior details such as case sensitivity, partial matching, ranking, or whether results are returned in any particular order. It also doesn't mention any authentication or rate limits. However, for a search tool, this is adequate basic transparency, but it could be more explicit about the search semantics.

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

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

The description is a single, concise sentence that efficiently conveys the tool's purpose. It lists the AI tools explicitly, which is valuable but makes it slightly longer. There is no fluff, and it is front-loaded with the main action. It could be more structured by separating the tool list, but it is appropriately sized for the information it provides.

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

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

Given the tool's moderate complexity (4 parameters, no output schema), the description is partially complete. It explains the query parameter's purpose and scope but leaves the other three parameters undocumented, which is a notable gap. There is no output schema to indicate the return format, so an agent might not know what to expect. The description is adequate for basic use but not fully complete for agents needing parameter details or knowing how results are returned.

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 has 0% description coverage, meaning the description provides no parameter-level details. The tool name and description only explain the 'query' parameter implicitly; the other three parameters (agent, limit, include_archived) are not described at all. With 0% coverage, the description should compensate, but it doesn't. It would be helpful to explain that 'agent' filters by AI tool, 'limit' caps results, and 'include_archived' includes archived transcripts. Therefore, the description fails to add meaning for most parameters, but it does at least clarify the query's purpose.

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

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

The description clearly states the tool's purpose: searching transcripts from multiple specific AI tools for a given phrase. It uses a specific verb ('search') and resource ('transcripts'), and lists the exact AI platforms covered. This distinguishes it from sibling tools like 'search_memories' (which searches memories) and 'read_transcript' (which likely reads a single transcript).

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 implicitly conveys when to use this tool: when you need to search across transcripts from the listed AI tools. However, it does not explicitly mention when not to use it or suggest alternatives, such as using 'search_memories' for memory searches or 'read_transcript' for viewing a specific transcript. There is no explicit guidance on prerequisites or conditional use.

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

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

With no annotations, the description carries the full behavioral burden. It goes beyond a simple 'send' statement by revealing that messages are always queued in the magents mailbox and that delivery may use native IPC or fall back to a supervised headless CLI. These are non-obvious behaviors that affect agent expectations, even though error behavior is not fully specified.

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

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

The description is two concise, front-loaded sentences with no redundant phrasing. The core action, target scope, preferred execution method, and queuing behavior are each stated once, and every clause earns its place.

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

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

For a two-parameter send operation, the description covers the main intent, supported targets, and delivery behavior, and no output schema exists so return-value detail is not expected. However, it omits error behavior for invalid or missing sessions, how to confirm delivery, and explicit guidance that a caller likely needs await_reply to receive responses—especially given the sibling tool list.

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 50%: 'to' has a description, but 'message' has none. The tool description adds no parameter-level details—it just repeats the word 'message' and mentions 'existing chat,' which does not meaningfully clarify formats, limits, or target resolution beyond the schema's existing gloss.

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

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

The description states a specific action ('Send a message') with a clear resource ('existing ... chat') and enumerates the supported client types, so an agent immediately knows the core function. It does not explicitly distinguish itself from sibling tools like reply or spawn_session, so it stops short of a 5.

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

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

The description implies this is for existing conversations rather than creating new ones, and it offers implementation guidance (native IPC preferred, headless CLI as fallback). However, it never explicitly says when to choose send_message over reply, handoff, or spawn_session, nor does it mention prerequisites or exclusions.

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

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

With no annotations provided, the description carries the full burden and explicitly states 'inert' and 'Does not inject,' making the read-only, side-effect-free behavior clear. It also discloses the summary contents and 'clipped turns,' hinting at truncation. It does not cover errors or permissions, but core behavior is well disclosed.

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, dense sentences with no filler. The first sentence front-loads the tool's purpose and output contents, and 'Does not inject' earns its place by clarifying side-effect behavior.

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

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

For a low-complexity tool with no output schema, the description names key output fields and confirms non-injection. Still, it leaves ambiguity about how the limit parameter controls results, what 'clipped turns' means exactly, and behavior when the session cannot be found. A bit more context would make invocation fully safe and predictable.

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%: session_id is documented in the schema, but limit has no schema description and is never explained in the description. 'Clipped turns' loosely hints at limiting or truncation, but it does not explicitly map the limit parameter to its effect. The description does not compensate for the undocumented parameter.

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

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

The description clearly identifies the tool as a compact, inert summary of a session and enumerates the returned fields: last request, last action, cwd, branch, clipped turns. It lacks an explicit verb like 'get' or 'read', and does not directly distinguish itself from siblings like get_session or read_transcript, though 'does not inject' separates it from action-oriented 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?

Usage is implied by 'compact inert summary'—an agent can infer it is for quick session overviews. However, there is no explicit guidance on when to prefer this over get_session, read_transcript, or list_sessions. 'Does not inject' provides a constraint but not a full when/when-not routing rule.

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

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

With no annotations available, the description carries the behavioral burden and does well: it discloses headless persistence, independent session execution, approval behavior, and the crucial asynchronous semantic that an accepted response does not mean completion. It could additionally mention return shape or how to later retrieve results, but the disclosed behaviors are substantial.

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

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

Four sentences, each earning its place: purpose, task requirement, collision safety, approval and async semantics. The most important information is front-loaded, and there is no filler or redundant restating of the schema.

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

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

For a tool with no output schema and no annotations, the description covers the core invocation requirements, safety concerns, and response interpretation. The only minor gap is not specifying what the accepted/starting response actually contains or how to subsequently await completion, but the async caveat is already explicitly stated.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining when cwd matters ('when concurrent edits could collide') and by framing message as a complete task that must include verification and reply instructions. This is meaningful enrichment, not schema repetition.

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: 'Start a new headless persisted ... session for independent work.' It names the supported agents and clearly separates this launch action from sibling tools like list_sessions, get_session, stop_session, and await_reply. An agent can identify exactly what spawn_session does without opening the schema.

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

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

It gives concrete usage guidance: provide a complete task, request a reply, and pass an isolated cwd when concurrent edits could collide. It also clarifies that host approvals still apply. It does not explicitly name alternatives or say when not to use it, but the context is strong enough for correct invocation.

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

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

With no annotations, the description carries the behavioral burden. It discloses its primary effect and a non-effect (not killing hosts), but doesn't say whether the stop is graceful, whether session data is preserved, or whether the session can later be resumed. Some behavioral context is provided, but important side-effect details are missing.

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 core action is front-loaded, and the clarifying boundary ('Does not kill Desktop/TUI hosts') is placed immediately after.

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

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

For a single-parameter imperative tool with no output schema, this covers the action, scope, and an important boundary. It could mention post-stop state or cleanup behavior, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, and the schema already documents that session_id accepts an id, title, or 'agent:ref'. The description adds no parameter-specific detail beyond the schema, so the baseline 3 applies.

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

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

The description uses a specific verb ('Stop') and resource ('session'), scoped to 'magents-supervised spawned or resumed sessions'. It also explicitly says it does not kill Desktop/TUI hosts, which distinguishes this from host-level termination and from sibling tools like get_session or spawn_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?

It gives a clear condition for use: stopping a magents-supervised spawned or resumed session, and a clear when-not signal with 'Does not kill Desktop/TUI hosts'. It doesn't name alternative tools, but the stop operation has no close sibling, so the implied usage context is enough.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It reveals concrete behavior by listing the resolution sources: env, messaging socket, or a unique live cwd match. This is useful context, though it does not discuss failure modes or exact return format.

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

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

The description is two short sentences, front-loaded with the core purpose and followed by a concise explanation of the resolution mechanism. Every word earns its place with no repetition or filler.

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

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

For a simple no-parameter tool, the description is largely complete: it states the tool's purpose and the sources it uses to resolve identity. It does not specify the exact return shape or error behavior, but these gaps are minor for this tool's low complexity.

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

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

The tool has zero parameters, so the rubric baseline is 4. The description does not conflict with the empty input schema and there are no parameter semantics to explain.

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

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

The description clearly states what the tool does: 'Who this MCP connection is running as.' It then adds a specific verb and method, 'Resolves session id from env, messaging socket, or a unique live cwd match,' which distinguishes it from sibling session-related tools like get_session and list_sessions.

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 the tool is used when an agent needs to know the current connection's identity, but it does not explicitly state when to use it versus alternatives or provide exclusion criteria. The resolution-source detail provides some context, but no direct routing guidance is given.

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