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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Read-only — never modifies the workspace' and mentions the return format ('severity, file, line'). This adequately covers the safety and output profile, though it does not address performance, prerequisites, or error behavior.

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

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

The description is succinct but information-dense: two sentences plus a compact list of checks with parenthetical definitions. It front-loads the core purpose and safety note, then covers usage. Every sentence adds value; there is no fluff.

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

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

For a complex scanner with 6 checks and no output schema, the description covers purpose, specific checks, output fields (severity, file, line), read-only safety, and usage timing. It lacks an example output or error handling details, but it gives enough for an agent to select and invoke the tool appropriately.

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 semantic meaning to the check enums by explaining each (e.g., 'muro_de_fuego (queries to ops_* without ownerId)'), which goes beyond the schema's enum values. This enriches parameter understanding and justifies a 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 identifies the tool as a 'Read-only KOMO antipattern detector' and explains it 'Scans files' for a specific list of antipatterns, with a clear verb and resource. This distinguishes it from sibling tools like mavis_git or mavis_write, which handle version control or file writing.

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: 'Use before commits, before refactors, or as a code review assistant.' This gives clear context and timing, though it does not mention any exclusions or specific alternatives. Still, the guidance is unambiguous.

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

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

The description discloses return values (stdout, stderr, exit code) and the behavioral constraint 'no shell interpolation.' With no annotations provided, the description carries the full transparency burden, but it does not mention potential side effects, permissions, or how non-zero exit codes are handled. This is sufficient for basic understanding but lacks deeper 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?

The description is two sentences long and every part adds value: purpose, return values, usage scenarios, and a behavioral guideline. It is front-loaded with the primary action and contains no filler or redundancy.

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

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

The tool is relatively simple with only three parameters, all documented in the schema. The description covers the core purpose, return values, and usage guidance, which is sufficient for selection and invocation. It could mention side effects or failure behavior, but given the tool's simplicity and schema richness, the current description is adequately complete.

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

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

Schema description coverage is 100%, so the input schema already documents all three parameters (command, cwd, timeout_ms). The description does not add parameter-specific meaning beyond the schema, which is acceptable given the high coverage. It indirectly implies cwd behavior by saying 'in the workspace,' but this is already 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 states exactly what the tool does: 'Run a shell command in the workspace.' It also distinguishes itself from specialized sibling tools by explicitly positioning itself as the general-purpose CLI runner (git, npm, vitest, supabase, node, etc.), making it clear when to use this tool over a specialized sibling.

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

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

The description provides clear usage context: 'Use this to run any CLI' with examples. It also gives a practical guideline: 'Prefer specific commands over shell scripts (no shell interpolation).' However, it does not mention any exclusions or when to prefer specialized siblings like mavis_git or mavis_supabase, so it falls short of a full 5.

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

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

With no annotations provided, the description carries the full burden. It does disclose the return format ('Returns the model content plus token usage and latency') and implies statelessness via 'single text generation.' However, it does not discuss potential costs, rate limits, authentication, or error behavior. The disclosure is useful but not comprehensive, meriting a mid-range score.

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 core purpose and usage. It includes return behavior and an alternative pointer without filler. Every sentence earns its place, making it 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?

For a simple text-generation tool with 5 parameters and no output schema, the description covers the key points: what it does, when to use it, what it returns, and an exclusion for multi-step work. It lacks an example or explicit mention of statelessness, but these are not critical for this tool's complexity. Overall, it is sufficiently 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%: every parameter (model, prompt, system, max_tokens, temperature) has a description in the schema. The tool description adds no additional parameter-level information beyond what the schema already provides. 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 function: 'Call MiniMax-M3 (OpenAI-compatible) for a single text generation.' It specifies concrete use cases (drafting code, writing explanations, summarizing files) and distinguishes itself from multi-step agentic work by pointing to an alternative. The verb is specific and the resource is 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 explicitly says when to use this tool ('Use for drafting code, writing explanations, summarizing files, or any text-in/text-out task') and when not to use it ('For multi-step agentic work with tool calling, see Sprint B-2'). However, the alternative pointer is vague ('Sprint B-2 (not yet implemented)') and does not name the sibling tool mavis_coder_agent, which could be the actual alternative. This prevents a perfect score.

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 comprehensively covers key behaviors: iterative tool calling, exclusion of itself (recursion guard), realtime progress notifications, and persistence to ~/.mavis-mcp/agent-sessions/. It also reveals the default doctrine (B-6) exposing all tools. This is rich behavioral transparency for an agent-loop 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 a single dense paragraph that front-loads the core purpose and then details key behavioral aspects. The list of invocable tools is somewhat redundant with "ANY mavis_* tool" but provides concrete examples. Every sentence contributes value, and the length is reasonable for the tool's complexity.

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

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

