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

With no annotations provided, the description must disclose behavioral traits. It mentions returning an auto-generated plan with intent, risk level, and suggested specs, but does not specify whether the tool has side effects (e.g., reads vs writes), required permissions, or idempotency. The output description is partial.

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

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

The description is two sentences, front-loads the action and output, and contains no fluff. Every sentence contributes directly to understanding the tool's purpose and output.

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

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

Given 5 parameters, no output schema, and no annotations, the description gives a high-level overview of the output but lacks details on expected return format, constraints, or prerequisites. It is adequate but not thorough.

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

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 no additional meaning beyond what the schema provides for each parameter; it restates 'git diff' and 'Repository' but does not enrich the understanding of format or usage.

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

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

The description clearly states the tool analyzes a git diff and auto-generates an EditPlan. It uses a specific verb ('Analyze') and resource ('git diff'), and the output is explicitly defined. The context of enabling continuous SDD distinguishes it from siblings like turingmind_apply_edit or turingmind_get_edit_reasoning.

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

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

The description implies usage when a diff is available and a plan is needed, stating 'where plans are inferred from changes rather than requiring upfront planning.' However, it lacks explicit when-not-to-use guidance or references to alternative tools for scenarios like already having a plan.

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

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

With no annotations, the description carries the full burden. It discloses that reasoning capture is mandatory and becomes part of a permanent audit trail, adding value by warning about irreversibility of recording. However, it does not mention other behavioral aspects like authentication requirements or side effects of edits.

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

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

The description is concise with three short sentences, each serving a distinct purpose: stating the action, providing usage guidance, and highlighting the audit trail. No wasted words.

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

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

Given the tool's complexity (10 parameters, no output schema), the description is too brief. It explains the reasoning requirement but does not cover return behavior or how to use multiple parameters, making it only partially complete.

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

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

Schema coverage is 100%, so all parameters have descriptions in the schema. The description itself adds no additional explanation for parameters, resulting in baseline score of 3 per guidelines.

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

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

The description clearly states 'Apply code changes' with a specific verb and resource, and emphasizes mandatory reasoning capture. However, it does not differentiate from sibling tools like turingmind_apply_fix, which may have similar functionality.

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

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

The description says 'Use this for ALL file edits', providing clear context for when to use the tool. However, it lacks explicit guidance on when not to use it or alternatives, nor does it mention prerequisites for file edits.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool resets the node stage and triggers re-verification, implying mutability. It does not mention side effects, idempotency, authorization needs, or what happens on multiple calls, which would be valuable for safe usage.

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

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

The description is extremely concise, consisting of three short sentences. The first sentence states the purpose, the second explains the effect, and the third provides usage timing. There is no redundant information, and the key points are front-loaded.

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

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

Given the complexity of three required parameters and no output schema, the description is incomplete. It lacks explanations of how to obtain 'node_id', the exact enum values for 'fix_type', and details about the return value or confirmation. Important edge cases like duplicate calls or error conditions are not addressed.

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

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

Schema description coverage is low (33%), with only the 'description' parameter having a schema description. The tool description adds some context by giving examples of fix types ('code patch, test expansion, spec refinement') but does not cover the full enum, and it does not explain 'node_id' or the exact enum values like 'unblock_dependency'. Thus, it adds limited value beyond the schema.

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

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

The description clearly states it records a repair action applied to a failed SpecNode and resets the node stage. The verb 'record' and the specific resource 'SpecNode' provide a clear purpose. However, it does not explicitly distinguish from sibling tools like 'turingmind_apply_edit' or 'turingmind_apply_spec_delta', which might be confused with applying fixes directly.

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

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

The description explicitly says 'Must be called after the repair action', giving clear context on when to use. However, it does not mention when not to use the tool or suggest alternative tools for different scenarios, leaving some guidance gap.

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

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

With no annotations, the description discloses critical side effects: all dependent nodes are reset and placed in ready_queue for regeneration. This fully informs the agent of the tool's impact.

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

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

Two concise sentences with the most important information front-loaded. No wasted words.

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

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

Describes the primary effect and usage context. Lacks mention of return values or error conditions, but given no output schema and clear description, it is nearly complete.

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

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

Schema coverage is 100%, so description adds no extra parameter detail beyond the schema. The description's mention of 'partial contract update' is vague but acceptable at baseline.

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

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

Clearly states the action (apply contract change) and the unique effect (trigger automatic downstream invalidation). Distinguishes from sibling tools like update_spec_node which may not have cascading invalidation.

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

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

Explicitly tells when to use ('whenever a requirement changes') and implies guarantee of correctness. Does not mention when not to use or alternative tools, but context is sufficient.

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

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

