marm-memory

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

Without annotations, the description carries the full burden. It discloses that the tool returns a 'graph lookup response, or a graph-unavailable error if the graph backend is disabled or failed to start.' It also explains the behavior of kind=auto based on query type. However, it does not detail the structure of the response or mention any authentication or rate limits, which would improve transparency.

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

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

The description is well-structured with an emoji, bolded key terms, a concise overview, and a bulleted parameter list. Every sentence adds value, and the length is appropriate for the complexity of the tool. It is front-loaded with the most important 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?

The description effectively explains the tool's functionality and parameters, and it mentions the return type. Given the complexity (6 parameters, no output schema, no annotations, and many sibling tools), it is largely complete. However, it could briefly mention what a 'graph lookup response' contains or provide an example to further aid understanding.

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

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

The description adds significant meaning beyond the input schema. For each parameter, it explains its purpose and behavior: e.g., query can be 'symbol name, natural-language phrase, code/text pattern, or a qualified_name'; kind options are detailed; regex is for text search; project can be omitted for auto-resolve; file_pattern is a glob. With 0% schema coverage, the description fully compensates.

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: 'Find code: symbols/definitions, text patterns, or a symbol's source.' It distinguishes itself by saying 'Use INSTEAD OF grep/glob,' and explains the different modes (auto, symbol, text, snippet), making it easy to understand what the tool does and how it differs from siblings.

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 this tool and its alternatives: 'Use INSTEAD OF grep/glob.' It also explains the behavior of each kind value, e.g., 'kind=auto picks: a qualified_name reads source; otherwise it searches the graph by name/keyword. Set kind=text to grep code, kind=snippet to read a symbol's source, kind=symbol to force graph search.' This gives clear context for selecting the appropriate mode.

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. It discloses key behaviors: apply marks source memories as compacted, discard leaves source memories untouched, and candidates include a 'ready-to-use prompt.' This is meaningful contextual information beyond the schema, though it does not mention all side effects or error conditions.

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 and well-structured: a one-sentence purpose, a workflow arrow, and a bulleted action list. Every sentence provides useful 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?

The tool has complexity (six actions, multiple parameters) and no output schema, so the description should clarify return values and expected behavior for each action. The workflow is explained, but the response/return format for actions like status or candidates is not described, leaving the user guessing about what data comes back. This is a significant omission for a stateful 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?

Schema description coverage is 0%, so the description must compensate. It explains action values (status, candidates, stage, etc.) and the candidate_id parameter in context. However, the summaries parameter is never explicitly described, leaving ambiguity about its structure and usage (likely for batch apply, but not stated). This is a noticeable gap.

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

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

The opening sentence states the tool's exact purpose: 'Compact related memories into a single summary to reduce context bloat.' The verb (compact) and resource (memories) are clear, and the workflow action list distinguishes it from sibling tools like marm_log or marm_smart_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?

The description provides a clear workflow (status/candidates → stage → review → apply/discard) and tells the user to run status first. It gives context for each action but does not explicitly name alternative tools or state when not to use this 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?

Describes extraction of entities/relationships, code linking, row-capping for search_all, and return fields. Lacks details on overwrite/durability behavior, but overall informative for a build tool with no annotations.

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

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

Concise and well-structured with bullet-like parameter list and clear action verb. The emoji is non-essential but not harmful. Could be slightly tighter by removing redundant phrasing.

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, manually lists return values. Covers scoping options, linking behavior, and prerequisite ordering. Missing error conditions and permissions, but adequate for a build 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 is 0%, but description compensates fully by explaining the purpose and interaction of all four parameters (session_name, search_all, project, run_id) beyond their titles.

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 action (extract entities/relationships) and the resource (concept graph). Distinguishes from sibling marm_concept_recall by specifying the ordering dependency.

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 explains scoping via session_name/project or search_all=True, and advises calling this before marm_concept_recall, providing clear when-to-use and when-not-to 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 were provided, so the description must carry the full burden. It discloses that returns empty lists (not errors) when the graph hasn't been built or no matches exist, which sets correct expectations. It does not explicitly state read-only behavior, but that is implied from the search nature. This is adequate but could be improved.

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 well-structured with a brief paragraph followed by bullet points for parameters. It uses formatting (emoji, bold) to aid readability. While it could be slightly more concise, it doesn't waste words 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?

