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

With no annotations, the description carries the full burden and does so: refusal semantics, returning the holder, hierarchical folder coverage that blocks ancestor/descendant claims, relative-path resolution against the session's project, TTL expiry, and lock death with the session. This is real behavioral disclosure an agent cannot infer from the schema.

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

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

Four tight sentences, front-loaded with the action and its timing, then failure mode, then scoping rules, then lifetime. Every clause carries operational information; nothing is filler.

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

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

There is no output schema, and the description explains the refusal case returns the holder but not what a successful claim returns (lock identifier? confirmation?), which an agent may need before writing. Otherwise complete for a 3-parameter tool with full schema coverage.

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

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

Schema coverage is 100%, so baseline is 3; the description adds meaning beyond the schema by explaining that a relative path resolves from this session's project and that a folder path implies subtree coverage. ttl defaults are restated from the schema but the hierarchy semantics for `path` are genuinely new.

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 ('cooperatively lock a path') plus the motivating timing ('before editing it'), so an agent immediately knows this is a mutual-exclusion claim, distinct from the read/write state tools. It does not explicitly name its counterpart release_path, so sibling differentiation is implied rather than stated.

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?

Strong guidance: use before editing, expect fail-fast refusal, and on refusal 'coordinate or pick another territory instead of retrying in a loop' — an explicit anti-pattern. It stops short of naming release_path as the exit path or describing multi-path claim ordering strategies.

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?

As there are no annotations, the description must carry all behavioral context. It clearly states crucial constraints: it 'does not delete raw observations, only marks them as compressed,' and explains the functional benefit (reduces token count).

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 paragraph is highly dense with information, covering function, constraints, behavior, and workflow guidance efficiently in a single cohesive block.

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

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

The description is complete; it details the input parameters' purpose, the resulting state of the raw data (marked, not deleted), and the expected output format (count and human-readable summary).

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 100% schema coverage, the description isn't required to explain syntax, but it successfully frames the use of the parameters (like 'since') within the context of targeted data reduction.

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 purpose is stated explicitly: compressing raw hook observations into structured, typed summaries. It clearly distinguishes itself from other state management tools by focusing on data reduction.

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

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

It provides explicit workflow instructions: the tool must be called 'before get_state or at session start' to ensure the data is compact before memory loading.

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, and the description does not explicitly state whether the tool is read-only or modifies any state. While the focus on 'analyze' suggests non-destructive behavior, it does not confirm side effects like persistence or data retention, leaving the agent uncertain about its impact.

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

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

The description is extremely concise, consisting of two clear sentences that cover functionality, parameters, output, and usage context. There is no redundancy or extra fluff, making it efficient for agent parsing.

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 lack of an output schema, the description adequately summarizes the return structure (array of pattern objects with specified fields). It also contextualizes the parameters implicitly by stating what they control. This is sufficient for a simple tool, though it could be slightly more detailed about edge cases.

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

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

The schema provides complete descriptions for both parameters (window_days and min_occurrences) with defaults, so the baseline is 3. The tool description does not add any extra nuance beyond what is in the schema, so it stays at the baseline.

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

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

The description clearly states the tool's function: analyzing runtime hook events to surface recurring behaviors. It distinguishes itself from sibling tools by focusing on pattern detection and automation suggestions, making its 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 provides explicit guidance on when to use the tool ('after several sessions of work'), which helps the agent decide when to invoke it. However, it does not mention when not to use it or alternative tools for single-session analysis, so it loses a point for incomplete context.

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

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

With no annotations, the description carries the behavioral burden. It clearly frames the tool as a read-only health probe that 'returns' metadata and even specifies the content. It could additionally state that it has no side effects or how it behaves when the server is down, but the 'returns' wording and verification purpose make the read-only nature evident.

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 tightly scoped sentences: the first defines the output with specific detail, the second gives usage guidance. Nothing extraneous is present, and the core purpose is front-loaded.

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

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

For a zero-parameter health-check tool with no output schema, the description fully covers what it returns (with possible values), when to call it, and why. An agent has enough information to invoke it correctly.

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

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

