decisionnode/DecisionNode

Tool Scores

• list_decisionsA
  3.7/5.0
  Behavior2/5

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

  No annotations are provided, placing full disclosure burden on the description. While 'List' implies read-only access, the description fails to specify return format, pagination behavior, sorting order, or performance implications of retrieving 'all' decisions. This leaves significant behavioral gaps for a data retrieval tool.

  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 well-structured sentences: first declares purpose, second declares usage context. No redundancy or filler. Information density is high with zero waste, and the description is appropriately front-loaded with the action verb.

  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?

  For a 2-parameter tool with simple flat schema and no output schema, the description adequately covers intent and usage scenarios. However, given the absence of annotations and output schema, it should ideally describe what the tool returns (e.g., full records vs summaries, data structure) and confirm read-only safety, which it omits.

  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%, with both 'project' and 'scope' parameters fully documented in the schema. The description mentions 'for the project' (aligning with the required parameter) but does not elaborate on the 'scope' filter capability or provide syntax examples beyond what the schema defines. Baseline 3 is appropriate given complete schema coverage.

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

  Purpose5/5

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

  The description clearly states the action ('List') and resource ('all recorded decisions') with specific scope ('for the project'). The verb 'List' and qualifier 'all' effectively distinguishes this from siblings: 'get_decision' (single retrieval), 'search_decisions' (filtered query), and 'add_decision' (creation).

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

  Usage Guidelines4/5

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

  Provides explicit positive guidance ('Use this when you need a complete overview... or when starting work on a new feature area'), giving clear context for appropriate use. Lacks explicit negative guidance or named alternatives (e.g., when to prefer 'search_decisions' over this), preventing a score of 5.

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

• get_decisionA
  4.2/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 specific content returned ('rationale and constraints') which hints at output structure, but lacks explicit statements about read-only safety, error handling for invalid IDs, or authentication 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?

  Two efficiently structured sentences with zero waste: the first states the core operation, the second provides the workflow context. Information is front-loaded and every word serves a specific purpose.

  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 lack of output schema, the description partially compensates by mentioning specific return content ('rationale and constraints'). It adequately covers the 2 parameters with 100% schema coverage and clarifies sibling relationships, though explicit error behavior would strengthen completeness.

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

  Parameters3/5

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

  The schema has 100% description coverage ('Decision ID', 'workspace folder name'), and the description references the ID parameter ('by ID') but does not add syntax details, format examples, or semantic context beyond what the schema already provides. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description uses a specific verb-resource pattern ('Get full details of a specific decision') and explicitly distinguishes from sibling tools by referencing search_decisions in the usage workflow, clarifying this is for ID-based retrieval versus searching.

  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 this after search_decisions returns relevant results') establishing the tool's position in a two-step workflow (search then get details), effectively guiding the agent away from using it as a primary discovery tool.

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

• add_decisionA
  4.3/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. It mentions persistence ('future context') and implies conflict detection exists (via the 'force' parameter reference to conflicts), but fails to explain the conflict resolution flow, idempotency, or what the tool returns when conflicts are detected. Adequate but incomplete for a write operation.

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

  Conciseness4/5

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

  Well-structured with bold front-loading ('Call this IMMEDIATELY'), followed by trigger phrases, numbered scenarios, and timing guidance. Every sentence serves a distinct purpose (triggers, scenarios, timing, content). Slightly verbose but no waste given the complexity of the triggering conditions.

  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 7-parameter schema with 100% coverage and no output schema, the description provides strong contextual completeness for when/why to invoke. Minor gap: could briefly acknowledge the conflict detection behavior implied by the 'force' parameter, though this is partially covered in the schema itself.

  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?

  While schema coverage is 100%, the description adds semantic value by mapping usage concepts to parameters: 'Focus on WHY' guides the rationale parameter, 'Clear statement' guides the decision parameter, and the trigger scenarios guide the scope parameter. This helps the agent understand not just what parameters exist, but how to populate them based on conversation context.

  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 explicitly states the tool captures/creates decisions when users express preferences or make technical choices, using specific trigger phrases ('Let's use...', 'Always do...'). It clearly distinguishes this creation tool from siblings (get_decision, list_decisions, search_decisions) which are retrieval operations.

  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?

  Excellent explicit guidance: lists specific trigger phrases, enumerates five concrete scenarios (design patterns, architectural choices, coding standards, UI/UX conventions, technology stack), specifies timing ('DURING the conversation, not after'), and content focus ('Focus on WHY, not just WHAT').

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

• search_decisionsA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, description carries full burden and successfully conveys the mandatory workflow gate behavior, consequences of skipping ('inconsistency and wasted rework'), and conditional logic based on results. Minor gap: does not describe return value structure despite no output schema being present.

  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 front-loaded with critical 'MANDATORY' warning. Structure flows logically: imperative -> triggers -> examples -> result handling. Slightly heavy on ALL CAPS emphasis and repetition ('ANY' appears multiple times), though justified given the tool's gatekeeper role in preventing rework.

  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?

  Comprehensive for a 3-parameter tool with no output schema. Covers workflow integration, cross-tool dependencies (list_projects), and result handling. Would benefit from brief mention of what the return value contains (e.g., 'returns matching decision records') to fully compensate for missing output schema.

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

  Parameters5/5

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

  Despite 100% schema description coverage (baseline 3), description adds substantial value: concrete query examples ('button styling', 'API design') and extraction logic for the 'project' parameter ('Extract this from the user's active file path'), plus cross-reference to list_projects. Exceeds baseline significantly.

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

  Purpose5/5

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

  Description explicitly states the tool checks for 'existing conventions' and 'decisions' before code changes. It clearly distinguishes from siblings (add_decision, get_decision, list_decisions) by emphasizing its search/query nature and mandatory pre-flight role in the 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?

  Provides explicit when-to-use with exhaustive trigger list ('add a feature, modify code, fix a bug...'), mandatory ordering ('Call this FIRST'), and clear alternative actions ('If no decisions exist, proceed freely; if decisions exist, FOLLOW them'). Also correctly references sibling tool list_projects as prerequisite when project is uncertain.

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