Server Quality Checklist

Tool Scores

• recent_in_dirA
  3.9/5.0
  Behavior4/5

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

  Annotations already indicate read-only, idempotent, non-destructive. Description adds prerequisite, limitation on legacy entries, return order (newest first with timestamps and exit codes), and scope (local index only). No contradiction.

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

  Conciseness5/5

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

  Three sentences, each adding key info: read-only status, purpose, prerequisite, limitation, output details. No wasted words.

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

  Completeness5/5

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

  Given full schema coverage, annotations, and output schema, the description covers purpose, prerequisites, limitations, output order, and scope. Complete for a list tool.

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

  Parameters3/5

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

  Schema covers both parameters fully (100% coverage). Description adds no extra parameter-specific detail beyond output format (newest first, timestamps). Baseline 3 is appropriate.

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

  Purpose4/5

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

  Clearly states it lists recent commands by working directory with a natural language example. Does not explicitly compare to siblings like search_history, but the specificity is sufficient for an agent to distinguish.

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

  Usage Guidelines3/5

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

  Describes when to use it (recall commands in a project directory) and mentions a prerequisite (shell hook) and limitation (legacy entries excluded). Does not explicitly say when not to use it or name alternatives.

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

• failed_commandsA
  4.2/5.0
  Behavior4/5

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

  Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds behavioral details: the need for a shell hook, legacy behavior, ordering (newest first), and scope (local index only). No contradictions with annotations.

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

  Conciseness5/5

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

  The description is three sentences with no redundancy. Each sentence serves a purpose: stating the function, describing optional filtering, and listing constraints. It is front-loaded with the most critical information.

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

  Completeness4/5

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

  For a simple list tool with two well-documented parameters, the description covers purpose, constraints, filtering, and prerequisites (shell hook). Output schema exists for return values. Minor gap: no mention of what happens if hook is missing, but that is acceptable.

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

  Parameters3/5

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

  Schema coverage is 100% with clear descriptions. The description adds minor value by restating the filter option in prose ('optionally restrict to commands after a given epoch-millisecond timestamp') and mentioning ordering, but the schema already defines the parameters adequately.

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

  Purpose5/5

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

  The description clearly states the tool lists recent failed commands (non-zero exit) as a quick feed. It uses specific verb 'lists' and resource 'failed commands', and distinguishes from siblings like search_history by emphasizing its scope and immediacy.

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

  Usage Guidelines4/5

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

  The description provides explicit usage context: read-only, requires shell hook for exit-code capture, legacy entries lack exit codes, and results are newest first and local index only. It doesn't explicitly name alternatives but implies when to use this tool.

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

• command_chainsA
  4.5/5.0
  Behavior5/5

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

  The description starts with 'Read-only', matching annotations (readOnlyHint=true, destructiveHint=false). It also discloses that it returns time-ordered sequences and uses a local index only, providing full behavioral transparency beyond annotations.

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

  Conciseness5/5

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

  The description is concise (4 sentences), front-loaded with 'Read-only', includes an example sequence and a practical use case. Every sentence adds value.

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

  Completeness5/5

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

  Given the presence of an output schema (not shown but implied), the description need not detail return format. It covers behavior, use case, and limitations (local index), making it complete.

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

  Parameters3/5

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

  Schema coverage is 100% with parameter descriptions. The description adds context like default window and purpose but doesn't significantly enhance parameter semantics beyond what's already in the schema.

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

  Purpose5/5

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

  The description clearly states it returns command chains around a query match, surfacing multi-step sequences. It distinguishes itself from siblings like search_history (which gives individual commands) and recent_in_dir (which shows recent commands).

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

  Usage Guidelines4/5

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

  It provides a clear use case: 'reconstructing how did I do X last time?'. While it doesn't explicitly exclude scenarios, the context of sibling tools implies when to use this vs. other search tools.

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

• search_historyA
  4.7/5.0
  Behavior5/5

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

  Adds significant behavioral context beyond annotations: declares read-only, specifies search algorithm (FTS5, stemming, Unicode), result ordering, returned fields (timestamp, shell, cwd, exit code), and privacy guarantee (local index only). No contradictions with annotations.

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

  Conciseness5/5

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

  Three sentences, front-loaded with core action and key features. Every sentence adds essential information without redundancy. Efficiently covers purpose, usage, details, and fallback.

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

  Completeness5/5

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

  Given full schema coverage, annotations, and output schema existence, the description is complete. It covers what the tool does, how to use it, what to expect in return, privacy, and relationship to sibling tool, leaving no gaps for an agent.

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

  Parameters4/5

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

  Schema already describes both parameters (100% coverage). Description adds value by explaining query syntax with examples and clarifying that prefix matching requires an asterisk, and by noting the default limit is 20 and results are newest first.

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

  Purpose5/5

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

  Clearly states it is a full-text search over indexed shell commands using SQLite FTS5. Specifies resource (shell history) and action (search), with details on stemming and Unicode-awareness. Differentiates from sibling 'reindex' by mentioning it as a fallback.

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

  Usage Guidelines4/5

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

  Provides explicit examples of keyword and prefix queries, describes return fields and ordering, and advises when to use 'reindex' if no results. Does not explicitly compare to other sibling tools like command_chains or failed_commands, but context is sufficient.

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

• reindexA
  4.8/5.0
  Behavior5/5

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

  The description reveals idempotency (already-indexed skipped by hash), safety for repeated calls, reads only local files, writes only to a specific directory, and returns counts. Annotations provide idempotentHint=true and destructiveHint=false, and the description adds specific behavioral details beyond annotations.

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

  Conciseness5/5

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

  The description is concise (three sentences), front-loaded with the main action, and every sentence adds value without redundancy.

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

  Completeness5/5

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

  With zero parameters, an output schema (mentioned), and clear annotations, the description fully covers purpose, behavior, use case, and return value. No gaps.

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

  Parameters5/5

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

  Input schema has no properties, and the description explicitly states 'Takes no arguments.' Schema coverage is 100%, so no additional parameter info needed.

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

  Purpose5/5

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

  The description clearly states the tool re-parses shell history files into a SQLite index. It distinguishes itself from sibling query tools by focusing on indexing, and it explicitly mentions idempotency and use case (after burst of shell activity).

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

  Usage Guidelines4/5

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

  The description explicitly recommends running after a burst of shell activity to make recent commands searchable. It does not explicitly state when not to use it, but the sibling tools imply that this is for indexing rather than querying, providing sufficient context.

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