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

With no annotations, the description must carry the behavioral burden. It discloses cooperative locking, fail-fast refusal, lock expiration (ttl), and session-based death. However, it does not describe what the tool returns on success (e.g., confirmation or lock token), which is a gap for an agent using the 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 three sentences with no wasted words. The first sentence front-loads the core purpose. Every sentence adds necessary detail about behavior and constraints.

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 no output schema and no annotations, the description adequately explains locking behavior but omits success return value and does not mention the need to later release the lock (via release_path). This leaves the agent with some ambiguity about the full workflow.

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 input schema covers all three parameters with descriptions (100% coverage). The description does not add any parameter-specific meaning beyond the schema: it repeats the default ttl_seconds but does not provide additional guidance on path or session_id. Baseline of 3 is appropriate.

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

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

The description directly states: 'Cooperatively lock a path on the session bus before editing it.' The verb 'lock' and resource 'path' are specific. This distinguishes it from sibling tools like release_path (unlock) and working_memory_* (memory operations).

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 clear usage context: use before editing, and fail-fast if lock is held. It explicitly advises against retrying in a loop, suggesting to 'coordinate or pick another territory instead.' However, it does not explicitly mention the counterpart release_path for releasing the lock, though the sibling exists.

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 exist, so the description carries full disclosure burden. It critically states 'Does not delete raw observations — only marks them as compressed,' clarifying non-destructive behavior. Also specifies return value (count and summary). While it omits error handling and permissions, it covers the most crucial safety aspect.

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 for the information it conveys, front-loading the core action and types. All sentences contribute: purpose, usage timing, non-destructive note, and return value. It could be trimmed slightly but is well-structured.

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 its simple 3-param schema with full coverage and no output schema, the description sufficiently covers what the tool does, when to use it, safety implications, and return behavior. It is complete for the tool's complexity and distinct from all siblings.

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 description adds little beyond schema definitions. The description does not elaborate on limit, since, or project_path beyond their names, so it meets the baseline but adds no extra semantic value.

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 action (compress) and resource (raw hook observations), specifies output types (tool_failure, tool_success, file_edit, generic), and differentiates from siblings like query_history and get_state. The purpose is unambiguous and actionable.

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 timing guidance ('Call before get_state or at session start') and rationale (reduces token count before loading memory). Lacks explicit when-not-to-use or alternatives, but the context is clear enough to select this tool appropriately.

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?

With no annotations provided, the description fully carries the burden of behavioral disclosure. It explains the exact retrieval logic: scoping to current git branch, falling back to default branch, then to legacy flat file, and how global memory is merged with precedence rules. It also implies a non-destructive read operation ('Returns'), and details the deduplication of global memory, which is transparent and actionable.

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 four sentences, each adding necessary detail: first defines what is returned, second explains scoping, third explains global memory handling, and fourth gives usage timing. It is front-loaded with the core purpose and avoids redundancy or fluff. Despite covering complex behavior, it remains tight and efficient.

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 must clarify what the caller receives. It explicitly lists content types (decisions, preferences, things to avoid, next steps), describes the structural sections (project state, Global Memory), and explains precedence and deduplication. It also covers edge cases like git vs non-git environments and global memory existence, making it complete for a state-fetching 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?

There is only one parameter, project_path, and its schema description already covers the default behavior ('Defaults to current working directory') with 100% schema description coverage. The tool description adds no additional information about the parameter, so the baseline score of 3 for high coverage is appropriate.

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

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

The description clearly states the tool returns 'the current project memory' and enumerates its contents (decisions, preferences, things to avoid, next steps). It also specifies scoping behavior to git branches, fallback order, and inclusion of global memory, making it distinct from siblings like get_project_state or working_memory_list. The verb 'Returns' with a concrete resource is specific and actionable.

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

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

The description gives an explicit usage instruction: 'Call this at the START of every session to restore context.' It also provides contextual guidance by explaining how global memory is written (via update_state with scope 'global'), which helps understand when this tool is appropriate. While it doesn't explicitly name alternatives, the call-to-action and scoping details offer clear guidance on when 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 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?

No annotations provided, so description carries full burden. Describes key behaviors: confidence decay over time, no deduplication, cross-session persistence. No contradictions with annotations (none provided).

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 essential. First sentence states purpose, second explains behavior, third gives usage context. No redundant or filler content.

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 5 parameters and no output schema, the description covers purpose, usage, behavior, and context (session, cross-session). No missing elements are critical for agent 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 100%, so baseline is 3. Description adds value by stating default confidence (0.7) and explaining the purpose of confidence decay. However, it does not add significantly to parameter descriptions that are already clear in 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?

Clearly states the tool persists a new lesson with an initial confidence score, using specific verb 'persist' and resource 'lesson'. Distinguishes from sibling tools by mentioning deduplication and referencing 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?

Explicitly tells when to use (record patterns, heuristics, observations) and when not to (call lesson_recall first if deduplication needed). Provides clear guidance on prerequisites and 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?

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?

