Server Quality Checklist

Tool Scores

• topos_assess_snapshotA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds context about blocked_by behavior for missing/expired snapshots, which is useful but not extensive. No contradictions with annotations.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the primary action, and contains no extraneous information. Every word contributes to understanding.

  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 the main action, the comparison baseline, and error case (blocked_by). However, it does not describe the output or the status semantics referenced from topos_assess_improvement, which would be helpful for a complete picture.

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

  Parameters3/5

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

  Schema description coverage is 100%; each parameter is described adequately in the schema. The description does not add further parameter-level detail, but that is not necessary given the schema's completeness.

  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 assesses a file against a baseline snapshot, referencing topos_begin_refactor for the baseline and topos_assess_improvement for status semantics. This uniquely identifies its role among siblings.

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

  Usage Guidelines3/5

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

  The description implies usage after topos_begin_refactor and mentions blocking for missing/expired snapshots, but does not explicitly state when to use this tool versus alternatives like topos_assess_worktree_change or topos_assess_changeset. No when-not-to guidance is provided.

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

• topos_begin_refactorA
  3.8/5.0
  Behavior1/5

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

  The description discloses that the only side effect is writing a snapshot record and that it returns a snapshot_id, but this contradicts the annotation idempotentHint=true. Writing a snapshot record implies each call creates a new side effect, so repeated calls would not be idempotent. This is an annotation contradiction.

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

  Conciseness5/5

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

  Three dense, front-loaded sentences: purpose plus side effect, return value plus follow-up workflow, and the specific usage condition. Every sentence earns its place with no 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 description covers purpose, side effect, return value, follow-up call, and the usage condition, which is quite complete for a 3-parameter tool with no output schema. However, the unresolved contradiction with idempotentHint leaves a behavioral gap around repeated calls.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already provides meaning for all three parameters. The description adds only the filepath context and the workflow but does not explain preferences or gitnexus_dir beyond what the schema states.

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

  Purpose5/5

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

  The description clearly states it persists the file's current source as a baseline snapshot before editing, with a specific verb and resource. It also distinguishes itself from siblings like topos_assess_snapshot by framing this as the initial step in a refactor workflow.

  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 provides a usage condition ('Use this when the baseline is not a committed git revision') and a concrete workflow: call this tool, edit the file, then call topos_assess_snapshot. This gives clear direction versus alternatives.

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

• topos_preference_walkA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds 'Pure and read-only (lattice math only; no files, no scoring),' which reinforces and expands the safety profile by explicitly ruling out file operations and scoring. This is useful context beyond the annotations. It also clarifies the effect of the 'current' parameter (truncates the walk to steps strictly above it), which helps predict behavior.

  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—three sentences that efficiently cover purpose, usage context, and output structure. It front-loads the core action in the first sentence, is free of filler, and every clause adds value. The structure is well organized for quick parsing by an agent.

  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?

  While there is no output schema, the description enumerates the result fields (walk, next_step, progress, aspirational_target/fallback_target, induced_order), which covers return-value essentials. The input schema is rich, including detailed enum definitions for LatticeElement. For a read-only lattice-math operation with one required parameter, this is sufficiently complete. It could be slightly richer on what 'relaxation walk' implies, but the existing context is strong.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents all three parameters (ranking, target, current) with clear descriptions. The tool description itself adds limited parameter-specific detail; it only mentions 'steps from target down to just above current' in the output, which indirectly references the 'current' parameter. Since the schema handles parameter semantics well, the baseline of 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 opens with a specific action and resource: 'Turn a generator ranking into a preference-ordered relaxation walk.' This clearly distinguishes it from siblings like topos_evaluate_code or topos_compare_files, which are evaluation/comparison tools. It also names the concrete output type (PreferenceWalkResult) and its key components.

  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 states when to use the tool: 'Call after an evaluation to pick the next verdict to aim for, or to relax the goal gracefully under a token/time budget.' This gives clear context. It does not explicitly mention alternatives or when-not-to-use, so it falls short of a 5, but the usage guidance is strong.

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

