Server Quality Checklist

Tool Scores

• proximo_tool_schemaC
  2.8/5.0
  Behavior2/5

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

  No annotations are provided, so the description must disclose behavior. It states that the tool returns the full description and JSON input schema, but it omits critical behavioral details such as error handling for invalid tool names, side effects, or read-only guarantees. For a tool with no annotation support, this is a significant gap.

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

  Conciseness4/5

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

  The description is a single, compact sentence that front-loads the core output. It is efficient and free of unnecessary content, though it is not a fully grammatical sentence and could benefit from clearer structure.

  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?

  For a simple tool, the description covers the basic function but lacks details on the return structure (e.g., whether it returns an object with 'description' and 'schema' fields), error behavior, and the relationship to proximo_find_tools. There is no output schema to compensate for these gaps, leaving the description incomplete.

  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?

  The schema has 0% description coverage, so the description carries the burden. It adds meaning by clarifying that 'name' refers to a tool found via proximo_find_tools. However, it does not specify format constraints, defaults, or the exact source of the name, leaving some ambiguity.

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

  Purpose3/5

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

  The description identifies the resource (full description and JSON input schema) but lacks a clear verb/action. It distinguishes itself by referencing 'one tool found via proximo_find_tools,' but the purpose remains vague and without a direct statement of 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.

  Usage Guidelines3/5

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

  Usage is implied: this tool is used to retrieve the schema for a tool discovered via proximo_find_tools. However, it does not explicitly state when to use this tool versus alternatives, nor provide any exclusions or conditions for use.

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

• proximo_find_toolsA
  4/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 transparency burden. It discloses that 'all terms must match' and mentions the 'facade is resident' and 906 searchable tools, adding some behavioral context. However, it does not describe the return format, pagination, or error behavior, leaving significant ambiguity.

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

  Conciseness4/5

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

  The description is front-loaded with the core purpose and then branches into usage guidance. The structure is logical, but the second paragraph includes verbose elements like 'ESTATE QUESTIONS' and 'facade is resident' that could be clearer. Still, every sentence serves a purpose and there is no redundant filler.

  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?

  The tool has an output schema, so it does not need to describe return values. The description covers the main scenarios, distinguishes from proximo_recall, and gives a necessary workflow. However, it does not address the 'limit' parameter or potential edge cases, leaving some gaps for a search tool.

  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?

  The schema has 0% description coverage, yet the description adds minimal meaning beyond what the schema already shows. It implies 'query' is a keyword and notes that 'all terms must match,' but it never explains the 'limit' parameter or offers any formatting guidance. This is insufficient given the lack of 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 opens with 'Search Proximo's full tool catalog by keyword,' which clearly states the tool's verb, resource, and scope. It also explicitly contrasts with proximo_recall, making the purpose unambiguous and distinct from siblings.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance: use proximo_recall for existential/count/change/time questions, and use this tool 'for everything else.' It also outlines a clear workflow (search, then proximo_tool_schema, then proximo_call), covering both when to use and the alternatestool.

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

• audit_verifyA
  4.2/5.0
  Behavior4/5

  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 explains the core hash-chain verification, lists specific tampering scenarios it can catch, and states the environment-variable fallback. While it doesn't describe return values or side effects, the read-only verification behavior is adequately conveyed.

  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 exceptionally tight: three sentences that front-load the verb and resource, then explain the optional parameter and fallback. There is no filler, and each sentence contributes directly to understanding the tool's use.

  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 tool with only one optional parameter and no output schema, the description covers the purpose, the optional parameter, and the fallback mechanism thoroughly. The only notable gap is the lack of detail about the verification result (e.g., boolean success, status message), but this is a minor omission given the tool's simplicity and the absence of an output schema.

  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 schema already documents expected_head's purpose, format, and fallback. The description repeats this information almost verbatim ('also catches tail truncation, a forged tail-append, or a full ledger replacement'), adding no new semantic detail beyond what the schema provides. Baseline 3 is appropriate.

  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 specifies the verb 'Verify' and the resource 'tamper-evident audit ledger's hash chain,' with an explicit goal to 'PROVE the log is intact.' This precisely differentiates it from sibling tools like audit_entries, which likely list entries rather than verify integrity.

  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 concrete guidance on when to pass expected_head (to catch tail truncation, forged tail-append, or full replacement) and explains the fallback to PROXIMO_AUDIT_EXPECTED_HEAD. It even contrasts with a forward-walk-only approach, giving a clear use case, though it doesn't explicitly name alternative tools.

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