Without annotations, the description carries full behavioral disclosure. It reveals that releasing a lock is a mutating operation, requires holder status, and returns a boolean indicating success. It does not detail error cases (e.g., invalid session), 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 concise sentences, front-loaded with the core action and resource, then a second sentence adds constraints and return value. Every word 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 the tool's simplicity (2 params, no output schema, no siblings), the description covers purpose, precondition, and outcome. It leaves no major gaps; the 'returns whether a lock was actually removed' implies graceful handling of non-existent locks.

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% (both parameters described in schema). The description adds minimal extra meaning beyond the schema; it restates that session_id defaults to current session. Baseline 3 is appropriate as the schema already explains the parameters adequately.

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 specifies the verb 'release', the resource 'path lock', and clarifies scope ('held by this session on the session bus'). It also distinguishes the action by stating 'Only the holder can release', leaving no ambiguity about what the tool does.

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 clearly says 'Only the holder can release', giving a precondition for usage. It also notes that the tool returns whether a lock was removed, which implies it is safe to call even without a lock. However, no explicit alternatives or when-not-to-use scenarios are 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?

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?

No annotations are provided, so the description carries full burden. It comprehensively discloses side effects: registers presence, triggers heartbeat, sweeps sessions after 10 minutes, releases locks, and returns peer sessions for territory coordination.

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?

Informative yet concise, with no superfluous words. First sentence captures the core purpose, followed by critical usage and behavior details in a natural flow.

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?

Despite no output schema, the description covers return value (list of live peer sessions) and all essential behavioral aspects. All three parameters are explained in context, making the tool 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% with descriptions for all parameters. The description adds value by explaining territory as an informal claim, session_id defaults, and project_path defaults, enhancing the schema definitions.

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 announces a session on the session bus, registers presence with optional territory, and doubles as a heartbeat. It differentiates from siblings like session_peers by explaining that this tool both announces and returns live peer 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?

Explicitly advises calling at session start and periodically during long work, and mentions the 10-minute heartbeat timeout. While it doesn't explicitly list when not to use, the context is clear enough for an agent.

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 present, the description carries the full transparency burden and does it well: it discloses consumption semantics ('delivered exactly once across calls'), ordering ('oldest first'), a non-consuming peek mode, and an important security property that payloads are untrusted. This goes well beyond basic descriptions.

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 compact, front-loaded with the core purpose, and every sentence adds value: read behavior, delivery semantics, security warning, and peek guidance. There is no filler 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?

For a relatively simple read tool with no output schema, the description covers purpose, behavior, ordering, consumption, non-consuming access, and security considerations. It is sufficiently complete for an agent to select and invoke the tool correctly in most scenarios.

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 input schema already provides complete descriptions for all three parameters (100% coverage). The description reinforces the peek behavior and broadcast scoping but does not add substantial new semantic detail beyond what the schema already states, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool reads events addressed to the current session, including direct and broadcast events, with specific delivery semantics (oldest first, exactly once). This distinguishes it from sibling tools like session_send or session_wait, which write or wait rather than read.

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 operational guidance, especially the peek:true option to read without consuming and the security warning about untrusted payloads. It does not explicitly name alternatives or state when not to use the tool, so it falls just short of full differentiation.

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 provided, so description must carry full burden. It discloses it lists sessions and locks, but does not clarify if read-only, define 'live', or mention permissions. Adequate but minimal.

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, each adding value: purpose and usage guidance. No unnecessary words, front-loaded with key 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 simple tool with one optional param and no output schema, description covers essential context: listing sessions and locks before parallel work. Could specify output format but not required for minimal completeness.

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% with parameter description already stating it filters by project. The description adds no further meaning about the parameter, meeting baseline but not exceeding.

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 live sessions and active path locks, using specific verbs and nouns. It distinguishes from siblings by focusing on listing rather than mutating (claim/release).

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 advises using before parallel work to see active and locked territories, providing clear context. Lacks explicit contraindications but implied by 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 the full burden. It discloses payload cap (16KB), delivery once per session, retention (24 hours), and default behavior for session_id. This is sufficient for understanding the tool's 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?

Three sentences, each serving a purpose: first defines the core action, second addresses constraints and alternatives, third details delivery guarantees. No unnecessary words.

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 no annotations and no output schema, the description covers delivery semantics, defaults, and limits. It could mention ordering guarantees, but overall it is fairly complete 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 coverage is 100%, so the description adds only marginal value beyond the schema: it explains broadcast behavior (omit to_session) and the payload size limit. The schema already describes each parameter adequately.

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 sends events to live sessions, distinguishing between direct (with to_session) and broadcast (omit to_session). It uses specific verbs and resources, and the sibling tools like session_announce suggest this is a distinct messaging function.

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 explains when to use direct vs broadcast, payload constraints, and suggests storing large context in project state. It does not explicitly list when not to use, but the context is clear.

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

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