• topos_assess_changesetA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds extra behavioral context: 'Each file is compared to baseline_ref (new files have no baseline)' and mentions specific flags like 'complexity_relocated_within_file' and 'project_regression'. This goes beyond the annotations by describing the comparison behavior and result flags, though it omits details on security findings or authorization.

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

  Conciseness5/5

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

  The description is three sentences, tightly packed with essential information: purpose, usage, key behavior, flags, and return type. There is no fluff or repetition; every sentence serves a distinct role. It is front-loaded with the core action and immediately followed by practical guidance.

  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 tool's complexity (6 parameters, nested preferences object, no output schema), the description provides a solid overview: it explains the baseline comparison, flags, and return type. It lacks details on some parameters (e.g., `include_security_findings`) and the exact shape of `ChangesetResult`, but the schema covers most parameter semantics. The description is sufficient for an agent to decide when to use this tool and what to expect at a high level.

  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 67%, so the schema carries most parameter info. The description enhances `baseline_ref` by explaining that each file is compared to it and noting that new files have no baseline. This adds practical meaning beyond the schema's 'Git baseline ref each file is compared against.' However, it does not clarify undocumented parameters like `gitnexus_dir` or `include_security_findings`, but the description's contribution is still valuable.

  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 a specific verb and resource: 'Assess a multi-file changeset against a git baseline and roll the per-file verdicts into a project before/after.' This distinguishes it from sibling tools that focus on single files, improvements, or snapshots. The mention of 'multi-file changeset' and 'project before/after' adds a unique scope not seen in other tool names.

  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 gives explicit usage context: 'Use for a module split or any edit spanning several files.' This tells the agent when to select this tool, but it does not explicitly state when not to use it or name alternative tools for single-file assessments. The guidance is clear enough for basic selection but lacks exclusionary or comparative notes.

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

• topos_assess_worktree_changeA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavior: the baseline is read from git via git show with default HEAD, compared to the working-tree file, and the tool is stateless with no prior call needed.

  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 concise sentences, front-loaded with the core function and immediately followed by the alternative path. Every sentence earns its place, with no filler or tautological 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?

  For a 6-parameter tool with no output schema, the description provides essential selection context: what the tool does, how the baseline is sourced, and when to delegate to snapshot-based flows. It doesn't describe the output shape, but the assess verb and sibling context make the purpose and typical usage sufficiently clear.

  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 83%, so most parameters are already documented. The description adds context to baseline_ref by specifying the git show mechanism and default HEAD, and clarifies that filepath refers to the current working-tree file. This goes beyond the schema's brief field labels.

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

  Purpose5/5

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

  The description states a specific verb+resource: 'Assess an in-place edit against a git revision', and names it 'the common refactor loop'. It clearly distinguishes from sibling assess tools by emphasizing the git baseline vs working-tree comparison and explicitly directs untracked/new files to begin_refactor + assess_snapshot.

  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 when to use the tool ('the common refactor loop') and provides an explicit alternative for untracked/new files or uncommitted pre-edit baselines. It also notes that no prior call is required, which helps with session sequencing.

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

• topos_calculate_coverageA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds algorithm details ('UAST bipartite declaration matching and k-gram path recall') and states the return type ('CoverageResult'), going beyond the annotation baseline without contradicting it.

  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 focused sentences, front-loaded with the main purpose, followed by a usage caveat and technical summary. No redundant or filler content; every sentence adds value.

  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?

  With rich annotations and full schema coverage, the description is sufficient for tool selection and invocation. It even names the return type, though it does not elaborate on CoverageResult fields, which would be needed for full completeness given no 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 description coverage is 100%, so the input schema fully documents all parameters. The description references 'k-gram path recall' which gives slight extra meaning to the `k` parameter, but generally does not need to compensate for schema gaps.

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

  Purpose5/5

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

  The description states a specific verb ('measure') and resource ('test suite exercises its program-under-test via structural UAST coverage'), clearly distinguishing it from siblings by noting it is a standalone signal separate from the quality lattice and pointing to `topos_evaluate_*` for quality verdicts.

  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 says when to use this tool (as a standalone coverage signal) and when not to (when a quality verdict is needed, use `topos_evaluate_*` instead), providing clear context relative to alternatives.

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