For a complex agent-loop tool with 10 parameters and no output schema, the description covers the essential behavioral context: how the loop operates, what tools are exposed, progress notifications, persistence, and the recursion guard. It doesn't discuss potential failure modes or typical use-case scenarios, but the core functionality is well documented.

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 all 10 parameters are already documented in the input schema. The description adds no additional meaning about parameters; it focuses on tool behavior rather than parameter specifics. Thus, it meets the baseline for high schema coverage but doesn't go beyond it.

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

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

The description clearly states the tool's function: "Run a multi-step agent loop where MiniMax-M3 can call ANY mavis_* tool ... iteratively until the task is done." It explicitly names the resource (mavis_* tools) and distinguishes itself from sibling tools by being the orchestrator that invokes them. It also provides specifics like recurrence guard and persistence, making the purpose unmistakable.

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

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

The description gives clear context for when to use this tool: when you want the LLM to autonomously decide which tools to call in a multi-step loop. It states "Default doctrine (B-6): ALL tools are exposed to the LLM — including non-LLM ones. The LLM is the one that decides which to call." It also notes exclusions (recursion guard). However, it lacks explicit 'when not to use' guidance or direct comparison to calling individual tools directly.

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 disclosing behavior. It reveals the default first-occurrence behavior, error handling for missing/multiple matches, and the effect of all_occurrences. This adds significant context beyond a simple 'edit' intent, though it omits details about file existence 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?

Three concise sentences that lead with the core action, then behavioral defaults/errors, and end with usage guidance. Every sentence earns its place with no redundancy or filler.

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

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

For a simple edit tool with no output schema, the description provides enough context: what it does, default behavior, error conditions, and when to use an alternative. It is complete given the tool's simplicity and the schema's rich parameter documentation.

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

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

The input schema covers all parameters with 100% coverage, so baseline is 3. The description adds value by explaining error behavior tied to old_text and all_occurrences, and clarifying the default replacement behavior. This semantic context goes beyond the schema's simple parameter 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 action: 'Edit a file by replacing a specific string with new text.' It specifies the resource and the operation, and explicitly distinguishes itself from mavis_write for full rewrites, making it distinct from sibling tools.

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

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

Provides explicit guidance: 'Use this for targeted edits; use mavis_write for full rewrites.' Also explains error conditions when old_text is not found or when multiple matches occur with all_occurrences=false, which helps the agent decide when to call this tool.

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

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

With no annotations, the description carries the full burden. It discloses the core behavior (runs git commands) and the security rationale for array arguments, but does not explain output formatting, error handling, or side effects of commands like 'push'. The examples provide some context, but a more detailed behavioral note (e.g., 'commands are executed in the workspace root') 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 two sentences, front-loaded with the purpose, and includes a compact list of examples. Every sentence contributes 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?

Given the tool's simplicity, 100% schema coverage, and absence of output schema, the description is reasonably complete. It clarifies argument passing and provides common usage examples. It misses a warning about potentially destructive commands (e.g., push, reset), but the agent can infer risks from the git context. Overall, it is sufficient for correct invocation in most scenarios.

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

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

Schema coverage is 100% for both parameters (cwd and args), so the bar is at baseline 3. The description adds examples that partially mirror the schema's own examples, offering slight reinforcement but no fundamentally new meaning. The security note about array args adds value beyond the schema's generic 'array of strings'.

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 'Run a git command in the workspace' with a specific verb and resource, and provides a range of concrete examples (status, log, diff, add, commit, push) that distinguish it from siblings like mavis_bash. It is immediately obvious what the tool does.

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

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

The description implies usage for git commands in the workspace and explicitly mentions passing args as an array to avoid shell injection, which is a security guideline. However, it does not explicitly contrast with alternatives (e.g., 'use mavis_bash for non-git commands'), leaving some implicit inference. The examples clarify common use cases.

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

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

With no annotations provided, the description must carry the behavioral burden. It discloses the prerequisite (nlm CLI installed and authenticated), but the side effects of mutating actions (add_source, create_notebook) are only implied by the action names. It does not explain the effect on the notebook, potential reversibility, or timeout behavior beyond the schema's timeout_seconds parameter.

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, front-loaded with the primary purpose, then usage context, then operational details. Every sentence adds unique value without redundancy, and it fits within a brief paragraph.

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 (5 actions, 7 parameters, no output schema), the description provides a useful orientation: it identifies the default notebook, gives example use cases, and lists actions. However, it does not map actions to their required parameters or explain what each action returns, which would be needed for a complete 5. Still, the schema covers per-parameter requirements, so 4 is fair.

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 with descriptions for every parameter, so the baseline is 3. The description adds value by explaining that the default notebook is the KOMO OS doctrinal manifesto (50+ sources), giving meaning to the notebook_id and action defaults. It also lists the actions, which reinforces the enum, but doesn't deepen parameter semantics further.

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 that this tool queries and updates the KOMO OS NotebookLM notebook via the nlm CLI, and lists the specific actions (query, add_source, create_notebook, list_notebooks, doctor). This distinguishes it from sibling tools like mavis_git or mavis_bash, which have different domains.

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 explicitly says 'Use to check doctrinal alignment, look up historical decisions, and document new patterns,' giving clear use cases. It also notes the prerequisite that the nlm CLI must be installed and authenticated. However, it does not mention when not to use this tool or name alternatives, so it is just shy 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?

