Server Quality Checklist

Tool Scores

• record_needB
  3.1/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 discloses that needs are first-class citizens that surface in recall and can be promoted. However, it omits details like side effects, authentication requirements, or idempotency.

  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 sentences long with no fluff. It is front-loaded with the action and efficiently conveys the core purpose.

  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 covers the core purpose and a bit of the lifecycle (recall, promotion). However, it lacks details on optional parameters, usage context, and return values (though output schema may cover the latter).

  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 0%, yet the description does not explain any parameters beyond the implicit 'content'. The optional 'why' and 'tags' parameters are not described, leaving the agent uninformed about their purpose.

  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 uses a specific verb-resource pair ('Record a NEED') and provides concrete examples. However, it does not explicitly distinguish this tool from siblings like 'capture' or 'generalize', which might overlap in functionality.

  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 explains what a need is but gives no guidance on when to use this tool versus alternatives. There are no when-not-to-use conditions or references to sibling tools.

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

• endorseB
  3.4/5.0
  Behavior2/5

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

  With no annotations, the description carries full burden but only explains the tool's role in promotions. Lacks disclosure of side effects, reversibility, permissions, or constraints beyond the promotion context.

  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?

  Two sentences with no waste; purpose is front-loaded. Every word earns its place, efficiently conveying the tool's unique value.

  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?

  While output schema exists so return values are covered, the description misses parameter semantics and behavioral details. Adequate but incomplete for a tool with no annotations.

  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?

  Schema description coverage is 0% and the description provides no explanation of 'item_id' or 'note' parameters. Fails to add meaning beyond the schema, leaving agents uninformed about required inputs.

  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 'vouch for an item' as the action, specifying it as the strong trust signal. Distinguishes from sibling tools like 'promote' and 'review_promotions' by explaining its role in promotion workflows.

  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 context on when endorsement is needed (required for team->org promotion, fast-tracks local->team). While it doesn't enumerate when not to use, the promotion flow guidance effectively signals appropriate usage.

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

• captureA
  3.9/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden but fails to disclose behavioral traits such as mutability, side effects, authentication needs, or persistence behavior. Mentioning 'LOCAL scope' hints at scope but does not clarify safety or limitations.

  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 well-structured with bullet-like lines for parameters after an initial clear statement. It is slightly verbose but every sentence adds value, making it efficient and easy to parse.

  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 tool has 6 parameters and an output schema (not shown), yet the description omits the return format or response behavior. It explains input well but lacks completeness about what the caller receives after execution.

  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 description coverage is 0%, but the description compensates fully by explaining each parameter's meaning: 'type' as memory|need|skill, 'kind' as note/decision/etc., 'why' as rationale, 'tags' as keywords, and 'valid_while' as dependency premise. This adds significant value beyond the raw 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 the tool saves a knowledge item to 'LOCAL scope' using a manual capture path, distinguishing it from the automatic sibling 'distill()'. The verb 'save' and resource 'knowledge item' are specific, and the scope is explicitly defined.

  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 guidance on when to use this tool ('manual capture path') vs. the alternative 'distill()' (automatic). It does not address other siblings like 'record_need' or 'recall', so it is not exhaustive but is clear enough for the primary distinction.

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

• distillA
  4.5/5.0
  Behavior5/5

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

  No annotations are provided, so the description carries full burden. It thoroughly discloses idempotent behavior, the release-time capture mechanism, and a residual gap where work might be lost. This level of transparency is exceptional.

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

  Conciseness3/5

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

  The description is quite long and packed with information, but it could be more concise. It uses paragraph structure rather than bullet points, which trades some clarity for detail. Still, 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 tool has no parameters and an output schema exists, the description covers behavior, limitations, use cases, and mechanisms thoroughly. It is complete and leaves little ambiguity.

  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 tool has zero parameters, and schema coverage is 100% trivially. The description does not need to add parameter information, and it provides extensive context beyond parameter semantics. Baseline for 0 params is 4.

  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 that distill turns completed work into knowledge, detailing two specific native substrates (agentsync and context-keeper). It distinguishes itself from sibling tools by focusing on automated capture from already completed tasks, unlike capture or generalize.

  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 guidance on when to use the tool (re-run freely, from session-end or post-commit hook) and explains the opt-in release-time capture. It does not explicitly state when not to use, but the context implies it's for automated knowledge capture, and the residual gap is noted.

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