The tool takes zero parameters, so the baseline is 4. The schema coverage is vacuously 100%, and there are no parameter semantics for the description to add.

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 purpose: returns server health metadata for the active project, listing exact fields (storage engine variants and write arbitration mode). It distinguishes itself from sibling tools by noting it should be used before get_state or update_state, so an agent can tell it apart.

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

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

Provides explicit usage context: 'Use this to verify the egc-memory server is running and responsive before calling get_state or update_state.' This names the sibling tools that follow it and the exact condition for using this tool, leaving no ambiguity about when to invoke 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?

Since no annotations are present, the description carries the entire burden of disclosure. It provides exceptional behavioral detail, explaining complex scoping rules (git branch vs. detached HEAD) and precedence (project > global memory) which are crucial behavioral traits.

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 necessarily long due to the complex state management logic (git vs. flat vs. global). However, it is logically structured, starting with what it returns and ending with the mandatory usage guidance.

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

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

It is extremely complete, covering the data structure (memory content), the retrieval mechanics (scoping rules like detached HEAD vs. flat state), and the required operational context (start of session). No critical information is missing.

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

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

While the schema is straightforward, the description provides essential semantic context for 'project_path' by defining that the parameter determines the project root, which is the basis of the entire memory lookup scope described.

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 primary purpose: 'Returns the current project memory.' It distinguishes itself by detailing the specific contents (decisions, preferences, things to avoid) and the specific operational scope of the memory retrieval.

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

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

It provides explicit usage instructions: 'Call this at the START of every session to restore context.' This dictates exactly when the agent should prioritize this tool over others.

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 for behavioral disclosure. It explicitly notes the side effect 'Updates the last_recalled timestamp on matched lessons' and clarifies that decay is driven by last_reinforced, not last_recalled. This is critical because the tool name suggests a read-only search but it mutates 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?

Four concise sentences cover purpose, filtering, side effects, ranking, and usage context without filler. The structure is front-loaded with the core action and each subsequent sentence adds meaningful detail.

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 3 parameters and no output schema, the description is complete enough to guide correct invocation: it explains what is searched, which results are returned, how confidence filtering behaves, what side effect occurs, and when to call the tool.

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

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

Although schema coverage is 100%, the description adds meaning by specifying that query searches across 'content, context, and tags' and that results are ranked by confidence score descending. This supplements the schema's minimal parameter descriptions with behavioral 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 opens with a specific verb and resource: 'Search active lessons by keyword across content, context, and tags.' It further differentiates itself from sibling tools by clarifying that only lessons above min_confidence are returned and lower-confidence lessons are archived/hidden.

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

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

Provides clear invocation context: 'Call at session start to surface relevant patterns before beginning work on a known problem area.' It does not explicitly name alternatives or exclusion conditions, but the timing and purpose are clearly stated.

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

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

With no annotations, the description fully discloses side effects: it modifies confidence (with precise magnitude and cap) and can unarchive lessons. It also mentions the return value, making the tool's behavior transparent.

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

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

The description is concise and well-structured, with each sentence conveying distinct information without redundancy. It efficiently communicates purpose, behavior, usage, and output.

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 simple operation, the description covers all essential aspects: what the tool does, when to use it, its effects (including quantitative changes and unarchiving), and the return value. No critical information is missing.

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

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

The schema already fully describes the single parameter 'id' as 'The lesson ID returned by lesson_save or lesson_recall.' The description does not add additional parameter-specific information beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: reinforcing an existing lesson. It specifies the exact action, the effect on confidence (increase by 0.15, capped at 1.0), and the unarchiving behavior. This distinguishes it from related tools like lesson_save or lesson_recall.

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?

Explicit usage conditions are provided: 'Call this when a lesson recalled via lesson_recall proves relevant to the current task, or when the same mistake recurs.' This gives clear guidance on when to invoke this tool versus others.

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 load and does disclose real behavior: it persists, assigns a starting confidence (default 0.7), and that confidence decays over time when unreinforced. It omits what the call returns (e.g., an ID or confirmation) and whether the write is immediately durable across processes.

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, front-loaded with the core action, and each sentence adds something (persistence, decay semantics, dedup caveat, use cases). Minor redundancy in repeating the 0.7 default from the schema costs it a point.

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

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

