GitMem

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

No annotations are provided, so the description carries full burden. It mentions 'persist' implying state change, but does not disclose side effects, idempotency, required permissions, or failure behavior. More detail needed for full transparency.

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

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

Three sentences, front-loaded with purpose, followed by workflow and outcome. Every sentence adds essential information without 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 has 2 parameters (1 required) and no output schema, the description adequately explains the input context and processing. It lacks details on return values or error handling, but is sufficient for a tool of this 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% with descriptions for all properties. The description adds value by explaining the purpose of the observations (analysis, scar candidate identification), which goes beyond the schema's structural 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 it captures observations from sub-agents and teammates, with specific verbs: capture, persist, analyze, identify. It distinguishes from siblings like confirm_scars or reflect_scars by focusing on the initial capture and analysis step.

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 context: it is called after the lead agent parses findings from sub-agent responses. However, it does not explicitly exclude alternatives or mention when not to use it, though the workflow implication 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 must fully disclose behavioral traits. It only mentions default output format and the alternative 'format=json'. It does not state whether the tool is read-only, has side effects, requires authentication, or any rate limits. This is insufficient for behavioral transparency.

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

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

Two sentences, no wasted words. The purpose is front-loaded. Each sentence adds distinct information: first defines the tool, second clarifies output defaults and options. Highly concise and 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 5 parameters, no output schema, and no annotations, the description is quite minimal. It covers output format but does not explain the 'lens' parameter meanings, the 'days' range, or the 'agent' filter. It provides the bare essentials but lacks completeness for a tool with multiple 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%, so baseline is 3. The description adds minimal extra value by noting that the default output is 'formatted markdown' and that format=json gives 'raw data', but the schema already describes the enum options. No additional semantics for other parameters.

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

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

The phrase 'Session analytics and insights engine' clearly communicates the tool's purpose: analyzing sessions to produce insights. It mentions default markdown output. However, it does not explicitly differentiate from sibling tools like 'search' or 'reflect_scars', so it loses a point.

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

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

No guidance is provided on when to use this tool versus its siblings. The only usage instruction is about the format parameter, which is more about parameter usage than tool selection. This leaves the agent without clarity on context of use.

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

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

With no annotations, description fully discloses soft-delete behavior (set active flag, timestamp, exclusion from search). Minor omission: no mention of reinstatement possibility, but sufficient for common use.

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 action and effect, no wasted 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?

Adequately covers purpose, mechanism, and impact on other tools. No output schema needed for this simple operation.

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 description adds value with examples (UUID prefix, reason example) beyond the schema's basic descriptions.

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 archives a learning by setting is_active=false and recording timestamp, and explains impact on recall/search. Distinguishes from sibling tools like create_learning or 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?

Tells when to use (to archive a learning) and consequences (excluded from recall/search, preserved for audit). Lacks explicit when-not or alternative tools, but 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?

No annotations are provided, so the description carries the full burden. It discloses the auto-archiving behavior (a destructive action), but it does not clarify whether the triage grouping is read-only or also modifies thread statuses. The term 'resolve' is ambiguous, leaving some behavioral traits unclear.

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 minimal waste. It is front-loaded with the main action, and each sentence adds value. Slightly more structure could improve clarity, but overall it is 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?

The tool has no output schema, so the description should explain what is returned. It mentions grouping with vitality scores but does not specify the output format, error conditions, or prerequisites. This is a significant gap for effective use.

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. The description only repeats the auto_archive behavior, adding no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses the specific verb 'triage' and resource 'open threads', clearly stating it groups threads by lifecycle health and offers auto-archive. It distinguishes from siblings like list_threads (just listing) and resolve_thread (individual resolution) by focusing on bulk lifecycle management.

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

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

The description implies usage for cleaning up stale threads and mentions auto-archiving after 30+ days, but it does not explicitly state when to avoid this tool or mention alternatives. Guidance is present but lacks exclusions or comparison to sibling 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 provided, the description carries full burden. It discloses the required sequence, the need to address all scars, and the behavioral expectations for each decision (e.g., past-tense evidence for APPLYING, risk acknowledgment for REFUTED). It lacks details on side effects like database updates or return values, but covers key behaviors sufficiently for a confirmation action.

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: the first states the function, the second specifies the required context, and the third explains decision options. No wasted words, highly front-loaded, and easy to parse.

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 complexity (1 parameter with nested subfields) and lack of output schema, the description covers the critical usage instructions (required after recall, address all scars), but omits what the tool returns or whether it mutates state. It is mostly complete but could benefit from mentioning the response format.

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 tool description adds some context (e.g., the three decision meanings) that reinforces schema descriptions, but does not provide new parameter-level details beyond what the schema already states (e.g., 'Minimum 50 characters'). The description is helpful but not essential beyond the schema.

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

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