No annotations are provided, so the description carries full burden. It discloses that nodes are created with blank contracts, skips excluded directories automatically, and supports dry-run preview. It does not mention idempotency, overwriting behavior, or error handling for missing paths, leaving some gaps.

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

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

The description is three sentences long, front-loaded with the core action, and every sentence adds value. It is concise and well-structured.

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

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

With no output schema and 5 fully described parameters, the description is fairly complete. It could mention return values or post-creation effects, but for a bootstrap tool with clear side effects (creating nodes), the provided information is sufficient.

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

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 adds minimal value beyond schema: it suggests dry_run usage and notes automatic skipping of excluded dirs. It does not elaborate on repo or project_path beyond what's in the schema.

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

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

The description clearly states the tool scans a project directory and auto-creates L2 SpecNodes for each module group. It uses a specific verb ('scan' and 'auto-create') and identifies the resource ('existing project directory' and 'L2 SpecNodes'), distinguishing it from sibling tools like turingmind_create_spec_node or turingmind_index_codebase.

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

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

The description advises using dry_run=true first to preview without writing to the DB, offering clear guidance for safe usage. However, it does not explicitly mention when to avoid this tool or which alternative to choose, though the context implies it's for initial bootstrapping.

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

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

With no annotations, the description carries the burden. It declares the tool is 'deterministic' and lists the outputs per classification. It does not cover error cases or idempotency, but the core behavior is transparent.

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

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

The description is extremely concise, front-loading the core purpose and using a clear bullet-like format. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (4 params, enum, no output schema), the description covers the classifications and their actions well. It assumes domain knowledge of SpecNode but otherwise is sufficiently complete for correct tool invocation.

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

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

Schema coverage is 50% (descriptions for evidence and failure_trace). The description adds meaning for 'classification' by explaining the enum values, but node_id and evidence lack additional context beyond what is in the schema.

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

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

The description clearly states the tool classifies a SpecNode failure deterministically, listing the four exact classifications and their meanings. This distinguishes it from sibling tools like 'detect_conflicts' or 'analyze_diff'.

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

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

The description provides explicit when-not instructions ('Do NOT guess') and defines each classification's action (escalate to Architect/Tester/Builder Mode, block node). However, it does not compare directly to other sibling tools for alternative use cases.

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

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

No annotations are provided, so the description carries full burden. It lacks disclosure of important behaviors such as whether the tool is idempotent, what happens if node_id already exists, or any authentication/permission requirements. The description only states the high-level purpose without behavioral details.

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

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

The description is extremely concise with two sentences: the first states the primary function, and the second adds context and restrictions. Every word is purposeful with no fluff, making it easy to parse quickly.

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

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

Given the complexity (11 parameters, nested objects, no output schema), the description is missing expected return value info and error handling semantics. For a creation tool, it would be helpful to know if it returns the created node or a confirmation. However, the description is adequate for a basic CRUD tool.

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

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

Schema coverage is high (91%), and the schema descriptions already explain most parameters. The description reinforces the concept of 'strict contract' and 'surface_type' but adds no new semantic meaning beyond what is in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool creates an atomic SpecNode in the constraint DAG, distinguishes it from siblings like update or list, and specifies the 'Architect Mode only' context. The verb 'create' and resource 'SpecNode' are specific and unambiguous.

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

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

The description explicitly restricts usage to 'Architect Mode only' and clarifies not to write code but only define constraints. While it doesn't provide explicit when-not-to-use compared to siblings, the context is clear enough for an AI agent to differentiate.

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

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

With no annotations, the description carries full burden. It discloses two behaviors (delete removes completely, deprecate preserves history) but lacks details on side effects, reversibility, or impact on other data.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core functionality.

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

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

Given the tool's moderate complexity (two actions) and no output schema, the description adequately explains the action types but omits consequences of each action and system-level impacts. More context on behavioral effects would improve completeness.

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

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

Schema coverage is 100%, but the description adds value by elaborating on the 'action' parameter's enum values, clarifying that deprecation preserves history while deletion does not. This goes beyond the schema's minimal description.

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

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

The description clearly states the tool's function: deleting or deprecating a memory entry, and distinguishes between the two actions. It is distinct from sibling tools like save, get, list memory.

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

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

The description explains the difference between delete and deprecate but does not provide explicit guidance on when to use each or mention alternatives. The usage context is implied but not fully articulated.

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

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

No annotations are present, so the description must fully disclose behavior. It only lists detection types (contradictions, overlaps, scope conflicts) but omits output format, side effects, or prerequisites.

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

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

Two concise sentences, no superfluous text, front-loaded with key action.

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

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