With no annotations, the description carries full responsibility and does an excellent job: it discloses long-poll semantics, timeout behavior, the EGC_MESH_PUSH=0 opt-out and degradation, cursor advancement, and—critically—warns that payloads from other sessions are untrusted and must not be executed blindly.

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 information-dense but appropriately sized for a nontrivial long-polling tool. Every sentence carries useful operational or security context, though it is somewhat longer than strictly necessary and could have moved the env-var detail to a separate note without losing clarity.

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 complex asynchronous tool with no output schema or annotations, the description covers behavior, timeout, fallback mode, consumption semantics, and security. The main gap is that it does not specify what is returned on timeout or the exact shape of the result, though the reference to session_events partially compensates.

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 three parameters. The description does not add parameter-specific details beyond what the schema provides, so it sits at the baseline score.

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 'Long-poll the session bus' and precisely explains the behavior: immediate return if events are pending, otherwise wait until an event or timeout. It distinguishes itself from the sibling session_events by contrasting the long-poll behavior and noting events are consumed exactly like session_events.

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 makes it clear when this tool applies (waiting for events) and implicitly contrasts with session_events by describing the fallback and consumption semantics. However, it does not explicitly state 'use session_events instead when you want a one-shot read' or list other exclusions, so guidance is strong 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?

There are no annotations, so the description carries the transparency burden. It discloses a useful behavioral trait: 'write-lock arbitration to prevent concurrent conflicts'. However, it does not explain write semantics such as whether the same context overwrites an existing decision, what errors may occur, or what is returned on success.

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 three concise sentences that front-load the primary action and add relevant details about concurrency and queryability. Every sentence contributes useful 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 simple two-parameter tool with full schema coverage and no output schema, the description is sufficiently complete. It explains persistence, concurrency handling, and how stored decisions can be retrieved, which gives the agent enough context to select and invoke 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?

Schema description coverage is 100%, so the baseline is 3. The description essentially restates the schema ('short context label' and 'decision text') without adding new semantic details beyond what the schema already documents.

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 and resource: 'Persist a single decision to the SQLite store'. It also distinguishes the tool from siblings by noting that stored decisions are 'queryable via query_history and surfaced in get_state', which clarifies its unique role.

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

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

The description gives clear context for when to use the tool: to persist a single decision, and it instructs the user to 'Provide a short context label and the decision text'. It does not explicitly state exclusions or alternatives, but the mention of query_history and get_state helps differentiate it from related 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 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 provided, the description carries the transparency burden. It discloses that it writes to the current git branch's state file, merges with existing state, and does not erase previous memory. However, it omits behavioral nuances like the force-recovery mode, global scope implications, or project_path fallback risks, which are only visible in 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 three sentences long, front-loaded with the primary action, and every sentence contributes distinct value. No redundant or filler content.

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 has 8 parameters and no output schema, but the description plus schema together cover behavior and parameter semantics well. The missing return value information is less critical for a write-focused tool, although a brief note on what the tool returns would have made it 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%, so each parameter already has meaningful definitions. The description adds no parameter-specific details beyond the schema, which is acceptable but does not elevate the score beyond 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 updates project memory with session decisions, using the specific verb 'updates' and the resource 'project memory/state file.' It further distinguishes itself by prescribing end-of-session use, separating it from sibling tools like store_decision or 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?

It gives explicit timing guidance ('Call this at the END of every session'), which is strong contextual instruction. However, it does not explicitly name alternatives or state when not to use it, leaving some ambiguity relative to sibling tools like store_decision.

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 fully discloses behavioral traits: it does not modify the entry, does not extend TTL, returns null if key is missing or expired, and does not throw. This is comprehensive for a read 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 delivering essential information without redundancy. The most critical action and purpose are front-loaded, and every sentence adds 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?

For a simple retrieval tool with two parameters and no output schema, the description is very complete: explains return value behavior, idempotency, and suggests an alternative for listing. No gaps evident.

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 does not add significant extra meaning beyond what the schema already provides for the two parameters. The phrase 'by key' is redundant with the key 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 states it retrieves a transient entry by key for the current project. It distinguishes itself from the sibling tool working_memory_list by specifying when to use that alternative (unknown key or audit).

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 guidance for when to use this tool versus working_memory_list (unknown key or audit). However, it does not contrast with working_memory_set for modification scenarios, though context is sufficient for the typical use case.

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?

No annotations provided, so description carries full burden. It discloses transient nature, automatic expiration, overwrite behavior, and scoping to project. Could mention what happens on missing project_path or other error conditions, but defaults are covered in schema. Overall transparent for a non-destructive write 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?

Four sentences, each earning its place. Front-loaded with core purpose, then caveats and guidance. 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 tool with 4 parameters and no output schema, the description covers purpose, usage, and parameter behavior well. It does not describe the return value, but as a write operation this is acceptable. Could add note about successful acknowledgment, but overall complete for its 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 coverage is 100% (baseline 3). Description adds value by explaining the purpose of each parameter in context: key as unique name, value as any string including JSON, ttl_seconds with default, project_path with default to current directory. This contextual enrichment justifies a score above 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?

Clearly states it stores a transient key-value entry scoped to the current project, with explicit mention of expiration, overwriting behavior, and use cases. Distinguishes from sibling tool update_state by noting it avoids polluting long-term 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?

Provides explicit guidance on when to use (debug flags, temporary task context) and when not to use (data that must survive session restart, recommending update_state instead). Also notes that it overwrites existing entries without error.

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