Server Quality Checklist

Tool Scores

• spike_synthesizeC
  2.9/5.0
  Behavior2/5

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

  No annotations provided, yet description fails to disclose critical behavioral traits: whether this is idempotent, what side effects occur (state changes, persistence), error conditions (missing branches), or mutation semantics beyond the word 'Create'.

  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?

  Efficient Google-style docstring format with clear separation between description and Args. No redundant text, though brevity comes at the cost of omitting workflow context that could aid agent decision-making.

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

  Completeness3/5

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

  Given existence of output schema, return values need not be described. However, for a complex workflow tool with 2 parameters and 0% schema coverage, the description lacks essential domain context (what constitutes a 'branch' in this system, relationship to ADR generation) necessary for correct invocation sequencing.

  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?

  With 0% schema description coverage, the Args section provides minimal compensation: identifies 'name' as referring to the Spike and 'synthesis_md' as Markdown content. However, lacks constraints (format conventions for spike names, length limits) or examples that would fully compensate for absent schema documentation.

  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?

  States specific verb (Create) and resource (synthesis document) with scope (comparing all explored branches). However, lacks explicit differentiation from siblings like spike_generate_adr or spike_complete_branch regarding when synthesis is appropriate versus other terminal actions.

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

  Usage Guidelines2/5

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

  No guidance on when to use this tool versus alternatives (spike_generate_adr, spike_complete_branch) or prerequisites (e.g., whether branches must be completed first). No mention of workflow position in the spike lifecycle.

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