Missing output schema and lacking details on conflict definitions, result format, or any side effects, making it incomplete for an agent to use effectively.

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

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

Schema coverage is 100% with clear parameter descriptions. The tool description adds no additional parameter meaning beyond the schema.

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

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

The description clearly states the tool detects conflicts (contradictions, overlaps, scope conflicts) between memory entries. It distinguishes from siblings like turingmind_resolve_conflict.

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

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

The description provides no guidance on when to use this tool versus alternatives like turingmind_resolve_conflict or other analysis tools.

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

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

Discloses that it does not write application code, and explains behavior when test_dir is omitted (stubs recorded in DB only). No annotations provided, so description carries burden; sufficiently transparent.

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

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

Two sentences plus a warning, front-loaded with purpose, no wasted words.

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

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

Covers main behavior, side effects, and limitations. Lacks mention of prerequisite that SpecNode must exist, but overall adequate given no output schema.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds context about translation but no additional parameter-specific details beyond schema.

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

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

Clearly states verb 'generate', resource 'verification suite for a SpecNode', and details translations from contract elements. Distinguishes from sibling tools like turingmind_run_verification.

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

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

Provides a negative guideline ('Do NOT write application code'), but lacks explicit when-to-use vs alternatives. Implies it's for test generation only, but could be more specific.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It describes what the tool returns but does not mention side effects, authentication, rate limits, or error handling. For a read-only tool, this is adequate but not rich.

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

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

The description is a single sentence, front-loaded with the action and key details. Every word earns its place with no redundancy.

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

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

For a simple retrieval tool with one parameter, the description covers the purpose and return content. It does not mention response format or prerequisites, but given no output schema, this is still fairly complete.

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

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

Schema coverage is 100% with one parameter (plan_id described as 'EditPlan ID'). The description adds no additional meaning beyond the schema. Baseline is 3, and no value is added.

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

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

The description clearly states the tool retrieves a full audit trail for a TDD cycle, specifying it returns reasoning, specs, tests, and edits with traceability. This specific verb+resource distinguishes it from siblings like turingmind_get_edit_reasoning, which likely returns a subset.

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

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

The description implies usage when a comprehensive audit trail is needed but does not explicitly state when not to use it or mention alternatives like turingmind_get_edit_reasoning. No when-not or exclusion criteria are provided.

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

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

With no annotations, the description adequately covers behavior: it returns a list of high-priority gaps sorted by blast radius severity, with examples. It could further detail the sorting mechanism, but it's sufficient.

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

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

The description is concise (three sentences) and front-loaded with purpose. Each sentence adds value: defines output, usage, and specifics of output. No unnecessary content.

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

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

For a simple read tool with 2 params and no output schema, the description is mostly complete. It explains what is returned and when to use it, though it could mention pagination or limit behavior explicitly.

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

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 does not add any parameter-specific details beyond what the schema already provides (repo and limit).

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

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

The description clearly states the tool provides a prioritized Action Item queue, specifies its purpose (deciding next work), and distinguishes it from siblings by focusing on gaps sorted by blast radius severity.

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

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

The description explicitly says to call this tool to figure out next work, providing clear context. However, it does not mention when not to use it or compare with alternatives like get_ready_nodes, so it's not a full 5.

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

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

No annotations are provided, so the description carries full burden. It discloses that reasoning can be extracted from commit messages or via user prompting (interactive parameter). However, it does not explain what 'capture' means in terms of state changes or side effects, nor does it cover permission requirements or error scenarios. The description is adequate but not fully transparent.

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

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

The description is four sentences long, front-loaded with the core purpose in the first sentence. Each subsequent sentence adds a distinct point: extraction methods, per-file support, and benefit. No wasted words.

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

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, 2 required, no output schema), the description covers main behaviors: getting reasoning from commits or prompts, per-file support, historical lookups (commit_hash), and interactive prompting. It does not explain return format or error conditions, but those are somewhat acceptable without an output schema. A small gap is lack of clarity on 'capture' semantics.

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

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

Schema coverage is 100%, so the input schema already documents all 6 parameters. The description reinforces that per-file reasoning is supported and mentions extraction from commit messages and prompting, but it adds minimal new meaning beyond the schema. Baseline 3 with marginal added value.

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

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

The description clearly states the verb-resource pair: 'Get or capture developer reasoning for file changes.' It specifies the action (get/capture) and target (reasoning for file changes). It also provides distinguishing context with 'Supports per-file reasoning' and 'Helps code review understand intent,' which helps differentiate from sibling tools like turingmind_log_reasoning.

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

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

The description implies usage during code review ('Helps code review understand intent') but does not explicitly state when to use this tool versus alternatives like turingmind_log_reasoning. It lacks explicit when-not or prerequisite conditions. While some context is provided, it falls short of full guidance.

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

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