For a 5-parameter write tool with full schema coverage and no output schema, the description covers purpose, defaults, decay, and the dedup caveat adequately. The only notable gap is return-value expectations, which matter for a mutation with no output schema.

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

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

Schema coverage is 100%, so all five parameters are already documented, including defaults for initial_confidence and author. The description only restates the 0.7 default and adds no format or interaction detail beyond the schema, making the baseline 3 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?

Uses a specific verb+resource ('Persist a new lesson learned') and scopes it to the current session. It is clearly distinguishable from sibling lesson_recall and lesson_reinforce by stating it creates rather than retrieves or reinforces.

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

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

Explicitly names the alternative ('call lesson_recall first to check whether a similar lesson already exists') and the condition that selects it, plus a positive use case ('patterns, heuristics, or observations the AI should carry forward across sessions'). It even states an exclusion: it does not deduplicate.

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 supplied, so the description carries the transparency burden. It does communicate that this is a paginated read-style operation and what fields are returned, but it does not explicitly state side-effect-freenature, ordering, empty-list behavior, or permissions. That gap keeps it at a moderate level.

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 just three sentences with no waste. It front-loads the main operation, then adds entry details, pagination, and a useful audit context all concisely.

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, the description responsibly lists the main entry fields and pagination mechanics. It does not specify default ordering although that is often relevant for history tools, but most core functional context is covered.

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

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

Schema description covers all 2 parameters (limit and offset) fully. The description only repeats the pagination concept, adding no new semantics beyond the schema baseline, so it is adequate but not additive.

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?

Description uses a specific verb and resource: 'Return a paginated list of past decisions stored in the SQLite state,' and describes the result fields. It is clear in operation, but it does not explicitly differentiate itself from the sibling search_history tool, so it misses the top differentiation bar.

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

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

The description provides a clear usage context: useful for auditing past decisions without loading the full project state. It does not mention when not to use it or what alternative tool to prefer, but the audit use case is a strong guide.

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

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

With no annotations, the description carries the burden well: it declares the authorization rule ('only the holder can release') and discloses the return semantics ('returns whether a lock was actually removed'), which is important for a mutation tool. It stops short of saying what happens on failure or whether the operation is idempotent.

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

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

Two tight sentences with zero waste, and the core action and its key constraint are front-loaded ahead of the return note.

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 small 2-parameter tool, the description covers purpose, authorization, and return value, and the schema documents both params fully. The only gap is failure behavior, which no output schema exists to compensate for.

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%, including a clear explanation that session_id should be omitted. The description adds nothing parameter-specific beyond what the schema already states, 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?

States a specific verb ('Release') and resource ('a path lock') with scope ('held by this session on the session bus'). It is clearly the inverse of a claim/acquire sibling, though it never names the complement explicitly.

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

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

Usage is only implied by the constraint 'Only the holder can release.' There is no explicit 'call this after claim_path' or 'do not call if no lock is held,' so the agent must infer the trigger condition from context.

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

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

No annotations are provided, so the description carries full burden. It discloses non-obvious behavior: rank algorithm (BM25/FTS5), result fields (content, context label, timestamp, score), and score normalization to [0,1]. It doesn't mention permissions or explicit read-only status, but 'search' implies a safe read operation; additional detail on output and scoring is strong.

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 core action and method, then result details and usage guidance. Every sentence earns its place with no 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?

Given there is no output schema, the description appropriately explains return content and score semantics. It covers ranking behavior, result fields, and score normalization, which is complete for a straightforward search tool with 3 simple parameters.

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%, with clear parameter descriptions for query, limit, and min_score. The tool description adds no extra parameter-specific guidance beyond reinforcing 'keyword search' and normalized score, which is sufficient but not additive.

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 performs keyword search over decision history using BM25 relevance ranking (SQLite FTS5), specifying both the verb and resource. It also distinguishes from sibling query_history by noting it is an alternative for finding past decisions by topic.

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

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