• topos_depgraph_statusA
  4.4/5.0
  Behavior5/5

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

  Annotations already declare readOnly and idempotent hints, but the description adds valuable behavioral disclosure beyond that: 'Never shells out and never mutates state.' It also explains the failure modes (missing, stale, load/schema failure), which is not captured in annotations and helps the agent interpret the tool's behavior.

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

  Conciseness5/5

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

  The description is three sentences, front-loaded with the core purpose, and every sentence adds value: what it does, how it distinguishes outcomes, and safety guarantees. No filler or redundancy.

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

  Completeness4/5

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

  For a simple read-only status tool with no output schema, the description adequately covers purpose, failure modes, and next steps. It does not specify the exact return format, but given the simplicity and the 'what to do next' guidance, it is sufficiently complete for an agent to invoke it correctly.

  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% for both parameters, and each parameter already has a clear description in the schema. The tool description does not add additional parameter-level meaning, so the baseline of 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 states a specific verb ('Report') and resource ('.gitnexus' availability and freshness), and distinguishes it from sibling tools by focusing on status rather than generation or assessment. The read-only scope and the distinction between missing, stale, and failure states give precise purpose.

  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: check this before trusting COMPOSABLE, and it tells the agent what to do next based on the state. It doesn't explicitly name alternatives like topos_generate_depgraph, but the read-only nature and 'what to do next' provide clear contextual guidance.

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

• topos_generate_depgraphA
  4.4/5.0
  Behavior5/5

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

  Discloses side-effecting nature, the underlying `gitnexus analyze` command, conditional no-op behavior, and force regeneration. Annotations only provide generic hints (readOnlyHint=false, idempotentHint=false); the description adds meaningful behavioral context beyond those.

  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 purpose and side-effect. The second sentence efficiently explains no-op and force behavior. No wasted 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?

  Covers the tool's purpose, side effects, default behavior, and force parameter. No output schema exists, but for a side-effecting graph generation tool this is adequate for an agent to select and invoke correctly.

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

  Parameters3/5

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

  Schema coverage is 100% and every parameter (force, directory, gitnexus_dir) already has a clear description. The description restates force=true behavior but adds no new parameter semantics 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?

  Clearly states the specific action: generate the `.gitnexus` dependency graph via GitNexus. This distinguishes it from sibling tools like `topos_depgraph_status` (status check) and `topos_generate_graphify_graph` (different graph type).

  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: default behavior ensures the graph and no-ops when current, which implies when to use it (to guarantee graph existence). Does not explicitly name alternatives or exclusions, but the context is sufficient for selection.

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

• topos_refactorA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safe/advisory nature is expected. The description adds valuable context beyond annotations: it discloses engine-specific prerequisites (.gitnexus, Graphify graph), states the return type (RefactorResult with hotspots), and clarifies that it does not score the four pillars. It does not mention error behavior when prerequisites are missing, but that is a minor gap given the coverage.

  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 yet comprehensive: a one-sentence core purpose, a one-sentence differentiation, a concise enumeration of target engines with prerequisites, and a brief note on the return type. Every sentence carries information and there is no 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?

  For a tool with five parameters, two required, and several engine-specific prerequisites, the description covers the main purpose, alternatives, prerequisites, and return structure. It does not exhaustively document all edge cases (e.g., behavior without .gitnexus) but is sufficiently complete given the complexity and the lack 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 description coverage is 100%, so all parameters have detailed descriptions in the schema itself. The tool description restates some parameter guidance (e.g., which targets need .gitnexus) and adds the relationship between gitnexus_dir/graphify_dir and specific targets, but it does not significantly augment the schema. A baseline of 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 states the tool's function with a specific verb and resource: 'Rank structural refactor hotspots for one file'. It explicitly distinguishes itself from siblings by noting it does not score the four pillars and directing the reader to topos_evaluate_* and topos_assess_* for those purposes.

  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 on when to use this tool versus alternatives: it says to use topos_evaluate_* for medals and topos_assess_* to verify edits. It also mentions prerequisites for specific targets (e.g., dependencies/process need .gitnexus) and names topos_generate_graphify_graph as a prerequisite for graphify.

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