The description discloses important behavioral traits: return types (text vs base64), truncation of large files, and the need for partial reads. However, it references a non-existent 'offset' parameter, which is misleading, and omits other behavioral details like error handling, file size limits, or explicit confirmation that this is a read-only operation (though that is implied by the 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 concise and front-loaded with the core action 'Read a file from the workspace.' The second sentence provides useful details about return types and truncation. However, the 'use offset' clause is inaccurate and unnecessary, preventing a perfect score.

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

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

For a simple read tool with no output schema, the description covers return format and truncation behavior, which is good. But the mention of 'offset' without the parameter existing, combined with no explanation of how max_lines relates to partial reads, leaves an ambiguous path for handling large files. Overall, it is adequate but has a clear 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?

The schema has 100% parameter description coverage, so the baseline is 3, but the description introduces an 'offset' parameter that is not part of the input schema, potentially confusing the agent. It adds no additional meaning beyond the schema for cwd, path, or max_lines, making the net contribution negative.

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 'Read a file from the workspace' and specifies return types (text or base64), making the tool's purpose unambiguous. However, it does not explicitly differentiate from sibling tools like mavis_search or mavis_write, so it misses the highest tier of clarity.

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

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

The description gives a clear context for reading files and notes truncation for large files, but it does not explicitly state when to use this tool instead of alternatives or when not to use it. The advice to 'use offset for partial reads' is actionable but references a parameter that does not exist in the schema, which undermines the 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states the output behavior ('Returns the full vitest output (truncated at 5MB)') and the pattern-filter behavior. It does not disclose potential side effects (e.g., tests modifying files), but for a test runner this is arguably implied. The truncation note is a valuable behavioral detail.

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 primary action, and every phrase adds value. It includes the action, scope, filtering option, output behavior, and use cases without 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?

The tool has four parameters, no output schema, and no annotations. The description covers the main behavior, output format, and use cases. It does not explain each parameter, but the schema covers them. It could mention potential side effects or environment considerations, but for a focused test runner the description is sufficiently complete.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds only a brief mention of the pattern filter, consistent with the schema. It does not elaborate on timeout, bail, or cwd beyond what the schema states, so the description provides no significant additional meaning. 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 opens with 'Run vitest tests in the workspace', a specific verb+resource combination. It clearly distinguishes from sibling tools like git, bash, or search by focusing exclusively on test execution. The optional pattern filter and output note reinforce this dedicated purpose.

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

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

The description explicitly states when to use the tool: 'to verify a fix worked or to reproduce a failure.' This provides clear context for usage. It does not explicitly mention when not to use it or name alternative tools, which prevents a 5, but the given use cases are sufficient for a narrow tool.

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

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

With no annotations provided, the description carries the full burden. It discloses the return format (file:line:match lines) and the backend selection behavior (ripgrep if available, else node recursive search), which adds transparency about performance and fallback. However, it does not disclose potential edge cases like regex syntax differences or hidden file behavior, so it's not fully 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 extremely concise, using three short sentences to convey purpose, output format, and implementation. Every sentence earns its place, with no filler.

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

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

Given the moderate complexity and lack of an output schema, the description adequately explains the return format and execution behavior. It does not mention any limitations such as gitignore behavior, but for a simple search tool, it is sufficiently 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 provides 100% coverage with detailed descriptions for all 5 parameters, so the baseline is 3. The description does not add additional parameter semantics beyond what the schema already states.

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

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

The description clearly states the tool's purpose: searching for a regex pattern across files in the workspace, with a specific output format of file:line:match lines. This is a specific verb and resource, and it distinguishes itself from sibling tools by focusing on regex search across the workspace.

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 provide any guidance on when to use this tool versus alternatives like mavis_read or mavis_bash. It only describes the tool's execution strategy (ripgrep vs node fallback), not usage 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?

With no annotations provided, the description carries the full burden. It discloses the destructive 'clear' action (delete sessions older than N days) and lists all actions, but it does not elaborate on return formats, safety precautions, or file system side effects beyond the path. The initial verb 'Read' could be slightly misleading given that 'clear' mutates data.

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

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

Two sentences, front-loaded with the resource path and actions. No redundant wording; every sentence adds value. The structure is efficient and scannable.

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 main purpose and actions, but given no output schema, it lacks details on return formats (e.g., what 'list' returns, session ID format) and relies on the schema for parameter specifics. Adequate but not comprehensive for a multi-action 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%, with each parameter having a description and constraints. The description adds minimal parameter detail beyond enumerating actions, so it relies on the schema's high coverage. 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 clearly states it reads agent run traces from a specific path (~/.mavis-mcp/agent-sessions/) and enumerates supported actions (list, get, tail, clear). This distinguishes it from sibling tools by its focus on session logs and explicitly mentions the relevant agent (mavis_coder_agent).

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 explicitly states when to use the tool: 'Use to debug, audit, or post-mortem past mavis_coder_agent runs.' This provides clear context and implies the tool is for retrospective analysis, though it does not mention alternatives or when not to use it.

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

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

With no annotations, the description carries the full transparency burden. It discloses that 'get' returns recent files touched and exit codes (read operation), and 'save' forces a disk flush (write operation). This sufficiently communicates the read/write nature and key behaviors, though it doesn't mention auto-save behavior or potential 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 two sentences long, front-loaded with the main purpose, and every word contributes. It avoids fluff and clearly organizes the two actions. This is an exemplary concise structure.

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

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

For a simple one-parameter enum tool, the description is complete: it explains both actions, gives the use case for 'get,' and describes the effect of 'save.' No output schema exists, but the description states what 'get' returns. Minor gaps include not mentioning error conditions or auto-save behavior, but overall it's well-rounded.

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 covers 100% of parameters with an enum description, providing a baseline of 3. The description adds value beyond the schema by specifying what 'get' returns ('recent files touched and last exit codes') and clarifying 'save' as 'force flush state to disk,' which is more detailed than the schema's 'force flush.'

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

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

The description clearly states the tool's function: 'Get or update the MCP server's persistent state.' The verb+resource construction is specific, and the two actions (get/save) are explicitly distinguished. It differentiates from sibling tools (e.g., mavis_read, mavis_write) by focusing on server-wide state rather than file operations.

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

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

The description gives concrete guidance: 'Use "get" to see recent files touched and last exit codes' and 'Use "save" to force flush state to disk.' This effectively tells when to use each action, but it does not explicitly mention when not to use the tool or provide alternatives. Thus, clear context but no exclusions.

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

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

With no annotations, the description supplies the key behavioral constraint: read-only by design and specific denied subcommands. It does not cover error handling or output, but it adds the most critical safety context for an agent.

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: purpose first, followed by a behavioral constraint, then concrete examples. Every sentence provides necessary information without fluff, making it 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 simple two-parameter tool with no annotations or output schema, the description conveys enough to select and use it: what it does, what it denies, and how to pass args. It lacks return-value details, but the core context is present.

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

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

The schema already covers both parameters with 100% description coverage, so the baseline is 3. The description's examples reinforce the args format but do not add significant semantic depth 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 it runs a supabase CLI command in the workspace, which is a specific verb and resource. It also notes the read-only design, further differentiating it from generic shell or write tools.

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

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

The description explicitly denies write subcommands (db push, db reset, db execute), providing clear when-not guidance. It gives examples of acceptable commands, but does not name alternative tools for write operations, leaving usage context clear but not fully explicit.

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

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

With no annotations provided, the description discloses key behaviors: overwrites any existing content and creates parent directories as needed. This goes beyond simple verb phrasing and alerts the agent to the destructive overwriting nature, which is crucial for safe tool selection.

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

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

The description is four concise sentences, front-loaded with the core action, then adds important behavioral details and usage guidance. No filler or 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?

The tool is a straightforward file-write operation. The description covers purpose, key behaviors (overwrite, mkdir), and usage boundaries, which is sufficient given the simple schema and lack of an output schema. It doesn't address edge cases like error handling, but that is not essential for this simple 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 input schema already provides full descriptions for all 3 parameters (coverage 100%), so the description need not repeat parameter-level details. The phrase 'full file content' reinforces the content parameter, but adds no new semantic information 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 opens with a specific verb and resource ('Write content to a file') and immediately clarifies the overwrite behavior, clearly distinguishing it from sibling tools like mavis_edit. It also specifies the exact use case ('new files or full rewrites').

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

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

Explicitly states when to use: 'Use this for new files or full rewrites.' It also names the alternative: 'For targeted edits, use mavis_edit instead.' This provides clear selection guidance.

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