Explicitly states when to use: 'Use this to find past decisions by topic instead of paging through query_history.' Names the alternative tool query_history, giving clear context, but does not list exclusion conditions or other alternatives, stopping short of a full 5.

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

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

With no annotations, the description carries the full burden and delivers: it discloses the 10-minute staleness sweep, that locks are released for swept sessions, and that the call returns live peer sessions. That is meaningful side-effect and lifecycle context an agent cannot infer from the schema.

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

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

Four tight sentences, purpose front-loaded, then cadence, then the consequence of missing heartbeats, then the return value. No filler or repetition.

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?

No output schema, but the description explains what comes back (live peer sessions) and why it matters; combined with full schema coverage and no annotations, an agent has everything needed to call it correctly and interpret results.

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 each parameter already has a rich description (including the 'leave out' guidance for session_id and project_path fixing rules). The description only re-characterizes territory as an optional folder or theme, adding little beyond the schema, so 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?

States a concrete verb and resource ('Announce this session on the session bus: registers presence...') and clarifies scope: presence registration plus heartbeat, distinct from session_peers/session_send. The final clause on returning live peers further separates it from pure mutators like claim_path.

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?

Explicit timing guidance: 'Call at session start and periodically during long work,' plus the rationale 'so parallel sessions can split territory instead of colliding.' It does not explicitly name an alternative for just reading peers (session_peers exists), but the usage conditions are clear.

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

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

With no annotations available, the description carries the full burden and does real work: it discloses ordering (oldest first), the exactly-once delivery guarantee across calls, the cursor-advancing effect of a normal read versus peek, and a prompt-injection warning about untrusted payloads. It does not say whether the call blocks or returns empty when no events exist, which is the one behavioral trait an agent still has to guess.

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, zero waste, and the core behavior (what is read, in what order, with what delivery guarantee) is front-loaded before the safety warning and the peek hint. Every sentence adds distinct information.

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

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

There is no output schema, and the description never sketches the shape of an event (fields, sender, type), so an agent knows the delivery contract but not the payload structure. For a read tool with fully documented parameters and strong behavioral notes, that is a minor but real gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond restating fields by explaining the consumption consequence of peek ('look without consuming') and framing the read as cursor-advancing by default. The session_id and project_path constraints are left entirely to 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 and resource ('Read the events addressed to this session') with scope qualifiers (direct and broadcast, oldest first, delivered exactly once). It never names a sibling such as session_wait, so an agent must infer the difference between reading buffered events and waiting for new ones.

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 only usage instruction is 'Use peek: true to look without consuming,' which is guidance about a parameter rather than about when to choose this tool over alternatives. There is no statement about when not to call it or how it relates to session_wait, so usage is only implied by the description of what it returns.

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. 'List' implies a read-only operation and the description clarifies that it reports live sessions and active locks, but it does not disclose return format, pagination, permissions, or whether the result is scoped by visibility. For a read-only listing tool this is minimally adequate.

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 operation and followed by the usage condition. There is no redundant or wasted language.

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 one optional parameter, full schema coverage, no output schema, and no annotations, the description is largely complete for an agent to call it correctly. The main remaining gap is that it does not describe the shape of the returned listing, which matters slightly more because there is no output schema.

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

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

Schema description coverage is 100%, and the single optional parameter is already well documented in the schema, including the default behavior, refusal of a different project, and cross-project lock listing. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb, 'List,' and names two concrete resources: the live sessions of this session's project and every active path lock on the session bus. It is clear what the tool does, though it does not explicitly distinguish itself from adjacent tools such as team_status or get_project_state.

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 usage context: 'Use before starting parallel work to see who is active and which territories are taken.' This tells the agent when the tool is appropriate. It stops short of naming alternatives or stating 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?

With no annotations, the description carries the full burden and does well: 16KB payload cap, exactly-once delivery per receiving session, 24h retention, and the fact that a foreign session_id or project_path is refused. It omits any mention of what the call returns or error behavior on a dead target, keeping it short of a 5.

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

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