• export_markdownA
  4.5/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 full burden. It discloses key behavioral traits: rendering process, mojibake normalization, and the publishing vs. return-only behavior for different scopes. However, it omits potential side effects like file overwriting or permission requirements.

  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 yet informative, using structured bullet points to organize information efficiently. Every sentence adds value, and the key action is front-loaded.

  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 simple single-parameter tool and the existence of an output schema, the description covers the main functionality and outcomes well. It lacks error handling details but is sufficient for the complexity.

  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 only parameter, 'scope', is thoroughly explained in the description with three valid values and their corresponding effects. Even though schema coverage is 0%, the description fully compensates by detailing each option and its default.

  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 renders knowledge to a human-readable markdown file, grouped by scope and project, with details per item. It distinguishes between scope='org' (publishes to repo) and other scopes (returns markdown without publishing), which differentiates it 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.

  Usage Guidelines4/5

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

  The description explicitly defines when to use each scope value, including default behavior. It provides clear context for usage but does not explicitly compare to sibling tools or state when not 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.

• review_promotionsA
  4.5/5.0
  Behavior4/5

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

  No annotations are provided, so the description must bear the full burden. It transparently explains the tool lists eligible items and opened PRs, implying a read-only action. It doesn't discuss auth or rate limits, but for a list tool this is adequate.

  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?

  Two sentences are front-loaded with a hook ('What's ready to move up?') and efficiently convey purpose and context. 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?

  With no parameters, an output schema (not shown but present), and clear description of three item categories and its role as a checkpoint, the description is fully complete for this 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?

  There are no parameters, and the schema coverage is 100% (trivially). The description doesn't need to add parameter meaning; a baseline of 4 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 states the tool lists items eligible for promotion at local, team, and org levels, acting as a checkpoint before promote(). It uses a specific verb 'lists' and resource 'items eligible', and differentiates from sibling tools like promote.

  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 says it's a 'human-readable checkpoint before running promote()', guiding when to use it. It could be improved by noting when not to use or alternatives, but the context is clear.

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

• generalizeA
  4.6/5.0
  Behavior5/5

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

  No annotations exist, so description must cover behavioral traits. It details write operations via CAS paths, PR batching, and side effects on KNOWLEDGE.md. Differentiates between org and team scope. No contradictions.

  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?

  Front-loaded with main purpose; parameter details follow. Some redundancy (e.g., 'in place' and 'rewrites one to its general form') but overall efficient. Minor wordiness does not harm clarity.

  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 annotations are absent and parameter count is 3, the description provides comprehensive context: usage, parameters, write behavior, and output side effects. Output schema exists, so return value details are not needed.

  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 description coverage is 0%, but description explains `org_content` (with default behavior) and `note`. `item_id` remains implicit but is required. Adds meaning beyond schema for two of three parameters.

  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: 'Restate an ALREADY-PROMOTED item's body as the cross-project rule' and distinguishes it from sibling tools like 'promote' by specifying it is the remediation counterpart of the org generalization gate.

  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?

  Explicitly describes when to use: for items listed under `org_needs_generalization` by `review_promotions()`. Provides context for `org_content` defaulting to the endorsement note. However, lacks explicit when-not-to-use or alternatives.

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

• promoteA
  4.6/5.0
  Behavior5/5

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

  No annotations are provided, so the description carries full burden. It thoroughly discloses all behavioral traits: promotion conditions, scope transitions, readership changes, the need for org_content for cross-project restatement, the fallback response (refusal with tells and suggested draft), and the effect of force and environment variables (CAMBIUM_ORG_PR). This is highly transparent.

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

  Conciseness3/5

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

  The description is lengthy and dense, containing multiple paragraphs with example scenarios and conditional logic. While it is well-organized and covers necessary details, it could be more concise. For instance, the first sentence 'Graduate knowledge up a scope as it earns trust — the compound-growth step.' is verbose. A tighter rewrite would improve score.

  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 complexity of the tool (multiple promotion paths, thresholds, environment variables, PR vs direct push, org_content requirement), the description covers every aspect. It explains the escalation process, failure modes, and side effects. An output schema exists but is not shown; the description references it indirectly (direct push vs pull request). No gaps remain.

  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?

  Schema description coverage is 0%, yet the description adds rich meaning to each parameter: force overrides conditions, item_id specifies the item, to_scope sets target scope, org_content provides the restated body. It explains how org_content becomes the org body and preserves original as 'example'. Without any schema help, the description fully compensates.

  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's purpose: graduate knowledge up a scope (local->team->org) as trust earns. It explains the verb 'promote' and the resource (knowledge items). However, the phrasing is somewhat convoluted (e.g., 'compound-growth step'), and it could be more straightforward. It distinguishes between usage without arguments (scan and promote all) and with item_id (single item). Siblings like 'generalize' or 'distill' are not explicitly differentiated, but the scope promotion is unique.

  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 when-to-use scenarios: with no arguments to promote all qualifying local items, with item_id to promote one level, and with to_scope to target org. It explains thresholds (recalls/endorsements) and when force is needed. It also covers failure modes (refusal when org_content is missing) and suggests alternatives (review promotions, force). The guidelines are comprehensive and actionable.

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

• recallA
  4.6/5.0
  Behavior5/5

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

  Even without annotations, the description transparently discloses side effects (recall counter increment, trust signal promotion) and response behavior (no_confident_match flag), providing critical behavioral 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.

  Conciseness4/5

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

  Description is front-loaded with purpose and well-structured across a few sentences, though it could be slightly more concise. Still efficient for the information provided.

  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 all key aspects: purpose, parameters, side effects, error behavior. Does not describe output schema, but output schema exists. Nearly complete for a search tool.

  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?

  With 0% schema description coverage, the description fully compensates by explaining 'scope' values (auto, local, team, org), 'limit' as max results, and defaults, adding essential meaning beyond the raw 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?

  Description explicitly states 'Search knowledge across scopes and return the best matches' and identifies it as 'THE read endpoint for every agent type', clearly distinguishing it from sibling tools that are write/management oriented.

  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 clarifies when to use the tool (read/search) by explaining scope options and limit, and implicitly contrasts with siblings like 'capture' or 'endorse'. Could be more explicit about when not to use, but adequate.

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

• import_memoryA
  4.7/5.0
  Behavior5/5

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

  With no annotations, description fully discloses all behavioral traits: read-only source, no network/auth, idempotency, deduplication by source ID or content hash, provenance stamping, and that imported items are not auto-promoted. No contradictions.

  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?

  Well-structured with clear sections, but slightly verbose. Front-loads purpose and constraints. Each sentence is valuable, but minor redundancy in parameter explanations could be trimmed.

  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?

  Covers all essential aspects: purpose, parameters, behavioral nuances, idempotency, provenance, and return format. Output schema exists, so return description is sufficient. Complete for its complexity.

  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?

  Schema coverage is 0%, but description compensates fully by defining each parameter: 'source' explains the 'json' adapter format and structure, 'path' specifies local file path. Adds critical meaning beyond 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?

  Explicitly states it ingests external memory exports as provenance-tagged items, distinguishing itself from sibling tools like 'capture' (native capture) and 'distill' (substrate reading). Clearly identifies it as an import/ingest-only, read-only operation.

  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 clear context: read-only on source, idempotent, no auto-promotion, and local file path only. Lacks explicit exclusion guidance or when to use alternatives like 'capture', but the context is sufficient for correct usage.

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

• setupA
  4.7/5.0
  Behavior5/5

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

  With no annotations, the description fully discloses behavioral details: validates paths, scaffolds a directory, writes config, env vars override, no restart needed, org_repo only suggests commands, never creates/pushes, and no secrets written.

  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 well-structured with a summary sentence followed by parameter details. It is informative without being overly verbose, though slightly lengthy.

  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, the description covers all necessary aspects: parameter behaviors, side effects, and constraints. It is complete for a setup tool.

  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?

  Schema description coverage is 0%, but the description provides detailed explanations for all 5 parameters, including their purpose, requiredness, and special behavior (e.g., org_repo offering commands if not cloned). This adds significant meaning beyond 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 that the tool 'finish[es] cambium's setup in one call' and enumerates specific actions like path validation, scaffolding .cambium/, and writing config. It distinguishes itself from sibling tools like status and capture by focusing on setup.

  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 implies usage when status or errors indicate incomplete setup, and explains optional parameters' behavior. However, it does not explicitly state when not to use it or mention alternatives.

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

• statusA
  4.7/5.0
  Behavior5/5

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

  No annotations provided, but description fully discloses behavior: never raises on missing config, reports config state, item counts, watermarks, and wired substrates. Transparent about what it does and does not do.

  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?

  Two sentences, front-loaded with key purpose, no wasted words. Every sentence provides essential information.

  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 zero parameters, no annotations, and presence of output schema, the description covers all needed context: purpose, output details, and behavior on missing config. Fully complete for a status 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?

  Zero parameters, schema coverage 100%. Description adds value by explaining what the tool accomplishes without needing parameters, exceeding the baseline.

  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?

  Description clearly states 'First thing to call' and returns structured config state, distinguishing it from siblings by positioning it as the initial diagnostic tool.

  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?

  Explicitly says 'First thing to call—especially when cambium looks broken' and notes it never raises on missing config, providing clear context. Lacks explicit when-not or alternative names but is strong overall.

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

• verify_entryA
  4.8/5.0
  Behavior5/5

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

  With no annotations, the description fully discloses behavior: it stamps 'last_verified' to now, supports an optional note, works on local and team entries, and does not automatically downgrade when stale. This covers all relevant behavioral traits.

  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-5 sentences) and front-loaded with the core action. Every sentence adds distinct value: purpose, rationale, optional note, behavioral nuance, and scope. No redundant or vague statements.

  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 description covers purpose, usage, behavior, and scope well. For a simple tool with 2 params and no annotations, it is nearly complete. It does not describe the return value (output schema exists but not mentioned), which is a minor gap.

  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 0%, but the description adds meaning: 'note' is documented as optional record, 'item_id' is implied to identify entries, and scope ('local and team') is provided. It lacks explicit format or constraints for 'item_id', but still adds value.

  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 uses specific verbs ('Confirm', 'stamp') and clearly identifies the resource ('knowledge entry'). It distinguishes this tool from siblings like 'stale_report' and 'promote' by explaining the verification role.

  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 explains when to use this tool (after promotion, to prevent staleness) and explicitly points to 'stale_report' for finding stale entries. It also clarifies that verification does not automatically downgrade, providing clear usage context.

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

• stale_reportA
  5/5.0
  Behavior5/5

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

  No annotations provided, but the description fully discloses behavior: sorting order, flagging of never-reverified entries, surfacing of valid_while premises, and the event-driven nature. No contradictions.

  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 well-structured, starting with a question to introduce purpose, then explaining output, parameters, and behavioral notes. 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?

  Given the existence of an output schema, the description covers all necessary aspects: purpose, parameters, behavioral traits, and differentiation from siblings. It is complete and informative.

  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?

  Despite 0% schema description coverage, the description explains both parameters in detail: project for limiting to one project (default all) and older_than_days for age filter (0 means no filter, includes never-verified). Defaults and behavior are clear.

  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 promoted knowledge that might be stale, sorted oldest-first, with flagged never-reverified entries and surfaced valid_while premises. It distinguishes itself from siblings like verify_entry.

  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 explicitly states it is event-driven and not clock-driven, advises against using it for decaying confidence scores, and directs to verify_entry for re-confirmation. It also mentions that promotion counts as verification.

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