Server Quality Checklist

Tool Scores

• guide_neighboursD
  1.3/5.0
  Behavior1/5

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

  No annotations are provided, and the description does not disclose side effects, permissions, data mutation, rate limits, or whether the operation is read-only. The agent is given no behavioral expectations beyond an unclear statement about linked pages.

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

  Conciseness2/5

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

  The description is short but poorly structured and filled with unexplained jargon like 'succ · neg · bnot · flip <dimension> · jump ×k'. The opening phrase is somewhat concise, but the rest detracts from clarity and does not effectively front-load useful information.

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

  Completeness1/5

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

  The description omits essential context such as the return format, the meaning of the lattice moves, the relationship between parameters and the page, and any example usage. With no output schema and cryptic terminology, the tool is not sufficiently specified for reliable invocation.

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

  Parameters1/5

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

  The schema lists 'site' and 'slug' with no descriptions, and the tool description does not explain what these parameters mean or how they relate to the 'page'. Schema coverage is 0%, and the description provides no meaningful parameter semantics.

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

  Purpose2/5

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

  The description states the tool deals with 'linked pages (outgoing and backlinks) of a page', but it is phrased as a noun phrase rather than a clear action. The appended 'NAMED LATTICE MOVE' terminology is cryptic and does not clarify the tool's primary purpose or distinguish it from sibling tools like guide_search or guide_page.

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

  Usage Guidelines1/5

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

  There is no guidance on when to use this tool versus the sibling tools. The description does not mention alternatives, conditions, or scenarios, leaving the agent to infer usage solely from the tool name and vague description.

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

• sigil_renderC
  2.6/5.0
  Behavior3/5

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

  The description discloses that the tool returns an image, optionally writes to a file specified by 'out', and embeds the key in the PNG metadata (tEXt cityKey). These are important side effects, but there is no mention of read-only or destructive behavior, and the description uses cryptic language. Still, the side effects are stated.

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

  Conciseness2/5

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

  The description is a long, convoluted sentence with ambiguous jargon and poetic phrasing. It lacks clear structure and could be simplified. The essential information is embedded in cryptic language, making it hard to parse.

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

  Completeness1/5

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

  The description does not explain the tool's place among its siblings or when to prefer it over alternatives. No prerequisites, follow-up steps, or related tools are mentioned. The mention of importable URLs is tangential and not contextual.

  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?

  Only the 'key' parameter has a detailed description, covering multiple formats. The 'out' parameter has a brief description, and 'size' has no description, only constraints. With only 33% schema description coverage, the parameter semantics are insufficient.

  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 primary purpose of drawing a sigil from a key. The phrase 'Draw the key's sigil' directly indicates the action, though the details are cryptic.

  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 does not provide explicit guidance on when to use this tool. It mentions importability on certain URLs, but that does not constitute a usage guideline. No conditions or scenarios are described.

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

• key_deriveC
  2.8/5.0
  Behavior2/5

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

  With no annotations, the description carries the full burden of explaining side effects, but it only mentions inputs, processing steps, and return values. It does not state whether the operation is read-only, whether file paths are read, or whether any state is modified.

  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 compact and uses a clear process arrow, with no redundant filler. However, the density of domain-specific terms makes it harder to parse, slightly reducing accessibility.

  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?

  The description mentions several outputs but leaves crucial context unexplained, such as what 'stamped κ' refers to, what 'prior' means, and how 'glyphs', 'lit vertices', and 'walked vertices' are defined. There is no output schema to fill these gaps.

  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 description for 'key' is detailed and useful, specifying accepted formats: JSON object, JSON string, sigil PNG as base64/data URL, or a path. This goes beyond basic type information and gives practical input guidance.

  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 conveys a derivation-and-comparison process, but it is heavily jargon-laden and does not clearly define key terms such as 'stamped κ', 'prior', or 'lit and walked vertices'. The purpose is inferable but not directly stated in plain language.

  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?

  No explicit guidance is given about when to use this tool versus sibling tools like key_verify, key_evolve, or compare_plain. The 'never trusted, only re-derived' rule hints at a principle, but it does not specify concrete use cases or selection criteria.

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