Three tight sentences that front-load the primary action, then delivery modes, then payload constraints and lifetime. Every clause carries operational information; nothing is padding.

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

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

For a 5-parameter, no-annotation, no-output-schema mutation tool, the description covers mode selection, payload limits, retention, and refusal semantics. The main remaining gap is the response shape / confirmation behavior, which the agent must infer.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: omitting to_session means project-wide broadcast, and the 16KB cap is framed as a design constraint with a recommended workaround (send a reference into project state). That is guidance the schema does not supply.

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 ("Send an event to another live session") and immediately distinguishes the two modes — direct vs. broadcast — plus the payload philosophy (intents and pointers, not bulk content). An agent can tell exactly what this does and how it differs from read-side siblings like session_events or session_wait.

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?

Explains the broadcast trigger ("by omitting to_session") and steers large content elsewhere ("store large context in project state and send a reference"). It does not name sibling alternatives for reading or waiting on events, so routing guidance is clear but not complete.

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

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

With no annotations, the description carries the full burden and does so well: mesh wake-on-write is ON by default, the opt-out env var is named, the degraded behavior is described, and the crucial side effect that the cursor advances (events consumed) is disclosed. It also flags the untrusted-payload safety requirement, which is unusual and valuable context beyond the schema.

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

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

The description is dense but front-loaded: core long-poll behavior comes first, followed by configuration/fallback details, then the security caveat. Every sentence conveys distinct operational information with no filler.

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

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

For a blocking-read tool with no annotations and no output schema, the description supplies what an agent needs: when it returns, what it returns (events addressed to the session), that consumption advances the cursor, and how behavior changes when push is disabled. The security warning about untrusted payloads closes an important gap.

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

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

Schema description coverage is 100%, so session_id, timeout_ms, and project_path are already fully documented in the schema. The description reinforces timeout behavior ('or timeout_ms elapses') but adds no new syntax, format, or constraint information beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb ('Long-poll') and resource ('the session bus') and precisely defines the return semantics: immediate when events are pending, otherwise blocking until an event or timeout. It distinguishes itself from session_events by noting consumption is identical but the wait behavior differs.

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?

Explicit conditions are given for selecting this tool: use it to wait for addressed events, with immediate return when pending. It also names a concrete alternative path ('degrades to a single session_events read') and the exact condition that triggers it (EGC_MESH_PUSH=0), leaving little to inference.

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

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

With no annotations, the description carries the full burden and does add real behavioral context: SQLite persistence, write-lock arbitration to prevent concurrent conflicts, and where the data is and is not visible (query_history/search_history vs. get_state). It does not cover failure behavior under lock contention, return value, or duplicate handling, which keeps it from a 5.

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

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

Three short sentences with the core action and concurrency behavior front-loaded, followed by the most important scoping fact (not part of get_state). The middle sentence largely repeats the schema's required parameters, which is the only minor waste.

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

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

For a two-parameter write tool with no annotations and no output schema, the description covers storage medium, concurrency safety, retrieval path, and state-visibility exclusion. It omits what the call returns and how lock contention surfaces to the caller, so it is nearly 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 100%, with both parameters documented and an example context label already in the schema. The description's 'short context label and the decision text' restates what the schema provides without adding format, length, or validation guidance, so 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?

States a specific verb and resource ('Persist a single decision to the SQLite store') and immediately distinguishes this store from sibling surfaces by noting decisions are queryable via query_history and search_history but are not part of get_state. An agent can tell exactly what this tool does and where the data lives.

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

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