The description uses specific verbs ('Confirm', 'surfaced scars') and clearly distinguishes the tool from siblings like recall and reflect_scars by stating it is required after recall before consequential actions. The three decision types are explained explicitly, leaving no ambiguity about the tool's 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 explicitly states when to use the tool ('REQUIRED after recall() before consequential actions') and that 'Each recalled scar must be addressed.' It provides context for each decision option but does not mention when not to use it or compare directly to alternatives like reflect_scars, which limits the score to 4.

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 fully carries the burden. It discloses local saving, opt-in anonymous sending, and session limit—covering the key behaviors for a feedback submission tool.

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

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

Three sentences with no redundancy. Purpose is front-loaded, and every sentence adds distinct information (purpose, storage, limit). Excellent conciseness.

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 feedback submisssion tool with no output schema, the description covers purpose, storage, anonymization, and rate limit. No missing aspects apparent.

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 parameters are already documented. The description adds no additional parameter semantics (e.g., no hints about how to fill fields). 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?

Description starts with 'Submit feedback about gitmem' and enumerates types (feature requests, bug reports, etc.). Clearly identifies the verb and resource, and distinguishes from siblings as the dedicated feedback tool.

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

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

Provides context on storage ('saved locally to .gitmem/feedback/'), opt-in anonymization, and a rate limit ('10/session limit'). Does not explicitly state when to use vs alternatives, but no similar siblings exist, so the guidance is adequate.

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 full burden for behavioral disclosure. It only says 'log', implying a write operation, but does not mention idempotency, side effects, permissions, or rate limits.

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

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

The description is a single, front-loaded sentence with no filler. It could be slightly more structured (e.g., listing typical use) but is 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?

Despite 9 parameters and no output schema or annotations, the description is extremely brief. It does not explain return values, error cases, or behavioral expectations, leaving significant gaps for an agent.

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 parameters. The description adds the 'architectural/operational' context but does not elaborate on parameter meaning or constraints 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?

The description uses a specific verb ('Log') and resource ('decision') with context ('architectural/operational', 'to institutional memory'), clearly distinguishing it from siblings like 'absorb_observations' or 'analyze'.

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

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

No guidance on when to use this tool versus alternatives (e.g., 'log', 'analyze'). It does not state prerequisites, exclusions, or preferred scenarios.

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 disclose behavioral traits such as idempotency, permission requirements, or effects of duplicates. For a creation tool, this is a significant gap.

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 at ~50 words and front-loaded with the core purpose. It could be slightly more structured but is efficient overall.

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 13 parameters and no output schema, the description omits important context such as the relationship between learning_type and other fields (e.g., severity for scars). It does not explain required vs optional parameters fully.

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%, but the description adds value by explaining the tone for 'title' and 'description' (factual insight, no self-criticism) and grouping learning types. This goes beyond the schema's field descriptions.

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 'Create scar, win, or pattern entry in institutional memory,' specifying the verb (create) and resource (learning entry). It differentiates from sibling tools like 'create_decision' by explicitly naming the learning types.

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 guidance on framing (lead with factual discovery, not what went wrong) and gives good/bad examples. However, it does not explicitly state when not to use this tool or compare it to alternatives like 'record_scar_usage'.

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?

Discloses semantic dedup with cosine similarity threshold and instructs to check 'deduplicated' field in response. No annotations provided, so description carries full burden; missing some side effects but sufficient.

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 wasted words, front-loaded with purpose. 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?