• proximo_callA
  4.6/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the burden. It discloses the security gates (dry-run PLAN, ledger entry, token ACL) and explicitly states this is a 'smaller doorway' not a 'looser' one, providing behavioral context beyond structured fields. It does not mention error handling or return format, but these are inherently tool-dependent.

  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 earning its place: the purpose, the prerequisite step, and the security context. It is front-loaded and free of redundant or filler content.

  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 generic dispatcher, this is quite complete. It covers what the tool does, how to find argument shapes, and the applicable permission gates. The lack of return-value details is excusable because the output depends on the target tool.

  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 coverage is 100%, so the baseline is 3. The description adds value by directing users to proximo_tool_schema for the argument shape, which is essential because arguments are dynamic and tool-specific. This goes beyond what the static schema descriptions provide.

  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 "Call any Proximo tool by exact name, including ones not in this server's listed tools." This clearly identifies the action (call) and resource (Proximo tools), and explicitly distinguishes it from sibling tools by noting it can invoke non-listed tools.

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

  Usage Guidelines5/5

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

  It gives explicit preparation guidance: "Get the argument shape from proximo_tool_schema first." It also clarifies when it's appropriate by noting "Same gates as calling it directly" and "A smaller doorway, not a looser one," meaning it is not an escalation path. This effectively tells the agent how to use the tool and what to expect.

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

• audit_entriesA
  4.9/5.0
  Behavior5/5

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

  With no annotations, the description carries the full burden and delivers: it declares READ-ONLY safety, newest-first ordering, response semantics (matched/total/truncated), and a nuanced null-principal behavior that prevents misinterpretation as a blame claim. This is far beyond a typical minimal description.

  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?

  Front-loaded with the safety marker and core purpose, then progressively covers use cases, response metadata, edge-case behavior, and sibling contrast. Every sentence earns its place; nothing is redundant or filler despite the length.

  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?

  Lacking both annotations and an output schema, the description compensates by explaining the return shape (matched/total/truncated), null-principal behavior, and ordering — plus differentiating the closest sibling (audit_verify). For a 5-param read-only query tool, this is complete.

  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 covers all 5 parameters (100%), so baseline is 3. The description adds value by explaining how the filter params relate to the `matched` count and how `limit` triggers `truncated`, enriching the semantic meaning of both filter and pagination parameters beyond the schema text.

  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?

  Opens with 'READ-ONLY: WHO changed WHAT and WHEN' — a specific verb (read) plus resource (PROVE ledger) and scope (guest config changes and all audited actions). It clearly distinguishes itself from the sibling audit_verify by stating it READS the chain while audit_verify PROVES integrity.

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

  Usage Guidelines5/5

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

  Explicitly frames usage: 'This is how you answer "who changed this guest" or "what has this caller done"'. It also gives a when-not signal by contrasting with audit_verify ('This READS the chain; audit_verify PROVES it is intact'), steering the agent to the right sibling for integrity checks.

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

• proximo_recallA
  5/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, the description reveals that this is a snapshot from local memory, not live data, and that entries carry as_of and age_seconds stamps. It also clarifies that not_seen_since is an observation, not proof of deletion, and that journal entries are summaries only — substantial behavioral detail that the annotation alone does not convey.

  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 dense but highly efficient; every sentence and clause adds operational value. It front-loads the most important distinction (memory vs live) and uses compact, scannable phrasing like 'stamped {source:'memory', as_of, age_seconds}' and 'not_seen_since (last observed before the window — a fact, not a claim the entity is gone)' to pack maximum insight into limited text.

  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 tool's complexity (optional diff windows, journal integration, memory configuration) and the presence of an output schema, the description covers the essential semantics: data freshness, server-side counting, derivation/rebuildability, and safe usage guidance. It fully equips an agent to decide when and how to invoke the tool without missing behavioral nuances.

  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?

  Although the schema already documents all four parameters with descriptions, the tool description adds critical cross-parameter behavior: `since` activates diffs (appeared, status_changed, not_seen_since), `journal=N` includes diagnosis digests and is windowed by `since`, `query` narrows rows but counts cover the whole estate, and `detail` controls row depth. This enriches meaning well beyond the individual schema entries.

  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 opens with 'READ-ONLY: the estate map from local Tier-1 memory' which clearly identifies the resource and operation. It explicitly contrasts with 'NOT a live PVE read' and enumerates the exact return contents (counts, entity rows, stamps), distinguishing it from sibling audit and tool-discovery tools.

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

  Usage Guidelines5/5

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

  The description gives explicit when-to-use and when-not-to-use guidance: 'For live state use pve_list_guests / pve_cluster_resources' while this tool serves memory-derived summaries. It also advises trusting guest_summary for guest-count questions and explains that `since` and `journal` are optional for diffs and digests, providing clear context for choosing this tool over alternatives.

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