Clearly implies when to use it (recording a decision) and routes the agent to the right retrieval siblings (query_history, search_history) while explicitly excluding get_state. It stops short of naming a direct alternative for writing decisions or stating when not to call it, so it is clear context without full 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, the description must carry the behavioral disclosure burden. It does disclose the core side effects: configuring team.json and setting up the git repository. However, it does not mention what happens on re-initialization, whether existing files are overwritten, authentication requirements, or any confirmation/output behavior, so transparency is partial.

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, no filler, and the most important usage constraint ('Call once per developer workstation') is placed early. Every sentence contributes information about what the tool does and when to run it.

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-time initialization tool with a fully documented schema, the description covers the main context: what gets configured, what storage mechanism is used, and the required precondition. It could also state the post-condition or next step (e.g., use team_sync afterward), but the core information needed to call it correctly is present.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds useful context by framing 'remote' as the 'shared remote URL from a teammate', but it does not meaningfully elaborate on branch, backend, or team_key beyond what the schema provides. 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 names a specific verb ('Initialize'), a clear resource ('sync backend for team memory sharing'), and concrete actions ('Configures the team.json file and sets up the git repository'). This distinguishes it from sibling tools like team_sync and team_status, which handle ongoing syncing/status rather than one-time setup.

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 the exact invocation context: 'Call once per developer workstation after receiving the shared remote URL from a teammate.' This gives clear when-to-use guidance. It does not explicitly name alternatives or state when not to use it, but the one-time setup framing makes the boundary reasonably clear.

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

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

With no annotations, the description carries the burden for behavioral disclosure. It clearly implies a read-only operation ('Show', 'verify') and lists the exact output fields. It does not mention potential errors, permissions, or side effects, but for a simple health-check tool this is adequate.

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 exactly two sentences, it is front-loaded with the primary purpose and provides an actionable usage suggestion in the second sentence. Every word adds value and there is no fluff.

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 dependency-free, zero-parameter tool with no output schema, the description fully captures its purpose, output, and appropriate timing relative to the sibling team_sync. It is simple, complete, and 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?

The tool has zero parameters, so the baseline for parameter semantics is 4. The description does not need to explain any parameter specifics and doesn't add redundant information about the empty schema.

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

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

The description clearly states the verb ('Show') and the resource ('team sync health'), specifying the exact data displayed (last sync time, uncommitted changes, conflict count, configured remote URL). It distinguishes itself from server-level tools like team_sync by focusing on status/health rather than execution.

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 'before or after a team_sync call' and frames the tool as a way to 'verify the sync backend is connected and working'. This provides clear context for when to use it relative to sibling tools, but it does not explicitly mention scenarios when it should not be used or alternatives beyond team_sync.

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 does disclose the conflict-resolution mechanism ('last-write-wins timestamp comparison'), implying newer lessons overwrite older ones. But it does not disclose return behavior, failure modes (e.g., no team connection), or idempotency for what is clearly a mutating push operation.

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

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

Three sentences, each earning its place: purpose+scope, conflict-resolution mechanism, and usage cadence. Front-loaded with the core action and free of redundancy.

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

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

For a moderately complex sync tool with no annotations and no output schema, the description covers purpose, conflict resolution, and invocation timing. However, it omits what the agent should expect after invocation (the absence of an output schema means the description carries that burden) and does not address error conditions or the risk of overwriting teammates' newer lessons.

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 0 parameters, earning a baseline of 4. The description adds meaning by implying the operation is a bulk sync of all lessons without filtering, which justifies the empty input schema.

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

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

The description opens with a specific verb+resource pair ('Synchronize team memory') and adds directional detail ('pull remote lessons from teammates and push local lessons'). This bidirectional framing clearly distinguishes it from siblings like team_init, team_status, lesson_save, and lesson_recall.

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?

Explicit when-to-use guidance is given: 'Run this periodically during a session to stay in sync with the team, or at session boundaries.' However, it does not explicitly name alternatives or state when not to use the tool, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden and does well: it discloses the merge semantics ("does not erase previous memory"), the path-resolution rule for branch vs detached HEAD, and precisely what force does (rename to '.corrupted-backup-<timestamp>', nothing merged, nothing deleted). It stops short of stating failure behavior for non-corruption errors or what the call returns on a conflicted write.

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

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