No annotations are provided, so the description carries full burden. It discloses a read-only operation (get) and specifies returned fields, but omits any behavioral aspects like idempotency, potential costs, 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.

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

The description is very concise (two sentences, 29 words) and front-loaded with the main action. However, the omission of parameter documentation is a structural gap that could have been included.

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

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

Given the tool has one parameter and no output schema, the description fails to fully enable correct invocation. The critical 'repo' parameter is undocumented, making the tool difficult to use without external knowledge.

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

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

The schema has one required parameter (repo) with 0% schema description coverage. The tool description does not mention the parameter at all, leaving the agent with no guidance on its meaning or valid values.

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

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

The description clearly states it retrieves global control plane state including ready_queue, blocked_queue, failed_nodes, and confidence metrics. This distinguishes it from sibling getter tools like get_ready_nodes, which focus on specific parts.

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

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

The description notes that the UI polls this tool to render specific visual elements, implying appropriate usage for periodic polling. However, it does not explicitly contrast usage with other tools or state when not to use it.

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

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

No annotations are provided, so the description must carry full burden. It explains the computation (transitive dependencies) and implies read-only behavior, but lacks details on side effects, output format, or whether repeated calls are safe.

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

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

Two sentences, front-loaded with core functionality, no redundant information. Every word earns its place.

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

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

Given a single parameter, no output schema, and no annotations, the description covers the tool's purpose, usage timing, and core logic. It could be improved by specifying the return type (e.g., list of node IDs) but is otherwise adequate.

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

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 does not add significant meaning beyond the schema's 'Origin node' description; the tool's purpose is already clear from context.

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

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

The description uses specific verbs and resources ('Compute the exact blast radius', 'all downstream nodes in the DAG') and clearly distinguishes from sibling tools like turingmind_apply_edit or turingmind_analyze_diff by focusing on impact preview.

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

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

The description explicitly tells when to use: 'Use BEFORE applying a spec change to preview impact'. It provides clear context but does not explicitly exclude use cases or mention alternatives among siblings.

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

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

No annotations are provided, so the description carries full burden. It states it 'gets' information and includes 'evidence', implying read behavior. However, it does not disclose if any side effects occur, required permissions, or whether the evidence is fetched from storage or computed. This is adequate but lacks depth.

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

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

The description is a single sentence that immediately conveys the tool's purpose and key detail ('including evidence'). No extraneous words, making it highly efficient.

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

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

Given the tool's simplicity (2 parameters, no output schema, no annotations), the description adequately covers the purpose. Some might desire more detail on what 'detailed information' entails, but it is mostly complete for a retrieval tool.

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

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

Schema description coverage is 100% (both 'repo' and 'memory_id' have complete descriptions). The tool description adds no additional meaning beyond the schema, so baseline of 3 applies.

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

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

The description clearly states the action 'Get' and the resource 'specific memory entry' with the detail 'including evidence'. This distinguishes it from sibling tools like turingmind_save_memory and turingmind_delete_memory, which are write operations, and turingmind_list_memory, which lists entries.

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

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

No guidance is provided on when to use this tool versus alternatives, such as turingmind_list_memory which retrieves a list, or when not to use it. There are no prerequisites or context for usage beyond the basic description.

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

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

No annotations provided, and the description does not explicitly state behavioral traits like read-only, permission requirements, or rate limits. It implies a read operation but lacks disclosure beyond that.

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

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

A single sentence that conveys the purpose and return value without extraneous words. Perfectly concise.

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

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

For a simple tool with one parameter and no output schema, the description adequately covers the purpose and basic returns. Lacks detail on 'basic architecture info' but sufficient for a straightforward retrieval tool.

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

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

Schema coverage is 100% for the single parameter 'repo'. The description adds no additional meaning beyond the schema's description. Baseline of 3 is appropriate.

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

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

The description clearly states 'Get comprehensive project structure summary' with specific return items (language distribution, entity type counts, basic architecture info). It is distinct from sibling tools like turingmind_index_codebase, though it does not explicitly differentiate.

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

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

No guidance on when to use this tool vs alternatives. No mention of when not to use it or context for selection among siblings like turingmind_get_related_code.

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

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

The description discloses it is a read operation (getting nodes) and that it depends on upstream verification. Since no annotations are provided, the description carries the burden, but it does not mention any additional behaviors like side effects, performance, or pagination. The description is adequate for a simple getter.

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

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

The description is extremely concise with two sentences, no redundant information, and front-loads the core action. Every sentence adds value.

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

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