• spike_get_stateB
  3.1/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 of behavioral disclosure. While 'Get' implies a read operation, the description fails to disclose error behavior (e.g., what happens if the spike name doesn't exist), whether the state is cached, or what the state object contains. The existence of an output schema mitigates some need for return value description, but safety and error characteristics are missing.

  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 appropriately brief and front-loaded with the core purpose. The Args section provides structured parameter documentation that is easy to parse, though the Python-docstring formatting is slightly informal for an MCP tool description.

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

  Completeness3/5

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

  Given the tool's simplicity (single required parameter, no nested objects) and the existence of an output schema, the description covers the minimum required information. However, it lacks guidance on error states or the nature of the returned state object, leaving minor gaps in contextual completeness.

  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% (the 'name' parameter has only a title, no description). The description compensates by documenting the parameter as 'Spike name', adding crucial domain context that identifies what the name refers to within the spike investigation system.

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

  Purpose4/5

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

  The description clearly states the action (Get) and resource (current state of a spike investigation). It implicitly distinguishes from sibling mutation tools (spike_create, spike_add_branch, etc.) through the 'Get' verb, though it doesn't explicitly state this distinction.

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

  Usage Guidelines2/5

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

  No explicit guidance on when to use this tool versus alternatives like spike_list (which likely lists all spikes) or when retrieval is appropriate versus other operations. The description states what it does but not the contextual trigger for selection.

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

• spike_listB
  3.1/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 only minimally hints at return format ('summary information'). It lacks disclosure on safety (read-only vs mutable), performance characteristics of listing 'all' items, or what specific fields the summary includes.

  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?

  Single sentence is appropriately front-loaded and wastes no words, though it borders on under-specification given the complex sibling ecosystem.

  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?

  Adequate for a zero-parameter list operation with existing output schema, but given the presence of spike_archive and spike_get_state siblings, it should clarify whether 'all' includes archived or completed investigations.

  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 with 100% schema coverage meets the baseline score of 4 per the rubric. No parameter description is necessary.

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

  Purpose4/5

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

  Clearly states the verb (List), resource (spike investigations), and scope (all with summary information). The mention of 'summary information' distinguishes it from sibling spike_get_state which likely retrieves detailed single-item state.

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

  Usage Guidelines2/5

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

  Provides no guidance on when to use this versus alternatives like spike_get_state, nor does it mention prerequisites, filtering limitations, or pagination behavior despite claiming to return 'all' investigations.

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

• spike_generate_adrB
  3.3/5.0
  Behavior3/5

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

  With no annotations provided, description carries full burden. It discloses internal logic ('Builds alternatives from challenged branches') and output action ('renders the ADR template'), but lacks critical safety information: whether this creates/persists records, modifies existing state, or returns ephemeral content. Output schema exists but description doesn't hint at return format.

  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 separation: purpose statement, behavioral details, then parameter dictionary. Docstring-style Args section is readable. No redundant sentences, though 'Args:' section header is slightly informal for MCP context.

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

  Completeness3/5

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

  Given 4 required parameters and complex workflow (16 sibling spike tools), description adequately covers core function and parameters. However, lacks workflow context necessary for this tool type: doesn't indicate whether this creates a draft for review (vs final ADR) or relationship to spike_approve_adr. Output schema exists, so return documentation isn't required in description.

  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?

  Despite 0% schema description coverage, the Args block provides clear semantic mapping: 'Spike name' distinguishes from 'ADR title', 'Context/background' and 'The decision being documented' clarify purpose. Compensates adequately for schema gaps, though doesn't specify formats or constraints.

  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?

  States specific action (Generate) and resource (Architecture Decision Record) with clear scope (from spike artifacts). Mentions 'challenged branches' which implicitly distinguishes from sibling tools like spike_synthesize, though it could explicitly clarify when to prefer this over spike_approve_adr.

  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?

  Only implies prerequisites through 'from spike artifacts' phrasing, suggesting spike data must exist first. No explicit when-to-use guidance, prerequisites, or comparison to alternatives like spike_synthesize or spike_approve_adr despite complex sibling ecosystem.

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

• spike_approve_adrB
  3.4/5.0
  Behavior3/5

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

  Discloses state transition ('transitions to COMPLETED status') and terminal nature. Given zero annotations, description carries full burden but omits mechanistic details: what 'approval' entails (file commit? status update?), irreversibility, and relationship to spike_rollback sibling.

  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 action and outcome in first sentence. Two follow-up sentences reinforce finality without excessive redundancy. Args section efficiently documents the single parameter. No significant bloat.

  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?

  Sufficient for a single-parameter state transition tool with output schema present. Covers core action and terminal state. However, given mutation nature and zero annotations, should specify prerequisite steps (ADR generation) and confirm irreversibility.

  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 0% (name property lacks description). Description compensates by documenting the parameter as 'Spike name' in Args section, providing basic semantics but lacking constraints (format, valid characters, existence requirements).

  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?

  Clear specific action ('Approve the ADR') and resource ('spike') with explicit outcome ('mark as completed'). Distinguishes from sibling spike_approve_meta by specifying 'ADR' versus meta-approval, and signals finality via 'final gate' language.

  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?

  Provides implied temporal context ('This is the final gate') suggesting use at workflow end. However, lacks explicit prerequisites (e.g., 'only after spike_generate_adr') or distinction from spike_complete_branch/spike_archive alternatives.

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

• spike_archiveB
  3.4/5.0
  Behavior3/5

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

  With no annotations, description carries full burden. 'Move to archive directory' clarifies the physical action (distinguishing from deletion), but lacks critical safety context: reversibility, whether references break, required permissions, or side effects on sibling operations like spike_list.

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

  Conciseness5/5

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

  Front-loaded purpose statement followed by Args block. Every sentence earns its place—no redundancy or generic fluff. Appropriate length for a single-parameter tool.

  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?

  Adequate for the mechanical operation (given output schema exists), but incomplete for the rich spike workflow ecosystem. With 15+ sibling tools, description should clarify archival's role in the lifecycle (e.g., final state vs. reversible). Parameter documentation saves it from being inadequate.

  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% (only title 'Name' with no description). Description compensates effectively by documenting 'name' as 'Spike name to archive', clarifying the parameter's semantic domain that the schema omits.

  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?

  Clear specific verb ('Archive') and resource ('spike investigation') with helpful parenthetical clarification ('move to archive directory') that distinguishes it from deletion. However, lacks explicit differentiation from sibling tools like spike_delete or spike_complete_branch.

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

  Usage Guidelines2/5

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

  Provides no guidance on when to archive vs. delete, complete, or mark as dead end. No mention of prerequisites or whether archived spikes can be restored. Agent must infer usage from the ecosystem context.

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

• spike_deleteA
  3.6/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full disclosure burden. It successfully indicates the operation is permanent (irreversible) and requires explicit confirmation. However, it lacks details on side effects (e.g., whether child branches/challenges from sibling tools are also deleted), authorization requirements, or undo mechanics.

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

  Conciseness4/5

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

  The description is front-loaded with the core action, followed by a clear Args section documenting parameters. Both sentences earn their place. Minor deduction for informal 'Args:' formatting instead of natural language integration, but overall efficient.

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

  Completeness3/5

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

  Given the output schema exists, return values need no description. However, for a destructive tool with multiple related siblings (branches, challenges, ADRs), the description lacks context on data integrity impacts and cascade behavior. It meets minimum viability but has clear gaps for a workflow-critical mutation 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?

  With 0% schema description coverage, the description compensates by documenting both parameters: 'name' explained as 'Spike name to delete' and 'confirm' with its requirement 'Must be True to confirm deletion'. It clarifies the semantic purpose of the confirmation flag (safety guard), though it could add format constraints or examples for the name.

  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 'Permanently delete a spike investigation' provides a specific verb (delete), resource (spike investigation), and scope (permanently). The permanence qualifier effectively distinguishes this from the sibling spike_archive tool, clarifying this is hard deletion versus archival.

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

  Usage Guidelines2/5

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

  No guidance provided on when to use this versus alternatives like spike_archive (soft delete) or spike_rollback. No mention of prerequisites or safety considerations beyond the confirmation parameter itself. The description does not help the agent decide between deletion and other lifecycle actions.

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

• spike_rollbackA
  3.6/5.0
  Behavior3/5

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

  No annotations provided, so description carries full burden. 'Restores the full state from the checkpoint snapshot' clarifies the replacement nature of the operation. However, lacks disclosure on reversibility, whether current uncheckpointed state is permanently lost, or permission requirements for this destructive-by-replacement action.

  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 plus Args block. Front-loaded with the action statement, followed by behavioral details, then parameters. Slightly awkward indentation in the Args section, but no wasted sentences. Appropriate length for a 2-parameter tool with output schema.

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

  Completeness3/5

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

  Given existence of output schema, description correctly omits return value details. However, for a state-mutating operation (rollback), missing safety context and sibling differentiation keeps this from being fully complete. Adequate baseline coverage for the parameter count but lacks operational warnings appropriate for restoration operations.

  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%, requiring description to compensate. The Args section provides semantic meaning for both parameters: 'name' is the 'Spike name' and 'checkpoint_id' is the 'Checkpoint ID to restore from'. This successfully maps the technical parameters to their domain concepts, though 'Spike name' could elaborate on whether this is the unique identifier.

  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?

  Specific verb 'Rollback' + resource 'spike' + scope 'to a previous checkpoint' clearly identifies the operation. Distinct from siblings like spike_checkpoint (create), spike_archive (archive), or spike_delete (remove) by focusing on restoration to a prior state.

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

  Usage Guidelines2/5

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

  No explicit guidance on when to use versus alternatives (e.g., spike_archive vs rollback), nor prerequisites mentioned (checkpoint must exist first). The word 'Rollback' implies usage context but lacks explicit when/when-not direction.

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

• spike_update_confidenceA
  3.6/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It discloses the 0-100 range constraint and implies persistence ('Record'), but omits details about side effects, idempotency, error conditions (e.g., non-existent spike), or storage behavior.

  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 purpose first, constraints second, and pseudo-docstring Args section efficiently covering parameters. No redundancy, though the Args list slightly lengthens the text it is necessary given zero schema descriptions.

  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 6 parameters with 0% schema coverage, the description adequately documents all inputs. With an output schema present, omitting return value explanation is acceptable. Missing only behavioral side-effects and explicit sibling differentiators.

  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% (only titles), requiring description to compensate. The Args section documents all 6 parameters with clear semantics (e.g., 'How well is the problem understood (0-100)'), fully compensating for the sparse schema though lacking rich examples or deep constraints.

  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 'Record[s] a confidence rating for the spike' with specific verb and resource. It distinguishes itself from sibling spike tools by focusing specifically on confidence metrics and evolution tracking.

  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 phrase 'Tracks confidence evolution over time' implies temporal usage (periodic reassessment), but lacks explicit guidance on when to use this versus alternatives like spike_checkpoint or spike_complete_branch, and doesn't state prerequisites.

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

• spike_checkpointA
  3.7/5.0
  Behavior3/5

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

  No annotations provided, so description carries full burden. Explains the core behavioral trait: checkpoints enable rollback to previous states. Missing operational details like: whether duplicate names overwrite existing checkpoints, persistence guarantees, or side effects on current state. Output schema exists, mitigating need to describe return values.

  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?

  Excellent structure: single-sentence purpose declaration, value proposition sentence, then Args block. Front-loaded with critical information. No redundant words. Appropriate length for 2-parameter tool.

  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?

  Adequate complexity coverage given 2 simple parameters and existence of output schema (no need to detail return values). Parameter semantics covered via Args section. Minor gap in workflow integration (relationship to `spike_rollback`), but sufficient for correct 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 coverage is 0% (no property descriptions), but the Args section compensates effectively by documenting both parameters: 'name' identifies the spike, 'label' is human-readable. Adds clear semantic meaning beyond the bare schema titles. Could improve by noting if name must be unique or referencing existing spike.

  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?

  Clear verb ('Create') and resource ('checkpoint of the current spike state'). Explains the checkpoint concept and its purpose (rollback). Distinguishes from general spike creation via 'spike state' terminology, though could more explicitly differentiate from sibling `spike_rollback` and `spike_create`.

  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?

  Provides implicit guidance by describing when checkpoints are valuable ('if exploration goes down an unproductive path'), indicating it should be used before risky changes. However, lacks explicit workflow guidance on when to use vs `spike_rollback` or prerequisites (e.g., requiring an active spike).

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

• spike_add_challengeA
  3.8/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 of behavioral disclosure. It successfully documents the critical workflow side effect: 'When all explored branches are challenged, the spike automatically advances to Phase 3 (synthesis).' It also explains the semantic purpose of challenges ('document failure modes, hidden assumptions, and edge cases'). Missing auth requirements or error behavior details, but covers the primary state-transition logic.

  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 efficiently structured with a clear purpose statement, conceptual explanation, workflow trigger, and necessary Args section. With 0% schema coverage, the Args block is essential and earns its place by documenting all three parameters. No redundant or wasted prose.

  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 workflow tool with complex state management (phases, branches, challenges), the description provides sufficient context: it explains the phase advancement trigger, documents all parameters (compensating for 0% schema coverage), and an output schema exists per context signals (relieving the description of return value documentation duties).

  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%, requiring the description to compensate fully. The Args section successfully documents all three parameters: 'name' is clarified as 'Spike name', 'branch_name' includes the critical constraint 'must be in EXPLORED status', and 'challenge_md' specifies 'Markdown content'. This adequately compensates for the schema's lack of descriptions.

  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 opens with a specific verb-object pair ('Add adversarial challenge') and identifies the target resource ('to a branch'). It distinguishes from siblings like spike_add_branch by focusing on 'adversarial challenge' documentation rather than branch creation. The second sentence clarifies what challenges represent (failure modes, assumptions, edge cases).

  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 includes usage constraints in the Args section ('must be in EXPLORED status'), providing a clear prerequisite. It also explains the workflow consequence (automatic advancement to Phase 3), which guides the user on the impact of the action. However, it lacks explicit comparison to siblings (e.g., when to challenge vs. complete_branch vs. mark_dead_end).

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

• spike_complete_branchA
  3.8/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively documents two important side effects: 'The findings markdown replaces the branch template content' and the automatic Phase 2 advancement trigger. It appropriately flags the destructive replacement behavior.

  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 follows a logical structure: purpose statement, behavioral details, then parameter documentation. It is appropriately sized with minimal redundancy, though the Args section formatting (Python-docstring style) is slightly informal compared to the main prose.

  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 has 3 required parameters, an output schema (which handles return value documentation), and stateful side effects, the description provides sufficient context. It covers the core action, side effects, and parameter meanings, though it could mention error cases (e.g., branch not found).

  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% (parameters lack descriptions in the JSON schema), but the Args section compensates by documenting all three parameters: 'Spike name', 'Branch to mark as explored', and 'Markdown content with exploration findings'. This successfully provides necessary semantics missing from the schema.

  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 'Mark[s] a branch as explored and record[s] findings' using specific verbs and domain terminology (branch, spike). However, it does not explicitly distinguish usage from the similar sibling tool 'spike_mark_dead_end', which also finalizes a branch but presumably without findings.

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

  Usage Guidelines3/5

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

  The description provides valuable workflow context that 'when enough branches are explored (>=3), the spike automatically advances to Phase 2 (adversarial)', helping the agent understand state changes. However, it lacks explicit guidance on when to use this vs. 'spike_mark_dead_end' or other completion alternatives.

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

• spike_add_branchA
  3.9/5.0
  Behavior3/5

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

  No annotations provided, so description carries full disclosure burden. Adds conceptual context that 'Branches represent distinct approaches' and phase constraints. Missing critical mutation details: idempotency, error handling for duplicate branch names, or 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?

  Three concise sentences followed by structured Args block. Front-loaded with purpose and phase constraints. Zero redundancy, though formal 'Args:' structure slightly deviates from conversational prose without reducing clarity.

  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?

  Output schema exists reducing need to document returns. All params documented. However, given complex workflow domain (phases, branches, spikes), lacks explanation of branch lifecycle, relationship to siblings like spike_complete_branch, or validation rules.

  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 has 0% description coverage. Description compensates via Args section documenting all 3 parameters: 'name' (Spike name), 'branch_name' (Filesystem-safe constraint), and 'description' (purpose). The 'Filesystem-safe' detail adds crucial constraint information absent from schema.

  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?

  Clear verb 'Register' with resource 'exploration branch' and domain context 'spike'. Implies operation on existing spike via 'for a spike' and the name parameter, distinguishing it from spike_create. Could explicitly state 'adds to existing spike' for absolute clarity.

  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 states valid phases 'Phase 0 (planning) or Phase 1 (divergent)' for usage timing. Missing explicit 'when not to use' (e.g., prohibited phases) or guidance on choosing between alternatives like spike_create.

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

• spike_approve_metaA
  3.9/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It successfully discloses the state transition behavior (Phase 0→1) and gating logic, but omits error handling (e.g., what happens if called when not in Phase 0), reversibility, or side effects beyond the phase change.

  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 distinct sentences: the action, the gate explanation, and the Args note. Information is front-loaded with the core purpose. The 'Args:' line is slightly informal/docstring-style but efficiently addresses the schema coverage gap without verbosity.

  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 presence of an output schema (not shown but indicated), the description correctly omits return value details. It adequately covers the Phase 0→1 transition logic for a workflow tool with one simple parameter. It could be strengthened by describing error conditions or Phase 1 characteristics.

  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 0% (the 'name' property lacks a description). The description compensates with 'Args: name: Spike name', which adds minimal but necessary semantic meaning. Given the single parameter and intuitive naming, this is sufficient but not exemplary.

  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 ('Approve meta-design and advance'), explicit resource ('spike'), and precise scope ('Phase 0 to Phase 1'). It clearly distinguishes from sibling spike_approve_adr by specifying this handles 'meta-design' approval versus ADR approval.

  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 second sentence explains the gate mechanism ('cannot proceed to divergent exploration until...'), establishing when to use it (before Phase 1 exploration) and the prerequisite state (problem framing approved). It lacks explicit mention of sibling alternatives but implies the workflow sequence clearly.

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

• spike_mark_dead_endA
  4.5/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully explains the side effects (exclusion from synthesis, preservation of documentation) and implicitly indicates this is a state-mutation operation. It lacks explicit mention of reversibility 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 follows an efficient three-part structure: purpose statement upfront, behavioral context in the middle, and parameter documentation at the end. No filler text; every sentence earns its place by providing non-structured context.

  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 presence of an output schema and the description's thorough coverage of parameters (compensating for 0% schema coverage) and behavioral effects, the documentation is complete for this tool's complexity. Minor enhancement would be mentioning relationship to spike_rollback or spike_archive.

  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 Args section fully compensates by documenting all 4 parameters with domain-specific semantics: 'Spike name' provides context for the name parameter, 'Branch to mark as dead end' clarifies intent, and 'Any insights salvageable' explains the optional salvageable field.

  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 specific action ('Mark a branch as a dead end') and scope. It distinguishes from siblings like spike_complete_branch or spike_synthesize by explaining that dead-end branches are 'excluded from synthesis,' establishing clear functional boundaries.

  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 clear contextual guidance through the consequence clause ('excluded from synthesis but their documentation is preserved'), which informs the agent when to invoke this tool versus completion alternatives. However, it does not explicitly name sibling alternatives (e.g., 'use spike_complete_branch for successful branches').

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

• spike_createA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden and successfully discloses side effects: it warns that it 'creates the directory structure' and 'generates the meta-design template.' It loses a point for omitting behavioral details like idempotency (what happens if the filesystem name already exists?) or permissions 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 follows an efficient structure: a one-sentence purpose summary, followed by implementation details ('Initializes... creates... generates'), and a structured Args block documenting the two undocumented schema parameters. Every sentence serves the agent's decision-making.

  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 0% schema coverage and lack of annotations, the description is remarkably complete. It covers the domain concept ('spike investigation'), lifecycle stage ('Phase 0'), side effects (filesystem/template generation), and fully documents both parameters. With an output schema present, it appropriately omits return value details.

  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 Args block richly compensates for the 0% schema description coverage. For 'name,' it adds critical filesystem validation rules ('alphanumeric, hyphens, underscores, max 64 chars') absent from the schema. For 'problem_statement,' it provides semantic meaning ('The problem this spike investigates').

  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 the specific action 'Create a new spike investigation' (verb + resource). It distinguishes itself from lifecycle siblings (e.g., spike_add_branch, spike_archive) by stating it 'Initializes' the spike and targets 'Phase 0', clearly marking it as the entry-point 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?

  The description provides clear contextual guidance by labeling this as the 'Phase 0' initialization step, implicitly positioning it as the first action in the spike workflow before tools like spike_add_branch. However, it lacks explicit negative guidance (e.g., 'do not use for existing spikes; use spike_get_state instead').

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