Four sentences, front-loaded with purpose, then write target, then timing, then merge guarantee. Each sentence carries information; only the merge guarantee reads slightly redundant with the opening line.

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 8-parameter mutation tool with no annotations and no output schema, the description covers the things that would actually cause mistakes: where the write lands, that it merges rather than replaces, when to call it, and the safe recovery path. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already explains scope, force, project_path and the structured fields; baseline is 3. The description adds only the temporal framing ("decisions made this session") on top of that, and says nothing about next/avoid/preferences/context beyond what the schema provides.

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

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

States a specific verb and resource ("Updates the project memory with decisions made this session") and immediately pins down the write target: branch state file, or the commit's own state file on detached HEAD. That distinguishes it from a plain single-decision writer, though it never names the sibling it is not (e.g. store_decision), so an agent must infer the split.

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?

"Call this at the END of every session" gives an explicit trigger, and the merge-vs-force guidance says when force is and isn't appropriate ("only set this after confirming the failure is persistent, not a transient lock"). It lacks any explicit routing to alternatives among the many sibling state/decision 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 full burden and does: it discloses the missing-key/expired-key return value (null), states it does not throw, and asserts no mutation or TTL extension. Those are exactly the idempotency and side-effect facts an agent needs before calling a read tool repeatedly.

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, front-loaded with the core action, then the return contract, then the alternative. Nothing repeats the name or the schema and no sentence is filler.

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

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

No output schema exists, and the description compensates by specifying the return value and its null case. Combined with the 100%-covered input schema, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented and the baseline is 3. "By key for the current project" loosely hints at project_path scoping but adds no syntax or format detail 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?

States a specific verb and resource ("Retrieve a single transient entry by key") plus the scoping constraint ("for the current project"), which separates it cleanly from working_memory_list and working_memory_set in the sibling list.

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

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

Explicitly names the alternative and the selecting condition: "Use working_memory_list when the key is unknown or to audit all active entries." That is a direct when-to-use-this-instead rule, not an inference.

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

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

With no annotations, the description fully covers behavior: returns empty array when no entries, entries include key/value/expires_at, expired entries excluded, and ordering by key. No contradictions.

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 concise sentences with front-loaded purpose, no unnecessary words, clear 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?

Covers all essential aspects for a list tool: ordering, exclusion of expired, return format, and empty case. Minor omission of pagination but not critical given tool nature.

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

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

Schema description coverage is 100% for the single optional parameter, so the description does not need to add parameter info. It neither adds nor detracts, meeting baseline.

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

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

The description clearly states it lists all live transient key-value entries for the current project, ordered by key, distinguishing it from sibling tools like working_memory_get and working_memory_set.

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

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

Explicitly states use cases: to audit active transient state or check key existence before calling working_memory_get, guiding the agent on when and how to use this tool.

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

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

With no annotations, the description carries the burden well: it discloses auto-expiry, the default TTL, silent overwrite of an existing key, and project scoping. It stops short of saying what the call returns (no output schema exists) or how invalid/oversized input or expired-key reads behave, so the mutation/return contract is only partly covered.

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

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

Four short sentences, front-loaded with purpose, then lifecycle, then overwrite behavior, then routing guidance. Every sentence carries distinct information and the sibling reference is placed at the end as a natural decision point.

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-parameter write tool with no annotations and no output schema, this covers scope, expiry, overwrite, and alternatives, which is nearly everything needed to call it correctly. The remaining gap is the return value and failure modes (invalid TTL, expired key), which nothing else in the definition supplies.

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 each parameter already documents its role, range, and default. The description only restates the TTL default and the overwrite-by-key semantics, adding little syntactic or format detail beyond what the schema provides.

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

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

Names a specific verb and resource ('Store a transient key-value entry scoped to the current project') and immediately frames the lifecycle (TTL-based expiry) that distinguishes it from persistent siblings. The contrast with update_state and the persistence boundary makes it unmistakable versus working_memory_get/list.

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

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

Explicitly lists intended uses (debug flags, temporary task context, values that must not pollute long-term state) and an explicit exclusion ('Do not use for data that must survive a session restart, use update_state instead'). The alternative is named with the condition that selects it.

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