No output schema, but description mentions checking 'deduplicated' field. Simple two-parameter tool; covers creation and dedup. Could mention async behavior or limits, but adequate.

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 an example for linear_issue and slightly rephrases text parameter, but does not significantly enrich beyond 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 creates an open thread to track unresolved work across sessions, distinguishing it from sibling tools like resolve_thread and cleanup_threads.

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 context for when to use the tool (track unresolved work across sessions) and describes dedup behavior, but does not explicitly state when not to use or compare with alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool increments a dismiss count and that suggestions dismissed 3+ times are permanently suppressed. This adds meaningful context beyond a simple 'dismiss' action, though it doesn't detail all side effects or authorization needs.

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 consists of two succinct sentences with no wasted words. The first sentence states the purpose, and the second explains a key behavioral detail. It is front-loaded and every sentence earns its place.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers the core behavior but lacks information about the return value or what happens after dismissal (e.g., does the suggestion disappear from the list?). The description is adequate but could be more complete by explaining the state change or providing more context about the suppression mechanism.

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 the parameter's meaning and format. The description adds a concrete example ('ts-a1b2c3d4') and mentions it comes from a 'suggested_threads list', which provides helpful context but does not significantly augment the schema's description. Baseline of 3 is appropriate.

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

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

The description clearly states the action ('Dismiss') and the resource ('a suggested thread'), and it distinguishes the tool from siblings like 'promote_suggestion' by implying it is the opposite action. The mention of incrementing dismiss count and permanent suppression after 3 times adds specificity.

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 does not explicitly state when to use this tool versus alternatives. While the purpose is clear, there is no guidance on when not to use it or which sibling tools (e.g., 'promote_suggestion', 'resolve_thread') might be more appropriate in different contexts. Usage is implied rather than 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?

No annotations are provided, so the description must fully disclose behavioral traits. It states the action (force reload) but does not explain side effects, permission requirements, or what 'out of sync' means operationally. For a cache flush, this lack of detail is a significant gap.

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—one sentence—and front-loaded with the tool name and purpose. Every word is functional, but the brevity sacrifices necessary details.

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 one-parameter tool with no output schema and no annotations, the description should still explain what 'out of sync' means, what happens to the cache, and whether the operation is reversible. It lacks this context, so completeness is low.

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% for the single parameter 'project', and the schema description is clear. The tool description adds no additional meaning beyond the schema, meeting the baseline of 3.

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 explicitly states 'Force reload cache from Supabase', which is a specific verb and resource. It clearly distinguishes from sibling tools like gitmem-cache-health and gitmem-cache-status by focusing on flushing the cache.

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 includes 'use when out of sync', providing a clear context for when to use the tool. However, it does not specify when not to use it, nor does it mention alternatives among sibling 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?

No annotations are present, so the description must fully disclose behavior. It only says 'compare' and 'detect', but does not reveal whether the tool modifies anything, requires specific permissions, has rate limits, or what the response looks like. Essential behavioral details are missing.

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

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

The description is a single line with front-loaded intent, making it easy to parse quickly. However, it redundantly includes the tool name, wasting a few characters. Still, it is concise overall.

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?

Without an output schema, the description should clarify what the tool returns (e.g., a boolean, a diff report). It does not address default behavior when the optional 'project' is omitted, nor does it explain the detection mechanism. The description is incomplete for a health-check 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 parameter 'project' is already explained there. The tool description adds no additional meaning or context about how the parameter affects the comparison. Baseline score 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 verb 'compare' and the resources 'local cache against remote Supabase', with the explicit goal 'detect out-of-sync'. It distinguishes itself from sibling tools like gitmem-cache-flush and gitmem-cache-status by specifying a diagnostic 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?

No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, typical scenarios (e.g., before syncing), or when not to use it. The description lacks contextual usage advice.

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

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

The description lists the output fields (scar count, age, staleness) which gives some behavioral insight into what the tool returns. However, with no annotations, it should explicitly state that the tool is read-only and non-destructive, which is implied but not confirmed. No mention of permissions, rate limits, or side effects.

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

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

The description is a single, efficient sentence that front-loads the tool's purpose and key outputs. It uses parentheses to list details without extra words, making it concise yet informative. Slight improvement could be adding usage guidance, but as is, it 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 the tool's simplicity (one optional parameter, no output schema), the description adequately conveys the tool's function and output. It names three specific output fields (scar count, age, staleness), which is sufficient for a status tool. However, it does not explain domain-specific terms like 'scar', which might be unclear without domain knowledge.

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 the only parameter (project) with a clear description, so the description adds no additional meaning. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: showing local search cache status with specific metrics (scar count, age, staleness). The verb 'Show' combined with the resource 'local search cache status' distinguishes it from siblings like 'gitmem-cache-flush' and 'gitmem-cache-health'.

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

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