Given 7 parameters and no output schema, the description explains inputs well but the return structure is only briefly mentioned ('Returns: entities, related_entities, linked_code') without further detail on the shape or content. This is a gap, but the tool's purpose is still understandable. It meets minimum viability.

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 coverage is 0%, so the description must fully explain parameters. It does so for all 7 parameters: each has a clear purpose, default values, and acceptable ranges (e.g., limit 1-100, depth 1-5, direction enum). It adds meaning beyond the schema, which only defines types and defaults.

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 the concept graph for entities, relationships, and linked code. It uses a specific verb (search, query) and resource (concept graph). However, it does not explicitly distinguish this tool from siblings like marm_smart_recall or marm_graph_trace, leaving ambiguity.

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

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

The description provides guidance on query styles ('bare concept name' vs 'related to X'), which helps with when to use each. However, it lacks explicit advice on when to choose this tool over siblings (e.g., vs marm_smart_recall for smarter retrieval, or marm_graph_trace for tracing). No exclusions or alternatives are mentioned.

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 adequately discloses the destructive behavior and scope of deletion. It explains what gets deleted based on parameter combinations, but does not mention irreversibility or cascading 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 uses bullet points and emojis, which improves readability but adds length. It is clear but slightly verbose for the information conveyed.

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 delete tool, the description provides sufficient context about what can be deleted and how. However, missing details on the 'target' parameter and no output schema reduce completeness slightly.

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

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

The description clarifies the interaction between 'type' and 'session_name' parameters, but does not explain the 'target', 'project', or 'platform' parameters. With 0% schema coverage, the description partially compensates but leaves gaps.

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 that the tool deletes log sessions, log entries, or notebook entries. It distinguishes between different deletion behaviors based on the 'type' and 'session_name' parameters, making the purpose clear and 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 provides clear patterns for when to use each variation: deleting a specific log entry, deleting an entire log session, or deleting a notebook entry. It implicitly guides the agent to use other tools for non-deletion operations, but does not explicitly mention 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 provided, so the description carries the full burden. It discloses the failure mode: 'graph-unavailable error if the graph backend is disabled or failed to start', and also notes that omitting the project parameter auto-resolves. This gives the agent useful expectations for both success and error cases.

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?

Compact and well-organized: purpose in the first line, a clarifying sentence, then a parameter list and a returns line. Uses whitespace effectively and has 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?

Covers input, output (graph architecture response), and failure mode (graph-unavailable error). Without an output schema, it doesn't detail the response structure, but for an orientation tool this is a minor gap; the description is sufficient for basic invocation and expectation setting.

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 only defines a nullable string with a default. The description adds critical meaning: 'project name; omit to auto-resolve' clarifies the parameter's purpose and the behavior when omitted, which is far beyond the schema's minimal info.

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 'High-level architecture overview: node/edge breakdown, modules, and schema' – a specific verb+resource combination that clearly distinguishes this from sibling tools like graph_trace or graph_impact. The noun phrase 'architecture overview' leaves 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?

Explicitly frames itself as 'one-shot orientation for a project', implying use when a high-level understanding is needed. It doesn't explicitly name alternatives, but the context of sibling tools plus the 'orientation' wording makes the intended use case 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 full burden of behavioral disclosure. It usefully mentions the 'graph-unavailable error if the graph backend is disabled or failed to start' and describes the output conceptually. However, it does not explicitly state whether the operation is read-only, whether any mutation occurs, or any authentication requirements, leaving some ambiguity.

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

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

The description is front-loaded with a bold purpose statement, followed by usage, a bulleted parameter list, and return value. Every sentence earns its place, and the structure is clean and scannable. There is no redundant 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?

Since there is no output schema, the description explains returns: 'graph impact response, or a graph-unavailable error.' It also clarifies in the opening that the response includes affected symbols and propagation distance. This covers the essentials, though a more structured breakdown of the response object would make it more 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?