• topos_compare_codeA
  4.5/5.0
  Behavior4/5

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

  Annotations already provide readOnly, idempotent, non-destructive hints. Description adds 'parses both snippets in memory, never writes or scores,' which goes beyond annotations but is not extremely rich.

  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: purpose, behavior+usage, return value. All front-loaded, no wasted words.

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

  Completeness5/5

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

  For a tool with 3 simple and well-documented parameters and no output schema, the description covers purpose, usage, behavior, and return value completely.

  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 baseline is 3. The description repeats schema descriptions ('Baseline code.' and 'Proposed/target code.') without adding extra syntax or format details.

  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?

  States verb+resource clearly: 'Compute the AST distance between two source-code strings.' Distinguishes from siblings by noting that assess tools already fold it in, and this tool provides raw numbers for clone detection or refactor impact.

  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 says 'call it directly only for the raw number' and names alternatives (topos_assess_*), giving clear context on when to use vs. not use this tool.

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

• topos_compare_filesA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, which the description reinforces by stating 'Read-only; parses both files, never writes or scores.' Additionally, the description adds behavioral details like computing AST distance and returning a ComparisonResult, which go beyond annotations.

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

  Conciseness5/5

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

  The description is three sentences, front-loaded with the core purpose, followed by safety and usage guidance. Every sentence adds value without redundancy or fluff.

  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?

  The description covers purpose, safety, usage, and output (returns ComparisonResult, referencing `topos_compare_code`). Given the tool's moderate complexity and the presence of rich annotations, the description is complete for an agent to understand and invoke the tool correctly.

  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 input schema has 100% coverage with descriptions for both parameters ('Baseline file path.' and 'Comparison file path.'). The description does not add further semantics beyond what the schema provides, so a baseline score of 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 states the tool computes AST (tree-edit) distance between two source files. It specifies the verb 'compute' and resource 'AST distance', and distinguishes itself from sibling tools like `topos_assess_*` by stating it is for clone detection or refactor impact, not quality verdicts.

  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 explicitly says when to use: for clone detection or refactor impact. It also provides a clear alternative: use `topos_assess_*` for a quality verdict. This gives direct guidance on tool selection.

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

• topos_assess_improvementA
  4.6/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description doesn't need to repeat safety profile. It adds value by explaining the tool is read-only in its own words, describes the return shape (AssessmentResult with status and deltas), and clarifies the side-by-side variant context. No contradiction with annotations, and it provides useful behavioral context beyond the structured fields.

  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, no fluff. The first sentence states the core action, the second gives alternatives, and the third ties to specific parameters and return type. Highly front-loaded and every sentence earns its place.

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

  Completeness4/5

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

  With 9 parameters and no output schema, the description provides enough context for selection and invocation: it states the purpose, names the variant params, gives alternatives, and notes the return type. It doesn't detail every parameter, but the high schema coverage fills that gap. Missing details like the exact content of status values are not critical for tool selection/invocation.

  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 78%, which is high, so the schema already documents most parameters. The description goes beyond this by explicitly naming the key params for the variant input (proposed_code, proposed_filepath) and framing them as the defining use case. This adds semantic clarity that the schema alone does not convey.

  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 a specific verb+resource: 'Compare a baseline to a side-by-side proposed variant (read-only).' It clearly states what the tool does and distinguishes it from siblings by explicitly noting it is 'for variants supplied as proposed_code or proposed_filepath.' It also mentions the return type (AssessmentResult), reinforcing the tool's 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 provides explicit when-to-use and when-not-to-use guidance by naming alternatives: 'For normal edit-in-place loops, use topos_assess_worktree_change or snapshot first with topos_begin_refactor then topos_assess_snapshot.' This directly helps the agent choose between this tool and its siblings.

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

• topos_evaluate_fileA
  4.6/5.0
  Behavior5/5

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

  The description discloses key behavioral traits beyond annotations: it generates/refreshes .gitnexus when missing or stale, attaches a ModuleDependencyGraph, and handles GitNexus absence gracefully with coupling_available=false and warnings. This exceeds the general hints in annotations (readOnlyHint=false, idempotentHint=false) and adds actionable context.

  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?

  Three sentences deliver a dense but well-structured explanation. The purpose is front-loaded, side effects are in the second sentence, and failure handling in the third. It is slightly long but every sentence earns its place, with no 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?

  For a complex tool with 8 parameters, side effects, and dynamic generation, the description covers the essential behaviors: lattice scoring, .gitnexus generation conditions, side-effecting nature, and graceful fallback. It also mentions key output fields. Without an output schema, this is nearly 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 coverage is 100%, so the baseline is 3. The description adds value by explaining the relationship between no_composable and gitnexus_dir, the default behavior related to .gitnexus, and the output fields coupling_available/warnings, which gives context beyond the property descriptions.

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

  Purpose5/5

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

  The description clearly states the tool scores a file on disk on the SIMPLE/COMPOSABLE/SECURE/NAVIGABLE lattice, using a specific verb and resource. It also distinguishes itself from siblings by being 'the only evaluate tool that can reach COMPOSABLE', which separates it from other evaluate 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 gives clear context for when to use this tool (when COMPOSABLE evaluation or file-level scoring is needed) and implies alternatives via the sibling list. It explains side-effecting behavior and the no_composable escape hatch, but it does not explicitly name or exclude sibling tools.

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