No guidance is provided on when to use this tool instead of alternatives such as 'gitmem-cache-health' or 'gitmem-cache-flush'. The description does not mention prerequisite conditions, context, or when to avoid using 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 provided; description does not disclose safety, side effects, or read-only nature. Brief statement lacks behavioral context.

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?

Single sentence, front-loaded, no wasted words. Efficient and to the 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 zero-parameter help tool, description adequately conveys purpose. Some might appreciate more detail (e.g., usage format), but it suffices.

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?

No parameters exist; schema coverage is 100%. Baseline score of 4 applies as description adds no param info but none is needed.

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 clearly states verb 'show' and resource 'available commands' with additional detail 'ASCII art header', distinguishing it from functional siblings like gitmem-cache-*.

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

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

No guidance on when to use this tool versus alternatives. It simply describes function without context or exclusions.

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

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

No annotations provided. Description implies a read-only operation but does not explicitly state safety, idempotency, or any side effects. This is a minimal disclosure.

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 plus a list of lenses. Every sentence is informative and front-loaded. No wasted 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?

Covers the main use cases and output type (triples). Could mention depth/limit defaults, but those are in the schema. Adequate for a query tool without 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?

All 6 parameters are described in the schema, and the description adds context by linking lenses to example questions and providing example node values. This goes beyond 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?

Description clearly states it traverses a knowledge graph, provides example queries, and lists four traversal lenses. This distinguishes it from sibling tools like search or 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?

Example questions imply when to use the tool (e.g., 'show me everything connected'), but no explicit guidance on when not to use it or comparison with alternatives like analyze or search.

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; description implies read-only health check but does not explicitly confirm no side effects or disclose any behavioral traits beyond reporting rates.

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

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

Two sentences with no waste. Purpose is stated first, followed by use case. 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 health check with one optional parameter, the description adequately explains purpose and usage. It does not describe return format, but no output schema is expected.

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

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

Schema coverage is 100% and description adds no additional meaning beyond the schema's parameter description of 'failure_limit'. 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?

Description clearly states the tool shows write health for the current session, listing specific tracked operations. It distinguishes itself from sibling tools like 'gitmem-cache-health' by focusing on session-level write health.

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 says 'Use this to diagnose silent failures', providing clear context for when to use. However, it does not explicitly state when not to use or compare with alternatives.

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

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

With no annotations, the description carries full burden. It discloses incremental indexing behavior but lacks details on side effects (e.g., overwrite, resource usage, error states). The 'clear' and 'force' parameters are only in schema, not described here.

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 efficiently convey core function, incremental support, and cross-reference to sibling tool. 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?

Description explains the process and incremental indexing but omits return value, error handling, and whether execution is synchronous or asynchronous. While schema covers parameters, the overall context for an agent is adequate but not thorough.

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 does not add extra meaning to parameters beyond what the schema provides, so it meets the baseline without 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 indexes markdown files for semantic search, specifying the verb 'scan, chunk, embed, store' and the resource 'directory of markdown files'. It distinguishes from sibling tool 'search_docs' by mentioning it as the query counterpart.

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 incremental indexing and directs to 'search_docs' for queries, providing context on when to use the tool. However, it does not explicitly state when not to use it or list alternatives for other file types.

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 bears full responsibility for disclosing behavioral traits. It does not state that this is a read-only operation, nor does it mention safety, permissions, or rate limits. The description only says 'list' and 'shows', which implies read-only, but is not explicit. For a tool with no annotations, this is insufficient.

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

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

The description is two sentences long, with no wasted words. The first sentence states the core purpose, and the second adds context about session carry-over and points to a sibling tool. It is front-loaded and efficient, though it could be slightly improved by noting read-only nature.

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 no output schema, so the description should compensate by explaining what the response looks like, but it does not. It also does not clarify how the parameters interact (e.g., combining status and include_resolved), how 'recent sessions' is defined, or whether results are paginated. For a list tool with three parameters and no output schema, the description is undercomplete.

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 parameters are already fully documented in the input schema. The description adds no extra meaning beyond what the schema provides for the three parameters (status, project, include_resolved). Baseline 3 is appropriate given high schema coverage.

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

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