Despite the tool's simplicity, the description lacks explanation of the 'repo' parameter and does not describe the return value. Since there is no output schema, the agent has no information about what the tool returns. The description is incomplete for effective use.

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

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

The only parameter 'repo' is not described in the schema (0% coverage) or in the description. The tool description adds no meaning about what 'repo' represents, leaving the agent unclear on how to specify the repository.

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

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

The description clearly states the verb 'Get' and the resource 'SpecNodes whose upstream dependencies are fully verified', specifying the ready_queue context. It distinguishes from sibling getters like turingmind_get_decision_queue by focusing on dependency verification, but does not explicitly contrast with alternatives.

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

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

The description mentions 'The execution loop calls this to determine what the Builder can work on next', which implies usage context. However, it provides no guidance on when not to use this tool or mention alternative tools for similar tasks.

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

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

No annotations exist, so the description must disclose behavioral traits. It describes what it does (find callers, callees, imports) but omits details like return format, side effects, or authorization needs. The read-only nature is implied but not explicit.

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

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

Two concise sentences, front-loaded with the core purpose. No redundant words; every phrase adds value.

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

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

The description covers the tool's purpose and key capabilities, but with no output schema, it misses the return structure. It is adequate for a straightforward tool but leaves some gaps for deeper understanding.

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

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

Schema coverage is 100%, so the schema already describes parameters. The description adds context about the relationship graph and impact analysis, but does not enrich individual parameter meanings beyond what is in the schema.

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

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

The description clearly states it gets related code entities for a function/class/file using a relationship graph, which is specific and actionable. However, it does not distinguish itself from siblings like turingmind_get_impacted_nodes, which may overlap.

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

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

No when-to-use or when-not-to-use guidance is provided. It mentions 'impact analysis' but doesn't contrast with other tools or specify prerequisites, making it hard for an agent to decide between alternatives.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only states 'Get' suggesting a read operation, but omits details such as permission requirements, what happens if the node_id is invalid, rate limits, or side effects. This is insufficient for safe invocation.

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

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

The description is two sentences long, front-loading the core action and output fields, with no redundant information. Every word earns its place, making it highly efficient.

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

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

Given no output schema, the description lists only a few returned fields (stage, confidence, failure classification) but not the complete state. The context of 33 sibling tools, many of which also retrieve node-related information, demands more explicit differentiation and comprehensive description to guide tool selection, which is lacking.

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

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

Schema description coverage is 0%, so the description must add meaning beyond the schema. It mentions 'SpecNode' but does not explain the 'node_id' or 'repo' parameters, nor their formats or defaults. The description fails to compensate for the lack of parameter documentation in the schema.

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

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

The description clearly states the verb 'Get' and the resource 'full state of a SpecNode', listing specific fields (stage, confidence, failure classification). This provides a clear purpose and distinguishes it from siblings that might retrieve only partial data or different aspects, though explicit sibling differentiation is absent.

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

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

The phrase 'Use to query where a node is in the Manufacturing Line pipeline' implies a usage context (checking pipeline progress), but it does not specify when not to use this tool, nor does it mention alternative tools like get_execution_state or get_audit_trail. The guidance is present but minimal.

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

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

No annotations provided, so the description carries full burden. It explains the tool parses AST and extracts relationships, but does not disclose whether it is read-only, performance impact, or network requirements. The force_reindex parameter hints at idempotency, but lacks explicit behavioral disclosure.

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

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

Two short sentences, front-loaded with the action and purpose. No unnecessary words. Efficiently communicates the core functionality.

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

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

With 4 parameters and no output schema, the description covers the tool's purpose and method well. Missing details on return value or side effects, but overall sufficient for an indexing tool.

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

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 extra meaning beyond the schema; each parameter is adequately described in the schema. No additional context on parameter usage or limitations.

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

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

The description clearly states the tool indexes a codebase using AST parsing, extracting specific entities (functions, classes, files) and relationships. It explicitly links to code review and impact analysis, distinguishing it from sibling tools like turingmind_apply_edit or turingmind_analyze_diff.

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

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

The description implies use for code review and impact analysis but does not provide explicit when-to-use or when-not-to-use guidance, nor does it compare with alternatives. It is clear but lacks direct usage instructions.

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

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

Since no annotations are provided, the description fully bears the burden of behavioral disclosure. It details automatic threshold checks, confidence decay, node failure at 0.6, invalidation on regression, and evidence recording, providing extensive insight into the tool's effects.

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

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

The description is concise (4 sentences), front-loaded with the main action, and every sentence adds meaningful information without redundancy. It is well-structured and earns its length.

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

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