• topos_evaluate_projectA
  4.6/5.0
  Behavior5/5

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

  Annotations already indicate readOnlyHint=false, but the description goes far beyond that: it discloses the specific side effect of generating/refreshing `.gitnexus`, the behavior of skipping unsupported files, the rollup taking the project-wide minimum, and the graceful degradation when generation is not possible (`coupling_available`/`warnings`). This is exactly the kind of contextual detail that helps an agent predict side effects.

  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 information-dense with five sentences, each addressing a distinct concern: main purpose, language autodetection, rollup semantics, return values/pagination, and side-effect behavior. It is front-loaded and free of filler, though the final sentence is long and packs multiple clauses. For a complex tool with 9 parameters, this density is warranted.

  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 output schema, the description compensates by explicitly naming the returned lists (`hard_fails`, `leaf_composable_zeros`, `maintainability_giants`) and describing the paginated per-file table with gate failures first. It also covers side effects, failure fallback, and parameter-triggered behavior. Together with the heavily documented schema, the description provides a complete operational picture.

  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 schema already documents each parameter. The description adds value by explaining how `no_composable` controls the .gitnexus generation workflow, how `limit`/`offset` drive pagination, and how `gitnexus_dir` relates to project-root behavior. This goes beyond the schema's per-parameter descriptions and links them to the overall execution model.

  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 a specific verb+resource+scope: 'Recursively score every supported source file in a directory' on the four-dimension lattice. It explicitly lists supported languages, notes autodetection with no language argument, and distinguishes itself from file-level evaluation by referencing `topos_evaluate_file`.

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

  Usage Guidelines4/5

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

  The description makes clear this is for whole-directory evaluation and even mentions `same as topos_evaluate_file` for .gitnexus generation, which implicitly contrasts it with the file tool. However, it never explicitly states when to use this vs a sibling (e.g., 'use topos_evaluate_file for a single file'), so the guidance remains implied rather than directly articulated.

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

• topos_evaluate_codeA
  4.7/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds key behavioral context: 'never writes or runs the code' and details what the return value is: 'an EvaluationResult: the lattice verdict (SLOP…IDEAL), per-generator scores, and a next-step agent contract.' It also explains the analytical scope (CFG/CPG/UAST) and the COMPOSABLE limitation.

  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 and front-loaded: starts with the primary action, then usage context, limitations with alternatives, and return value—all in three sentences with no redundancy.

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

  Completeness5/5

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

  With no output schema, the description explains the return contract. It covers when to use, what it does, what it cannot do (COMPOSABLE), and that it is read-only. For a 5-parameter tool, this is thorough and gives sufficient context for correct invocation.

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

  Parameters3/5

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

  Schema description coverage is 100%, so baseline is 3. The description does not add parameter-specific details beyond the schema; it only mentions 'raw code string' which corresponds to `code`. No additional semantics for `allow`, `verbose`, `language`, or `preferences` are provided, though the schema covers them.

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

  Purpose5/5

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

  The description states a specific verb and resource: 'Score a raw code string on the SIMPLE / SECURE / NAVIGABLE quality lattice.' It clearly distinguishes from siblings by noting 'a snippet not yet on disk' and explicitly stating COMPOSABLE is not reachable here, directing to `topos_evaluate_file` or `topos_evaluate_project`.

  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 guidance: 'Use for a snippet not yet on disk.' It also names alternatives for cases it cannot handle: 'for [COMPOSABLE] use `topos_evaluate_file` with `gitnexus_dir`, or `topos_evaluate_project` for a whole tree.'

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