The input schema has 0% description coverage, so the description must compensate. It does so thoroughly by listing all four parameters with meanings and examples: 'since: git ref or date to compare from, e.g. HEAD~5, v0.5.0', 'depth: impact propagation depth, 1-5', and defaults for base_branch and project. This adds significant semantic value 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 opening line 'Blast radius of code changes: git diff → affected symbols + risk' precisely states the tool's function with a specific verb and resource. It clearly distinguishes from sibling tools like marm_graph_trace (trace specific symbols) and marm_graph_architecture (architecture view) by focusing on impact propagation from a git diff.

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 usage context: 'Pass `since` (a git ref/date) or a `base_branch` to compare against' and explains defaults for base_branch and depth. However, it does not explicitly name alternative tools or state when not to use this tool, relying on the purpose to differentiate from 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 fully carries the behavioral disclosure burden. It reveals auto-reindexing ('Indexed repos are re-indexed automatically in the background'), the effects of action options, and the possible graph-unavailable error on backend failure. It does not cover permissions or side effects on the repo, but covers the core behaviors well.

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 structured with a summary, parameter list, and return note. It front-loads the main purpose and stays under 200 words, but includes an unnecessary emoji and slightly redundant phrasing. Still, every section 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 complexity (4 optional params, multiple actions, auto-reindexing), the description covers the purpose, parameter semantics, usage order, and return/error behavior. It lacks concrete examples or response shape, but no output schema exists, so the description is sufficiently complete for an agent to invoke correctly.

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

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

Schema coverage is 0%, so the description must compensate. It does by providing per-parameter explanations: repo_path as index vs list/status, project as status check, mode as depth, and action as explicit enum with inference rules. This adds substantial meaning beyond titles and enums.

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 clear verb+resource statement: 'Index a code repository into the graph, or check status / list known projects.' It also differentiates itself from sibling graph tools by explicitly stating 'Call this first — all other graph tools need an indexed project,' establishing it as the prerequisite setup tool.

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

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

The description provides clear usage context: 'Call this first' and explains when to pass vs omit repo_path and project. It outlines the three main action modes (index, status, list) and the auto-reindexing controls, but does not explicitly name alternative tools for other graph operations, relying on the prerequisite statement to imply exclusion.

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 behavioral burden and does so well. It discloses the cross_service limitation that an empty result means 'unknown' and defines evidence strategies and confidence levels so guessed edges are transparently distinguishable. Error behavior for an unavailable graph backend is also explicitly documented.

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 prepended emoji and short purpose line front-load the key operation. Parameters are grouped in a compact bullet-style list, and each sentence adds either setup, a limitation, or parameter behavior. It is information-dense without being bloated for a tool with 8 parameters.

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

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

The description is thorough for a complex tool with no output schema or annotations: it covers behavioral caveats, direction/mode choices, evidence semantics, and backend failure. The main gap is that the return value is only described as a generic 'graph trace response', and it doesn't define the result graph shape or edge fields. Still, this is quite complete for an agent's invocation needs.

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

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

The schema has 0% description coverage, but the tool description covers all 8 parameters with meaningful semantics. It adds constraints like depth 1-5, auto-resolution for project, direction/mode meanings, risk-label behavior, and evidence strategy values. This fully compensates for the bare 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 starts with a specific action: 'Trace call paths / data flow through the graph from a function,' which clearly identifies the tool's purpose. It also lists concrete use cases ('impact analysis, dependency tracing, who calls this') that help orient an agent. The only slight overlap with the sibling marm_graph_impact is minor because this tool centers on graph traversal from a 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 gives actionable direction/mode guidance (inbound vs outbound vs data_flow vs cross_service) and states 'Use for impact analysis, dependency tracing, who calls this.' However, it doesn't explicitly state when not to use it, nor name alternatives like marm_graph_impact, marm_code_lookup, or marm_graph_architecture. Clear context exists, but exclusion/alternative guidance is missing.

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 key behaviors: entries are stored with date/topic/summary, session switching via prefix, auto-tagging of date, and storage as semantic memories for recall. It also notes return values.

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 somewhat lengthy but well-structured with bullet points and clear sections. Every sentence adds value, and the purpose is front-loaded. It could be slightly more concise, but it effectively communicates 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?

Given no output schema and low schema coverage, the description fully compensates by explaining return values, complex session-switching behavior, and storage side-effects. It is complete enough for an AI agent to use correctly without additional references.

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

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

Schema description coverage is 0%, so the description must fully define parameters. It explains that 'entry' is the text to log with optional prefixes for session/topic switching, and 'session_name' is an optional override. This adds significant meaning beyond the bare 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 writes a log entry to the active session, specifying the resource (log entry, active session) and verb (write). It distinguishes from siblings like marm_log_show (read) and marm_smart_recall (recall), which have different verbs.

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 the tool (to write a log entry) and gives detailed formatting and session-switching rules. However, it does not explicitly state when not to use it or mention alternatives, though the context from sibling names implies this.

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 description carries full burden. Describes two modes and return structures. However, does not disclose if the operation is read-only, or any potential side effects. Since it's a log viewer, likely safe, but not explicitly stated.

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?