• compare_plainB
  3/5.0
  Behavior2/5

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

  No annotations are provided, so the description bears full responsibility for behavior. It reveals that the tool reads both keys and computes the intersection 'IN THE OPEN', implying a potentially insecure or development-only behavior. It also notes the tool is hidden under VTA_MODE=1. However, it lacks details on side effects, security implications, return values, or error conditions, leaving the agent with limited understanding of consequences.

  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 concise, consisting of two sentences that front-load the core operation and then add lifecycle context. It avoids unnecessary verbosity. However, the use of specialized jargon ('walked + lit vertices', 'PSI', 'Rung 3') slightly hampers immediate clarity but does not add bloat. Overall structure is efficient.

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

  Completeness3/5

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

  Given the tool's moderate complexity (two parameters, no output schema, no enums), the description provides sufficient context about its development-only nature and hidden status. It lacks information about the return format, possible outputs, or error scenarios, but these are absent from the schema as well. The cryptic terminology and lack of parameter mapping create gaps, but the basic usage context is present.

  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 description adds minimal parameter-specific meaning. It mentions 'two keys' but does not differentiate between parameters 'a' and 'b' or explain their roles. The schema itself provides identical generic descriptions for both parameters (JSON object, string, PNG, or path), so the description contributes nothing beyond the schema. The agent must guess which key is which or infer from the operation.

  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 states a specific action: comparing two keys and computing their intersection ('∩ of two keys'), with a parenthetical explaining the inputs ('walked + lit vertices, shared PSI elements'). It clearly identifies the resource (two keys) and the operation (computed by reading both). Some jargon remains cryptic, but the core purpose is recognizable and distinct from sibling tools like key_verify or card_verify.

  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 provides usage constraints: it is 'development only', mentions a future replacement (Rung 3 / DH-PSI), and notes it is hidden when VTA_MODE=1. This gives the agent explicit conditions for when not to use it, but it does not explicitly compare to sibling tools or state when to prefer this over alternatives like key_verify. The guidance is useful but not comprehensive.

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

• guide_pageA
  3.6/5.0
  Behavior3/5

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

  No annotations are present, so the description carries the burden. It lists returned content (text, weave, lattice vertex, PSI element, public URL), suggesting read-only behavior, but does not explicitly confirm side effects 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.

  Conciseness5/5

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

  Single compact sentence conveys the tool's purpose, key parameter guidance, and return contents without unnecessary words.

  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 page-retrieval tool, the description is adequately complete: it names the resource, parameters, and output fields. It omits error scenarios, but these are not critical for basic usage.

  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 description clarifies that slug is the identity and site is optional, which partially compensates for the sparse schema. It does not explain the format or possible values for slug or site.

  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?

  Description clearly identifies the tool as retrieving a single page by slug and distinguishes it from search/neighbor tools by emphasizing the slug as the identity. Lacks an explicit verb like 'get' or 'fetch', but the intent is unmistakable.

  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?

  Gives useful guidance that the slug is the identity and site is optional, but does not explicitly state when to prefer this tool over sibling tools like guide_search or guide_neighbours.

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

• guide_searchA
  3.7/5.0
  Behavior5/5

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

  The description explicitly states 'reads the bake, never the live farm' and 'a walk is reproducible', indicating no side effects and deterministic behavior. This fully discloses the read-only, non-mutating nature of the operation.

  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 two sentences with the main purpose front-loaded. However, it includes several idiosyncratic terms (baked fedwiki, lattice vertex, PSI element) that add length and may obscure meaning, though they are likely domain-specific for this toolset.

  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?

  It describes the output structure (each step with site, slug, lattice vertex, PSI element) and the two-stage algorithm, giving the agent enough context to understand the result format. It does not cover edge cases or error behavior, but this is acceptable for the given complexity.

  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 33% (sites has a description, but query and limit do not). The tool description does not explain the meaning or expected format of any parameters, leaving parameter semantics under-specified.

  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 tool searches the guide and returns an ordered walk of pages, mentioning the data source (baked fedwiki federation), algorithm (BM25 + link-graph expansion), and output elements. This distinguishes it from page-level tools, though some jargon may reduce immediate clarity for a general agent.

  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?

  It implies a static snapshot ('reads the bake, never the live farm') and emphasizes reproducibility, but does not explicitly contrast with sibling tools like guide_neighbours or guide_page. The when-to-use decision is partially left to inference.

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