Given the tool's complexity (7 params, no output schema), the description is comprehensive enough. It explains the flow of signal ingestion and the effects on nodes. It does not need to detail return values since no output schema exists.

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

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 adds value by explaining parameter semantics beyond the schema, such as giving examples for 'value' (e.g., 0.04 for 4% error rate) and clarifying special behavior for 'signal_type' ('regression' fully invalidates).

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

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

The description clearly states the tool's purpose: ingesting a live runtime signal into the constraint graph. It uses specific verbs and resources and distinguishes itself from sibling tools by being the only one that handles runtime signals.

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

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

The description explicitly says 'Call from CI, Sentry, Datadog, or any monitoring source,' giving clear context on when to use the tool. While it doesn't list alternatives or when not to use it, no sibling tool serves a similar function, so the guidance is sufficient.

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

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 correctly indicates a read operation via 'list', but does not explicitly state that it is non-destructive, nor does it describe any side effects, rate limits, or authentication needs. Adding a safety hint would improve transparency.

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

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

The description is two sentences long, front-loads the main purpose, and avoids unnecessary detail. Every sentence earns its place.

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

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

For a tool with 10 parameters and no output schema, the description is insufficient. It omits pagination behavior (e.g., implicit ordering, maximum page size), response format (list of memory objects), and how filters interact. A more complete description would mention that results are paginated and include a summary of what fields are returned.

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

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 mentions three filter dimensions (category, status, scope, security tags) but does not add new meaning beyond what is already in the schema. It does not explain how filters combine (AND logic) or provide examples.

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

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

The description clearly states the verb 'list' and the resource 'memory entries', and explicitly mentions filtering and pagination. It distinguishes this tool from siblings like 'turingmind_get_memory' (single entry) and 'turingmind_delete_memory' by framing it as a listing operation with multiple filter dimensions.

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

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

The description provides no guidance on when to use this tool vs alternatives (e.g., 'turingmind_get_memory' for a single entry, or 'turingmind_get_audit_trail' for history). There is no mention of context or exclusions, leaving the agent to infer usage independently.

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

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 implies a read operation by using 'List,' but does not explicitly state that the operation is non-destructive, nor does it mention any side effects, rate limits, or pagination. For a simple listing tool, this is adequate but not fully transparent.

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

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

The description is two sentences long with no wasted words. The first sentence immediately states the core purpose and filters, and the second sentence provides actionable examples. Front-loaded and efficient.

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

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

For a tool with 4 parameters, no output schema, and no annotations, the description covers the main purpose and gives usage tips for two filters. However, it lacks explanation of the required repo parameter, the output format, and any potential edge cases (e.g., empty list). It is sufficient for basic understanding but incomplete for complex usage scenarios.

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

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

Schema coverage is 0%, so the description must add meaning beyond the schema. It mentions three optional filters (stage, surface_type, level) and gives specific examples for stage=failed and surface_type=api_endpoint. However, it does not explain the repo parameter or the meaning of other enum values (e.g., level L0-L7, stage spec_defined). This provides partial but incomplete guidance.

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

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

The description clearly states the tool lists SpecNodes for a repository, with optional filters. It includes specific use cases like stage=failed and surface_type=api_endpoint, which distinguish it from other tools that focus on analysis, edits, or auditing. The verb 'List' and resource 'SpecNodes' are explicit.

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

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 specific filters: 'Use stage=failed to find nodes requiring repair' and 'Use surface_type=api_endpoint to build the Risk Posture Map.' This gives context for common scenarios, though it does not mention when not to use this tool or list alternatives.

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

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

No annotations provided, so the description carries the burden. It states the tool is non-destructive ('without making changes') and creates a permanent record, but omits details like idempotency, rate limits, or response format.

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

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

Two concise sentences, front-loaded with the core purpose, no unnecessary words.

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

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

For a simple logging tool, the description covers the purpose, usage, and permanence; it lacks detail on return values but that is acceptable given no output schema.

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

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

Schema coverage is 100%, so the description does not need to add parameter details; it provides minimal extra context beyond the schema, which is adequate.

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

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

The description clearly states the action ('log') and resource ('reasoning/thinking process') and explicitly notes it does not make changes, distinguishing it from sibling tools that modify state.

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

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

The description tells when to use it ('document your thought process, analysis, and decisions') and mentions audit trails, but does not explicitly exclude alternatives or state when not to use.

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

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

With no annotations, the description carries the full burden. It only describes the state transition without disclosing potential side effects, authorization requirements, error handling, or what happens if the node is already in a higher state. This is insufficient for an agent to use safely.

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

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

The description is extremely concise with two front-loaded sentences that convey the essential purpose and key constraints without extraneous information.

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

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

