Server Quality Checklist

Tool Scores

• list_entriesA
  3.5/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It conveys that the tool returns journal file titles, dates, and section headings, and that filtering applies to path/title. However, it does not mention ordering, pagination, result limits, or how section headings are derived, leaving some behavioral ambiguity.

  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 two short sentences, front-loads the core behavior, and includes the key optional parameter without unnecessary detail. Every part earns its place.

  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 read-only list tool with a single optional parameter, the description provides the essential call details: what is returned and how filtering works. It is somewhat incomplete because it does not contrast with sibling search tools, but the low complexity and clear output fields keep the gap small.

  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?

  The schema already documents 'filter' as a case-insensitive substring filter, so the baseline is 3. The description adds meaningful scope by specifying the filter applies to path/title, which goes beyond the schema's generic wording. This clarifies the parameter's actual effect.

  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?

  The description clearly states the action ('List') and the resource ('journal files'), and specifies the returned metadata: title, date, and section headings. It does not explicitly differentiate itself from siblings like search_journal or search_regex, but the focus on listing file metadata is reasonably distinct.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives such as search_journal, get_entry, or search_regex. The optional filter is mentioned but there is no explicit indication of when listing with a substring filter is preferable to content or regex search.

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

• search_regexA
  3.7/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It makes the search behavior and scope clear and implicitly identifies the operation as non-mutating, but it does not disclose output shape, match limits, or behavior on invalid patterns. This is acceptable but incomplete.

  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?

  A single front-loaded sentence states the action and resource, then adds a compact parenthetical with high-value selection guidance. There is no wasted wording.

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

  Completeness2/5

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

  Without an output schema or annotations, the description should explain what the tool returns and clarify the k parameter's role. Neither is provided, leaving an agent uncertain about result format and how to configure search depth. This is a meaningful gap for a tool that is otherwise simple.

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

  Parameters2/5

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

  Schema description coverage is only 50%: pattern is described, but k has no semantic description beyond numeric bounds. The tool description reinforces pattern's purpose but says nothing about k, so an agent must guess whether k means top-k results, page size, or something else.

  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 names the operation as regex search over journal chunks and adds an explicit escape-hatch purpose: symbols, paths, and exact identifiers. This distinguishes it from the likely keyword-based search_journal sibling without opening any schema.

  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 'escape hatch' phrasing plus the concrete use cases tell an agent when to reach for this tool rather than a normal search. It does not explicitly name search_journal as the default alternative or state when not to use it, so it stops short of full routing guidance.

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

• get_entryA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral disclosure burden. It conveys read-only retrieval and the return shape ('full markdown'), but it doesn't disclose behavior for missing files, ambiguous bare filenames, or path resolution roots. Adequate but with gaps.

  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?

  One concise sentence that front-loads the action and scope, with no filler or redundancy.

  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 one-parameter retrieval tool, the definition plus the schema specify the input and the returned content ('full markdown'), which is enough for basic invocation. It doesn't fully specify edge-case behavior, but that is a modest gap at this complexity.

  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%, and the schema already explains the path parameter with an example. The description mostly restates the same addressing idea and adds no new parameter-level semantics beyond that.

  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 identifies a specific verb ('Return'), a specific resource ('full markdown of one journal file'), and the addressing method ('by relative path or filename'). This clearly distinguishes it from the list, search, and write sibling tools.

  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 clearly implies when to use it: when you need the complete markdown of a single known journal entry addressed by path or filename. It doesn't explicitly discuss exclusions or alternatives like search_journal, but the retrieval context is clear.

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

• search_journalA
  4/5.0
  Behavior4/5

  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 hybrid retrieval algorithm (BM25 + vector), the chunking strategy (heading-chunked), and the return format (ranked hits with file#heading citations), which effectively communicates read-only behavior and result structure. It omits details like pagination or authentication, but for a search tool the core behavior is transparent.

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

  Conciseness5/5

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

  The description is composed of two concise, information-dense sentences with no filler. The core mechanism and resource are front-loaded, followed by the output format, making every word useful.

  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 two-parameter tool with no output schema, the description covers the key aspects needed to invoke it correctly: the search scope, the retrieval method, and the return format. It does not describe the exact structure of a hit beyond file#heading citations, but this is acceptable given the tool's simplicity.

  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 description coverage is 50%: 'query' has a description and 'k' has default/min/max but no description. The tool description adds no explicit parameter-level guidance; however, 'Returns ranked hits' combined with k's default of 8 implies k controls result count. The description only marginally compensates for the missing k description.

  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 states a specific verb ('search'), a specific resource ('team markdown journals'), and the method ('Hybrid BM25 + vector semantic search'), while also noting the heading-chunked indexing and citation-style output. This clearly distinguishes it from sibling tools, especially search_regex, by indicating semantic rather than regex-based search.

  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?

  The description implies usage for semantic/fuzzy search over journals and contrasts with the existence of search_regex, but it does not explicitly say when to use this tool versus alternatives. There is no 'use search_regex for regex patterns' or similar guidance, leaving the decision to inference.

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

• write_entryA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses key behavioral details: filename generation from date and title slug, return value (file path), and the vector index side effect. It does not mention duplicate-title collision behavior, but the provided details are substantial.

  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 tight sentences with no filler. The core action is front-loaded, followed by filename behavior, return value, and the vector index side effect. Every sentence earns its place.

  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 two-parameter create tool with no output schema, the description covers the return value, file naming, and an important side effect. It could mention what happens on filename collision, but the essentials an agent needs to call it correctly are present.

  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%, so the baseline is 3. The description adds a bit of context by noting the date is part of the generated filename, but most parameter meaning is already present in the schema descriptions.

  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 action ('Create a new markdown journal entry') and names the resource. It is distinct from the sibling read/search/list tools, so an agent can tell it apart without extra inference.

  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 makes the intended use obvious: creating a new journal entry. It does not explicitly name alternatives or exclusions, but the contrast with read/search/list siblings is clear enough for a straightforward create operation.

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