• key_evolveA
  3.7/5.0
  Behavior4/5

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

  Discloses key behavioral traits: pure and deterministic, UNSIGNED requiring a Swordsman at Rung 1, and the resulting key structure with walks[], prior, and fresh κ. No annotations are present, but the description covers the important behavioral constraints.

  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 compact, front-loaded with the action, and every sentence adds relevant information; no filler or redundant restatement.

  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?

  Covers input forms, the default-key path, output key evolution, and signing context. It omits details such as error handling and explanation of bake/κ, but is reasonably complete for a domain-specific 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?

  All three parameters have meaningful descriptions that extend the loose anyOf schemas, especially key (JSON/sigil/path) and walk (step forms). The semantics are enriched beyond the schema even if some domain terms remain terse.

  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 the operation: append a walk to a City Key, with a deterministic, pure outcome. It distinguishes itself by emphasizing UNSIGNED and default-key behavior, though it does not explicitly contrast sibling tools like key_derive.

  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?

  Provides operational details (walk forms, default key, unsigned status) but no explicit guidance on when to choose this over sibling tools such as key_derive, guide_search, or lattice_move.

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

• key_verifyA
  3.8/5.0
  Behavior4/5

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

  It discloses key behavioral facts: it verifies signatures, can bind the record to a provided key, evaluates a liveness predicate with since, and holds no secret. However, it does not describe return values, failure modes, or side effects beyond verification.

  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 dense but efficient, packing the action, formats, optional behaviors, and a safety note into a short space. The heavy use of domain jargon slightly reduces readability, but there is no obvious fluff.

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

  Completeness3/5

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

  The description is sufficient for basic use and for optional since/key behavior, but it omits the meaning of horizonDays, does not state the output/return contract, and does not clarify how this tool relates to card_verify or compare_plain. Given the 4-parameter complexity, these are meaningful gaps.

  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 description adds useful semantics for key binding and accepted vta formats, and explains since's role. However, horizonDays is left completely unexplained, and the key/vta formats remain jargon-heavy, leaving gaps in the parameter documentation.

  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 identifies the action as verifying a signed VTA record, optionally checking key binding and evaluating liveness. It names the specific resource and scope, distinguishing it from sibling verification, derivation, and rendering tools.

  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 gives conditional behavior for optional key and since parameters, but it does not explicitly state when to prefer key_verify over related tools such as card_verify, 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.

• card_verifyA
  3.9/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 states the operation is verification, lists return data, and notes the board never re-issues it, implying a read-only/non-mutating action. It does not detail error behavior, but 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.

  Conciseness4/5

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

  The description is compact and informative. The final sentence about mages.city adds context but is not strictly necessary for invocation, keeping it from a perfect score.

  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?

  It explains the verification algorithm, the participantId derivation, and the return fields, which is sufficient despite the lack of an output schema. It does not specify failure behavior, but that is less critical for a verify operation.

  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 single parameter is fully described in the schema with accepted formats (object, JSON text, or path). The tool description adds no additional semantic detail beyond referencing the card payload.

  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 the tool verifies an AgentCard, specifies the signature scheme (ed25519), and lists the returned identity fields. It is distinct from sibling key_verify by targeting AgentCard/ceremony identity verification.

  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 purpose implies when to use it (when an AgentCard needs verification), but it does not explicitly compare against sibling tools like key_verify or state conditions for choosing this tool.

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

• lattice_moveA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the transparency burden. It discloses the return payload (resulting vertex, six bits, dimensions, stratum, and a derived reading) and explains all operator behaviors. It does not mention side effects or error conditions, but the operation appears pure and well-specified.

  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 every sentence contributes: it lists operators, explains their effects, and lists the return fields. No filler or redundant phrasing. The structure flows logically from action to parameters to output.

  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?

  Given the simplicity of the tool and the absence of an output schema, the description covers the essential aspects: what it does, the operators, and the return format. It does not discuss edge cases like invalid 'op' values, but that is a minor gap for a well-defined lattice operation.

  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?

  The schema only lists 'op' with a brief enum-like description and 'vertex' with a min/max. The tool description adds rich semantics: it defines each operator's mathematical meaning (e.g., '+1 mod 64', '64−x', '63−x', bit flip) and clarifies the vertex range. This far exceeds the schema's minimal information.

  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: 'Apply a lattice operator to a vertex' and enumerates each operator with its exact semantics (succ, neg, bnot, flip, to). This is distinct from sibling tools like key_derive or guide_search, which serve different purposes.

  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 provides the exact syntax for the 'op' parameter and explains each operation, effectively teaching how to use the tool. However, it does not explicitly state when to prefer this tool over siblings, leaving the agent to infer from context.

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