Given the lack of output schema and annotations, the description omits critical details such as return format, failure modes, and behavioral side effects. While the lifecycle is explained, the overall completeness is poor for safe invocation.

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

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

Schema description coverage is 0% and the description does not explain the parameter 'node_id' at all, leaving the agent to infer its meaning from context. This fails to add value beyond the schema.

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

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

The description specifies a clear verb ('Promote') and resource ('auto-inventoried node'), and details the lifecycle progression ('observed' → 'proposed' → 'governed'), distinguishing it from sibling tools like turingmind_create_spec_node or turingmind_update_spec_node.

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

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

The description provides contextual clues about when to use the tool (e.g., proposing nodes require contracts, governed nodes are actively checked), but lacks explicit statements about when not to use it or alternatives, leaving some ambiguity.

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

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

No annotations exist, so description carries full burden. It mentions recording but doesn't disclose side effects (e.g., overwrite behavior, authentication needs, or whether it can be called multiple times with different stages). The 'Builder/Auditor Mode' hint is unexplained.

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

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

Two sentences, no fluff. First sentence defines mode and purpose, second gives pipeline context. Every word earns its place.

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

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

Provides enough for basic understanding (purpose, stage list, use case) but lacks details on side effects, confidence interpretation, and required preconditions. For a tool with 4 params and no output schema, more completeness would be beneficial.

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

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

Schema coverage is 0% (no property descriptions), but the description lists the enum values for stage (same as schema) and implies node_id and confidence. It adds context by showing the pipeline order, though status enum values are not explained in relation to stages.

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

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

The description clearly states the tool records a SpecNode's execution stage and confidence, with specific verb 'Record a SpecNode's current execution stage and confidence'. It distinguishes from siblings like turingmind_update_spec_node or read-only tools.

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

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

It explicitly says 'Called by the agent as it moves a node through the Manufacturing Line pipeline' and lists the pipeline stages, providing clear context for when to use.

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

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

With no annotations, description must disclose behavior. It mentions human approval but lacks details on blocking/async nature, state changes, or permissions needed. Adequate but not thorough.

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

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

Two sentences, front-loaded with purpose and clear usage rules. No redundant text.

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

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

Given no output schema and moderate complexity, description is incomplete: does not explain what happens after request (e.g., blocking, return value) or provide more detail on context parameter. Adequate for basic use.

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

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

Description maps reason enum values to scenarios, adding value over schema. But node_id and context are not explained beyond minimal schema descriptions. Schema coverage is 33%, so description partially compensates.

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

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

The description clearly states the tool requests human approval for a SpecNode and lists three specific use cases, distinguishing it from siblings.

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

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

Explicitly states when to use (three conditions) and when not to use ('for everything else, the engine runs autonomously'), providing clear guidance on alternatives.

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

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

No annotations are provided, so the description must carry full weight. It only says 'Resolve' (implying mutation) without disclosing side effects, permissions required, or what happens to the conflict record after resolution. This is insufficient for safe agent invocation.

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

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

The description is a single sentence with no redundancy. It is front-loaded with the core purpose and immediately lists the key strategies.

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

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

Given the complexity (4 params, nested object, no output schema, many siblings), the description provides minimal context. It covers the basic purpose and strategies but lacks details on the resolution object, return values, and how strategies differ.

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

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

Schema coverage is 75%, with most parameters described. The description adds value by summarizing the strategy enum options. However, the 'resolution' nested object is not explained in the description.

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

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

The description clearly states the action ('Resolve conflicts') and the resource ('memory entries'). It lists specific strategies, which differentiates it from sibling tools like 'turingmind_detect_conflicts' that only detect conflicts.

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

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

The description implies the tool is used when conflicts exist, but offers no explicit guidance on when to use it versus alternatives or which strategy to choose. No when-not-to-use conditions are provided.

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

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

No annotations are provided, so the description carries the full burden. It discloses running tests, static checks, security scans, and updating confidence score. However, it does not mention potential side effects, required permissions, or whether the tool is safe (e.g., destructive implications are not addressed).

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

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

The description is concise with two sentences that front-load the purpose. It efficiently lists actions (runs tests, returns results, updates score). Minor improvement could be removing the 'Auditor Mode:' prefix for clarity.

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

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

Given no output schema and no annotations, the description adequately covers the tool's actions and outcomes. However, it lacks details on the return format of results, error conditions, and required setup. For a tool with 4 parameters and no structured output, more completeness is needed to fully guide the agent.

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

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

Schema description coverage is 75% (3 of 4 parameters have descriptions). The description adds minimal context beyond the schema, such as 'Auto-discovered' for test_dir, but does not elaborate on node_id or verification_types meaning. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool executes a verification suite for a SpecNode, runs tests, static checks, and security scans, and returns structured pass/fail results while updating a confidence score. It distinguishes from siblings like turingmind_generate_verification which likely creates verification suites.

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

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