• topos_get_docA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the output is Markdown and that the tool is a fallback for clients without resource fetching. It does not contradict annotations and provides useful behavioral context beyond the structured hints.

  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 plus a compact topic list. First sentence states purpose, second gives usage rationale, and the list is scannable with parenthetical explanations. No wasted words.

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

  Completeness5/5

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

  The tool is a simple read-only doc fetch with one parameter. The description covers the return format (Markdown), the precise when-to-use scenario, and enumerates all topics. Annotations handle the safety profile, so nothing is missing.

  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 the single 'topic' parameter 100% with enum definitions, but the description strengthens the semantics by explaining what each topic contains, e.g., 'agent-contract (compact loop contract, read first for refactors)'. This is meaningful enrichment beyond the enum values.

  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 'Return a Topos documentation page as Markdown,' a specific verb+resource statement that immediately disambiguates it from sibling tools (all focused on code analysis/refactoring). It clearly names the tool's function as documentation retrieval.

  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?

  Explicit guidance: 'Use when your MCP client does not expose resource fetching to the agent. Clients that do surface resources should prefer the equivalent resource URI for efficiency.' This directly states when to use the tool and when to prefer an alternative, which is exactly what usage guidelines should do.

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

• topos_generate_graphify_graphA
  4.9/5.0
  Behavior5/5

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

  The description enriches the annotations by explaining the side-effecting nature, the skip-if-existing behavior, and the independence from GitNexus. It aligns perfectly with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) and adds meaningful context beyond them, such as the force flag's effect and the tool's scope.

  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 yet information-dense: every sentence serves a purpose, from the main action, to usage guidance, to behavioral nuances, to alternative tools. It is front-loaded with the primary action and flows logically, with no redundant or filler content.

  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?

  For a side-effecting tool without an output schema, the description covers all essential aspects: what it does, when to use it, when to force regeneration, how it relates to other tools, and its independence from GitNexus. It is complete enough for an agent to select and invoke the tool correctly.

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

  Parameters4/5

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

  The schema already covers both parameters (100% coverage), so the baseline is 3. The description adds extra value by clarifying the behavior of `force=true` in the context of skipping regeneration, which provides semantic understanding beyond the schema's simple 'Regenerate even when current.' This lifts the score above 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?

  The description clearly states the tool's purpose: generating the Graphify knowledge graph at a specific path (`graphify-out/graph.json`) via an external CLI. It also distinguishes itself from the sibling tool `topos_generate_depgraph` by explicitly noting the difference, making the purpose unambiguous.

  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 usage context: 'Use before topos_refactor(target="graphify") when no graph exists' and also gives a direct alternative: 'For GitNexus dep graphs use topos_generate_depgraph instead.' This clearly tells the agent when and when not to use the tool.

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

• topos_inspect_codeA
  4.9/5.0
  Behavior5/5

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

  Annotations provide readOnlyHint=false, and the description goes further by disclosing the side-effecting nature: it 'generates/refreshes .gitnexus... so this tool is side-effecting.' It also clarifies reachable lattice elements for inline code and agreement with `topos_evaluate_file`, adding behavioral context beyond the annotations.

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

  Conciseness5/5

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

  The description is dense but well-structured: it front-loads the purpose, then covers usage, return shape, side effects, and mode differences. Every sentence contributes relevant information; there is no filler or redundancy for a tool of this complexity.

  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 (9 parameters, two modes, side effects, no output schema), the description covers the return value (InspectionResult), the behavioral difference between modes, the side-effect condition, and the alternative tools. Schema handles parameter details; description covers the behavioral and decision context completely.

  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 high (89%), so the baseline is 3. The description adds cross-parameter meaning by explaining the `code` vs `filepath` decision, the `no_composable` bypass, and the default `top_n_functions` behavior. It doesn't restate each parameter's schema but enriches the important choices.

  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 a specific verb+resource: 'Full metric breakdown for a single code unit (inline string or file).' It immediately distinguishes itself from siblings by stating 'use `topos_evaluate_*` when the medal alone is enough,' making the tool's unique role clear.

  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?

  Provides explicit when-to-use guidance: 'Use when you need the per-function detail behind a verdict' and names the alternative (`topos_evaluate_*`). It also states the exactly-one constraint for `code`/`filepath` and explains the side-effecting behavior with `filepath` versus inline `code`.

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