Description is well-structured with bullet points and clear sections. Every sentence adds value without redundancy. Efficiently covers purpose, modes, parameters, and return formats.

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 1 parameter, no output schema, and no annotations, the description fully covers both modes, parameter behavior, and expected return structure. No gaps in essential information.

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?

Only one parameter (`session_name`) with schema coverage 0%. Description fully explains that it's optional and its effect on output. Provides more semantic meaning than the schema alone, which only has type and default.

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 lists log sessions or shows entries for a specific session. Distinguishes two modes based on `session_name` presence. Action verb 'list' and 'show' combined with resource 'log sessions/entries' make purpose concrete.

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

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

Explains which mode triggers when `session_name` is provided or omitted. Provides explicit context for each usage. Does not explicitly exclude scenarios or compare to sibling tools, but the guidance is clear and actionable.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does describe side effects: updating scratch entries, activating instructions, clearing the active list, and promoting to permanent docs. But it omits important behaviors like whether 'clear' also deletes scratch entries, whether 'save' removes the source entry, and session persistence semantics. This is partial transparency, not full.

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 exceptionally well-structured: a single-line summary followed by a bulleted list of actions, each one sentence. There is no fluff, and the format makes the multi-action tool easy to scan and understand quickly.

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

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

The tool has 7 parameters, multiple actions, no annotations, and no output schema, yet the description only explains a subset of actions and three of the seven parameters. It lacks the underlying conceptual model (scratch vs. active vs. permanent) and never mentions return values or session-specific behaviors. This is insufficient for an agent to fully anticipate tool behavior.

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

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

The description adds meaning for action, name, data, and names by specifying their required status per action (e.g., 'name + data required' for add). However, it completely ignores project, platform, and session_name, which are present in the schema with zero documentation. Since schema coverage is 0%, the incomplete parameter guidance creates a significant gap.

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

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

The description clearly identifies the tool as a unified notebook manager with six explicit verbs (add, use, show, status, clear, save). It distinguishes this from sibling tools like marm_log_entry or marm_smart_recall by framing it as a scratch/active entry management tool, 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?

Per-action instructions imply when to use each subcommand (e.g., 'add' for saving scratch entries, 'use' for activating instructions), and the 'notebook' context implies a general use case. However, it never explicitly contrasts with alternatives or states when not to use this tool, and there is no high-level guidance on sibling tool selection.

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 read-like behavior (search, return ranked results, graph context) but omits details like error handling, performance characteristics, or any destructive potential. Adequate but not thorough.

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?

Well-structured with a concise header, summary paragraph, and clear parameter list. Every sentence adds value without redundancy. Uses formatting (emojis, line breaks) for readability.

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 9 parameters, no annotations, and no output schema, the description covers purpose, all parameters, and return fields (status, ranked results, graph_context, results_count). Missing details on result structure or graph_context, but largely 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 0%, but the description provides detailed explanations for all 9 parameters, including enumeration for 'exact_mode' and implications for 'detail' levels. This adds significant meaning beyond the raw 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 states the tool recalls memories by semantic similarity or keyword match, with a clear verb (searches/recalls) and resource (memories). It distinguishes from siblings like marm_concept_recall by mentioning similarity scores and graph context, but does not explicitly compare.

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 siblings. It describes what it does but does not state when NOT to use it or provide alternatives for specific use cases like exact matching or code lookup.

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 states it reads log_entries and returns a markdown summary, suggesting a read-only operation. However, it does not disclose potential side effects, prerequisites (e.g., session existence), or limits (e.g., entry count). Adequate but not detailed.

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: a clear headline sentence, a brief explanation, and a command equivalence. Every sentence adds value 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's simplicity (single param, read-only), the description covers the core purpose and output format (markdown). It could mention if it only reads from the provided session or has size limits, but overall it is fairly complete for a straightforward 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?

The schema has 0% description coverage, so the description must add meaning. It mentions 'Equivalent to /summary: [session name] command', which hints that session_name is the session's name. This provides some context beyond the bare schema, but still lacks format details or examples.

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 generates a 'paste-ready context block for new chats' by reading log entries and returning a formatted markdown summary. This distinguishes it from siblings like marm_log_show (raw logs) and marm_log_entry (adding entries).

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 by equating to a /summary command, indicating it should be used to get a compact summary. However, it does not explicitly state when to use vs. alternatives like marm_log_show or marm_smart_recall, nor provide 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.