The description implies usage via 'Auditor Mode' but does not explicitly state when to use this tool versus alternatives such as turingmind_generate_verification. No exclusions or when-not-to-use guidance is provided.

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

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

No annotations are provided, so the description carries full burden. It only states 'Create or update', which indicates mutation but lacks details on side effects, permissions, idempotency, or error conditions. Minimal behavioral disclosure.

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

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

Two short sentences, no fluff, front-loaded with main action. Every word earns its place.

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

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

With 9 parameters including optional ones like evidence, memory_id, confidence, security_tags, and yaml_definition, the description does not explain their purpose or usage patterns. No return value description (no output schema). Incomplete for a tool of this complexity.

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

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

Schema coverage is 100% with descriptions for all 9 parameters. The description adds 'supports learned patterns, explicit rules, and session context' but this is already captured by the 'type' enum. No additional semantic value beyond schema.

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

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

The description clearly states 'Create or update a memory entry' with specific supported types (learned patterns, explicit rules, session context), distinguishing it from sibling tools like turingmind_get_memory and turingmind_delete_memory.

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

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

The description implies usage for saving memories but does not explicitly state when to use this tool versus alternatives like turingmind_update_memory (if exists) or other write tools. No guidance on prerequisites or exclusions.

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

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

Discloses directionality (bidirectional) and data types (tombstones, active, etc.). Lacks details on idempotency, error handling, or authorization steps beyond env vars. Without annotations, description carries the burden but only partially covers behavior.

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

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

Two-clause sentence front-loads the main purpose ('Bidirectional memory sync for a repo') and then details mechanism. No fluff, but could be slightly more structured with separate sentences for pulling vs pushing.

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

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

For a single-param tool with no output schema, the description covers data flow and direction. Missing error conditions or success signals, but adequate for a sync operation.

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

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

Schema already documents 'repo' string clearly. Description reinforces it but adds no new semantic meaning beyond the schema. Baseline 3 is appropriate given 100% schema coverage.

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

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

Description clearly states 'bidirectional memory sync' for a repo, lists specific actions (pull tombstones, push memories). Distinguishes from siblings like turingmind_save_memory (single save) and turingmind_sync_codebase (code sync).

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

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

No guidance on when to use this tool vs alternatives (e.g., turingmind_save_memory, turingmind_list_memory). Does not mention prerequisites or when a sync is appropriate. Only notes environment variables needed.

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

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

With no annotations, the description carries full burden. It discloses key behavioral traits: applies confidence penalty to modified nodes and propagates blast radius. This goes beyond simple syncing to reveal 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.

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

Two sentences, directly addresses purpose, usage, and behavior. No redundant or wasted words.

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

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

Given no output schema and two simple parameters, the description covers purpose, intended trigger, and behavioral effect. Lacks explicit mention of return type or error states, but overall complete for its complexity.

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

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

Schema coverage is 100% with both parameters adequately described in the schema. The description does not add new meaning beyond stating what changes are being synced, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'syncs' and identifies the resource as 'codebase state with the constraint graph'. It also distinguishes itself from sibling tools like turingmind_analyze_diff by specifying its intended automated use via webhooks.

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

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

Explicitly states 'Intended to be called by git webhooks/hooks', providing clear usage context. Does not explicitly exclude manual use or list alternatives, but the context is sufficient.

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

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

No annotations are provided, so the description carries the full burden. It discloses that updating a contract triggers automatic subgraph invalidation, which is a key behavioral trait. However, it does not mention if metadata updates have similar effects, nor does it cover auth, rate limits, or idempotency.

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

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

The description is two sentences, front-loading the action and effect, then providing usage guidance. Every word adds value, with no redundancy.

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

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

Given the tool has 8 parameters, no output schema, and no annotations, the description is relatively sparse. It explains the key behavioral effect (subgraph invalidation) but omits return values, prerequisites (e.g., node must exist), and details on metadata updates.

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

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

Schema coverage is 88%, so most parameters are already described in the schema. The description adds little beyond the schema, only mentioning that 'contract' is a strict mathematical contract. This meets the baseline but does not significantly enhance understanding.

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

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

The description clearly states the tool updates an existing SpecNode's contract or metadata, distinguishing it from creation tools like turingmind_create_spec_node. It uses a specific verb and resource, and adds context about triggering subgraph invalidation.

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

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

The description explicitly advises using this tool 'when refining specs based on new information or audit results,' providing clear context. However, it does not explicitly state when not to use it or compare alternatives like promotion.

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