The description 'List open threads across recent sessions' uses a specific verb and resource, and clarifies the scope ('across recent sessions') and nature ('unresolved work items that carry over between sessions'). This clearly distinguishes it from sibling tools like resolve_thread, create_thread, and search.

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 names a sibling alternative ('Use resolve_thread to mark threads as done'), providing when-not-to-use guidance. It implicitly suggests this is for viewing open tasks, but lacks comprehensive context about when to prefer this over other listing tools like search or recall.

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?

Describes output ordering (chronological by creation date) and content types. No annotations exist, so description adequately covers behavior. Missing details on pagination or side effects, but reads are low risk.

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?

Single sentence with parenthetical simile; no wasted words. Front-loaded with key 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?

Complete enough for a simple list tool with well-documented schema parameters. Could note default limit or pagination behavior, but not required.

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 covers 100% of parameters with descriptions. Description does not add any additional meaning beyond what schema already 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?

Clear verb-resource pair ('list recent learnings') with helpful analogy ('like git log') and specific types shown. Distinguishes from siblings like search or 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?

No explicit when-to-use or when-not-to-use guidance. Could mention that for advanced filtering or full-text search, use 'search' instead.

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 is the sole source for behavioral insights. It explains the three output formats with token budgets but omits any details about side effects, permissions, or whether the operation is read-only. The behavior is partially transparent but not fully disclosed.

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

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

The description is extremely concise with two sentences that front-load the primary purpose and then detail the formatting. Every sentence provides unique value without repetition or 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?

Despite having 5 parameters and no output schema, the description fails to explain the return value or payload structure. The agent is left guessing what the output looks like (e.g., a string, JSON, markdown). This lack of completeness is a significant gap for a tool generating payloads.

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 meaningful context beyond the schema: it clarifies 'plan' as 'What the team is about to do', elaborates on format options with token budgets, notes that 'agent_role' is reserved for Phase 3, and provides default token budgets for max_tokens. This extra detail justifies a score of 4.

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

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

The description clearly states the tool's purpose: generating portable memory payloads for sub-agent injection. It specifies the verb 'Generate' and the resource 'portable memory payload', and distinguishes it from sibling tools by focusing on injection payloads, which no other 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 implies usage for sub-agent injection but does not explicitly state when to use this tool versus alternatives like 'recall' or 'archive_learning'. No when-not-to-use guidance or alternative references are provided, leaving the agent to infer 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 that the tool creates a real thread (mutation), but does not mention what happens to the original suggestion (e.g., is it removed?), any authorization needs, or error conditions. Some behavioral aspects are left unclear.

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 wasted words, front-loaded with the key action. Highly concise.

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

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

No output schema is present, and the description does not explain what the tool returns or fails. It also omits prerequisites like an active session. While it covers the core behavior, completeness is moderate given the complexity of creating a thread from a suggestion.

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 parameter descriptions in the schema are already clear. The description's mention of 'suggestion_id from session_start's suggested_threads list' adds little beyond what the schema provides. The baseline of 3 is appropriate.

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

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

The description clearly states the action ('promote a suggested thread to an open thread') and specifies the resource (suggestion_id from session_start's suggested_threads list). It distinguishes from sibling tools like create_thread (which creates from scratch) and dismiss_suggestion (which dismisses).

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 context for when to use (when you have a suggestion_id from the suggested_threads list) but does not explicitly state when not to use or contrast with alternatives like create_thread or dismiss_suggestion. The agent could benefit from clearer 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?

With no annotations, the description must fully convey behavior. It implies a read operation ('check') but also mentions 'integrates variant assignment', which could suggest a write side effect. It does not clarify read-only nature, permissions, or error states. The lack of transparency about potential mutations is a significant gap.

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 at three sentences, front-loaded with the primary purpose. Every sentence adds value without redundancy. Ideal length for an agent.

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 5 parameters and no output schema, the description omits details about output format, pagination, error behavior, and the exact nature of 'variant assignment'. It leaves significant gaps for an agent to infer, making it incomplete for confident usage.

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 context for issue_id ('variant assignment') which reinforces the schema. However, it does not provide additional meaning beyond the schema for plan, match_count, or similarity_threshold. Value added is marginal.

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 checks institutional memory for scars before action, returning matching scars and lessons. It distinguishes itself from siblings like 'search' and 'reflect_scars' by its specific purpose of pre-action memory retrieval. However, the verb 'check' is somewhat abstract and the domain term 'scars' may not be universally understood.

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 a usage context ('before taking action') and mentions variant assignment when issue_id is provided. However, it does not explicitly state when not to use this tool or point to alternative tools like 'reflect_scars' or 'search' for different use cases. The guidance is implied but not comprehensive.

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 provided, the description carries the full burden of behavioral disclosure. It fails to mention that this tool creates a record, any side effects, or required permissions. The description is too minimal to inform the agent about the tool's behavior beyond its name.

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 (5 words) and front-loaded. It wastes no words, but it may be too terse for a tool with 11 parameters. Every word earns its place, but additional context would be beneficial.

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 has 11 parameters (4 required), no output schema, and no annotations, the description is insufficiently complete. It does not explain return values, interpretation of 'effectiveness measurement', or why certain parameters (e.g., 'variant_id') are needed. The agent would lack context for correct invocation.

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

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

The input schema has 100% coverage describing all parameters. The description does not add any additional meaning beyond the schema; it simply repeats the tool's purpose. Baseline 3 applies.

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

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

The description uses the verb 'Track' and specifies the resource 'scar application' with a clear goal 'for effectiveness measurement'. However, it could be more specific about the action (e.g., 'record' vs 'track'). It distinguishes from siblings like 'confirm_scars' or 'reflect_scars' implicitly.

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

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

The description implies its use for recording scar application events, but it provides no explicit context about when to use this tool versus alternatives (e.g., 'confirm_scars', 'reflect_scars'). No when-not-to-use guidance.

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

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

No annotations, so full burden on description. Discloses character length minimums and that session_close uses reflections to determine execution_successful. Clearly describes input constraints and output consequences.

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?

Concise, front-loaded with purpose. Every sentence adds critical information (timing, outcome behavior, impact on session close). 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?

Fully explains the tool's role in the session flow, references related sibling (confirm_scars), and covers input constraints. No output schema, but describes usage outcome (sets execution_successful). Comprehensive for a reflection 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 coverage 100%, but description adds value: evidence length minima (15/30 chars), explanation of outcome enum meanings, and that reflections are per surfaced scar. Goes beyond 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?

Clear verb+resource: 'scar reflection'. States it's the closing counterpart to confirm_scars, mirroring a protocol. Distinguishes its role in the session lifecycle.

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 instructs 'Call BEFORE session_close' and details behavior for OBEYED vs REFUTED. Mentions how session close uses reflections. Lacks explicit when-not-to-use but provides strong 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 discloses that the tool modifies session state and a JSON file, indicating mutation. However, it does not specify behavior for edge cases like already-resolved threads or nonexistent threads, nor prerequisites or permissions.

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

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

The description is two sentences long, front-loads the main action, and contains no superfluous words or redundancy. Every sentence contributes essential 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?

Given the tool's simplicity (3 optional parameters, no output schema), the description covers the core purpose, identification methods, and side effects. It lacks information on conflict resolution when both thread_id and text_match are provided, and does not describe return values or error states, but is adequate for basic use.

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%, but the description adds value by explaining the intended use of thread_id ('for exact match') and text_match ('for fuzzy matching, fallback if no thread_id'), which goes beyond the schema descriptions. The resolution_note parameter is already well-described in the schema.

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

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

The description clearly states the tool's action ('Mark an open thread as resolved') and distinguishes it from sibling tools like create_thread and list_threads. It specifies two methods for identifying the thread (by ID or fuzzy match).

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 explicit guidance on when to use thread_id versus text_match, but does not include explicit when-not-to-use or alternative tools. The context is clear enough for basic usage.

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 states 'without side effects', which is good, but lacks details on authentication, rate limits, or return format. For a search tool, this is adequate but not comprehensive.

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

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

The description is two sentences, front-loaded with the main purpose. Every word earns its place—no fluff, clear and to the 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?

Given the absence of output schema and 5 parameters, the description is fairly complete. It defines the tool's purpose, contrast with recall, and confirms no side effects. Could mention result format or pagination, but not a major 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. The description does not add new meaning beyond the schema; it only restates that it returns matching items without side effects. No extra parameter details are provided.

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 'Search institutional memory by query' and distinguishes from recall, which is action-oriented. The verb 'search' and resource 'institutional memory' are specific.

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 contrasts with recall (exploration vs action) and notes no side effects, helping agents decide when to use it. However, it doesn't list when not to use or other alternatives.

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

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

With no annotations provided, the description discloses two search mechanisms, the return format (chunks with file paths), and a prerequisite. It does not mention rate limits or authorization but covers the essential behavioral aspects for a search tool.

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

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

The description is two focused sentences: first describes core functionality with tier differentiation, second mentions return type and prerequisite. No extraneous information, every word serves a purpose.

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

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

The description covers the tier-based search methods, return format, and prerequisite. It does not elaborate on the differences between semantic and BM25 search beyond tier association, but overall it provides sufficient context for the tool's use.

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

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

Schema coverage is 100%, and the schema descriptions are detailed. The description adds examples for 'query' and context for 'project' and 'category', but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool searches indexed documentation using two methods (semantic similarity and BM25 keyword search), and mentions it returns relevant chunks with file paths. It distinguishes from sibling tools like 'index_docs' and 'search'.

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 prerequisite ('Index docs first with index_docs') and differentiates search methods by tier. However, it does not explicitly state when not to use this tool or compare it with alternative search tools among siblings.

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 burden. It discloses that the tool persists with compliance validation, auto-generates task_completion, and instructs to output the display field verbatim. It does not detail side effects or authentication needs, but the key behavioral aspects are 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?

The description is concise (four sentences) and front-loaded with purpose. Every sentence provides essential information without redundancy or 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?

Given the tool's complexity (6 parameters, no output schema), the description is reasonably complete: it explains modes, inline override, auto-generation of task_completion, and display instructions. It could be improved by specifying the output format, but it covers the most critical context for an agent.

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 value by explaining the two operational modes and the relationship between file payload and inline parameters, which goes beyond the schema descriptions.

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 persists a session with compliance validation, and it distinguishes from sibling session tools (session_start, session_refresh) by focusing on closure. The two modes are explicitly described, making the purpose specific and unambiguous.

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

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

The description provides explicit usage guidance for two modes (file-based vs inline), including the fallback rule (inline overrides file). However, it does not specify when NOT to use this tool or mention alternative tools for similar tasks.

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 full burden for behavioral disclosure. It states the tool does not create a new session, and provides crucial output handling instructions: 'Output the display field verbatim as your response — tool results are collapsed in the CLI.' This is helpful transparency. 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?

The description is concise: two clear sentences plus a display instruction. Purpose and usage are front-loaded. Every sentence adds value—no redundancy, no filler. Highly efficient communication.

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 (1 optional parameter, no output schema, no annotations), the description is largely complete: it covers purpose, usage, and output behavior. It could mention that an active session must exist, but this is implied. Overall, adequate for correct invocation.

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

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

Schema description coverage is 100% (the single parameter 'project' has a complete description in the schema). The tool description does not add extra parameter context, but the schema already provides sufficient semantics. 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's purpose: 'Re-surface institutional context (threads, decisions) for the current active session without creating a new session.' It uses a specific verb ('Re-surface') and identifiable resource ('institutional context'), and explicitly distinguishes it from creating a new session, differentiating it from sibling tools like session_start.

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 explicit usage scenarios: 'Use mid-session when you need to remember where you left off, after context compaction, or after a long gap.' This gives clear context for when to use the tool. It does not explicitly mention when not to use it or list alternatives, but the guidance is sufficient for an agent to decide.

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

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

Despite no annotations, the description discloses key behaviors: session initialization, agent detection, loading of context, and the note about scars surfacing via recall(). It also explicitly instructs on handling the 'display' field in output. However, it does not mention side effects of the 'force' parameter on existing sessions.

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 very concise with two short paragraphs. The first paragraph states the core functionality, and the second provides crucial output handling instructions. Every sentence adds value, and there is 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?

The description covers initialization and output display instructions but lacks details on return structure beyond the display field, error conditions, or prerequisites. Given the complexity (7 params, no output schema), it is adequate but not complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema; it mentions loading context but does not map to specific parameters. The parameter descriptions in the schema are already clear.

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 initializes a session, detects the agent, and loads institutional context (last session, recent decisions, open threads). It uses specific verbs and resources, and the purpose is distinct from siblings like session_refresh or session_close.

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

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

The description implies this tool is used to start a session but provides no explicit guidance on when to use it versus alternatives like session_refresh. There is no mention of when-not to use or what prerequisites exist.

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