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

With no annotations, the description carries the burden, and it discloses key behaviors: it clears the plan flag, rejects commits without metadata.implements, and requires prior recording via update_node. It does not mention failure modes or reversibility, but the core behavior and preconditions are 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 three sentences, front-loaded with the primary action, followed by the verification gate and usage guidance. Every sentence provides necessary information without redundancy or filler.

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 fully covers the purpose, prerequisite conditions, and rejection behavior, and it points to additional rules. It does not describe the return value or side effects on child nodes, but for the purpose of selecting and invoking the tool correctly, the context 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?

The schema already describes both parameters ('Plan node id to commit' and 'Ground slug') with 100% coverage, so the baseline is 3. The description adds context about metadata.implements and source paths, but it does not add new syntax or format details for the parameters themselves.

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: 'Promotes a plan node (metadata.plan=true) to the real tree by clearing the plan flag.' This is a specific verb+resource+mechanism that distinguishes it from siblings like update_node, which is referenced as the prior step for recording implements.

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?

Explicit usage guidance is provided: 'Call this only after you have actually written the code and recorded implements via update_node.' The description also specifies a verification gate and references a rule link, making it clear when the tool is appropriate and what conditions must be met.

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?

Despite no annotations, the description discloses critical behavioral constraints: direction is caller→callee, start/end must be existing node ids, APIs are first-class (apis table) not generic edges, and it's for runtime data flows. This goes well beyond a simple 'create' and gives the agent necessary operational context.

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 bit long but well-organized: definition, examples, direction clarification, distinction from sibling, usage guidance, constraint, and rule reference. Each sentence contributes. Slightly more verbose than the highest-caliber examples, but no waste.

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?

It covers purpose, constraints, examples, and references a rule. No output schema exists, so return value is not clarified, and error conditions (e.g., what happens if start/end don't exist) are only implied. Still, given the tool's moderate complexity and rich description, it is mostly 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?

The description adds meaning to start/end ('must be existing node ids', 'direction is caller → callee') beyond the schema's terse 'Source/Target node id'. However, with 50% schema description coverage, it does not compensate for undocumented params like label, metadata, and description. Slug remains underdefined ('Ground slug' is vague).

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 a specific verb+resource ('Records an API flow') and immediately clarifies scope with examples (screen→endpoint, endpoint→table, external integration). It explicitly distinguishes from create_edge by stating this is for runtime flows vs dependency, making the purpose unambiguous even among sibling 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 gives explicit when-to-use vs alternatives: 'for a build-time/structural reliance use create_edge (dependency) instead.' It also provides selection guidance ('Add the flows a maintainer would trace; don't wire everything'), telling the agent which edges to create.

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 and does so thoroughly. It discloses the score rubric (0–8, defaults to 4), states urgency is intentionally excluded, explains solution overwrite semantics with project_events diff, status default, response auto-attached impact, empty radius meaning, and write-scope token requirement.

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 long but structured: it starts with the main purpose, then target, score, status, solution, and response behavior. Every sentence adds substantive detail, though the score rubric could have been condensed. Overall, the length is justified by the tool's complexity.

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 7-parameter tool with nested objects and no output schema, the description covers all necessary ground: target selection, score rubric, status default, solution handling, response impact details, and write-token requirement. It is fully self-contained for correct invocation and expectation setting.

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 significantly enriches multiple parameters: it gives the full score rubric referenced by the schema, explains target.kind semantics beyond the enum, clarifies solution lifecycle, and confirms status default. This goes well beyond baseline schema descriptions.

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 opens with 'Creates a new bug (issue eroding the target).' using a specific verb and resource, clearly distinguishing it from sibling tools like update_bug, delete_bug, and list_bugs. It also elaborates on the target.kind variants, reinforcing the resource type and scope.

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 provides explicit context on when to use different target kinds (node/api vs ground) and when to omit id. It also advises leaving solution empty rather than guessing and uses the impact response for QA scoping. However, it does not explicitly contrast with alternatives like update_bug or delete_bug, so it stops short of a full when-not/exclusion statement.

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 reveals key behavioral details: structural vs runtime, self-loop rejection, and a reference to rules. It doesn't mention idempotency, response format, or existence checks, but covers core behaviors well.

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?

Four sentences, front-loaded with the core purpose. Each sentence earns its place: what it creates, use cases, when not to use, constraints/reference. 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?

Despite no output schema, the description covers purpose, usage boundaries, alternatives, and a validation rule. It omits return value/error scenarios but points to a rule document for more details, making it fairly complete for a moderately complex 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 covers slug/source/target/type descriptions (67% coverage). The description adds significant meaning for 'type' with examples and clarifies source/target as directed nodes. However, label and metadata are left undocumented in both schema and 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 creates a directed edge for structural relations, with specific types (dependency, data_flow). It explicitly distinguishes from create_api for runtime calls and from node-creation tools by focusing on edges.

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 concrete use cases (module/library deps, route depending on data store, job writing a table) and explicitly says when NOT to use it ('use create_api instead for runtime request/call/integration'). Also advises restraint ('don't wire everything').

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 and excels: it discloses validation against protocol policies, rejection of hierarchy violations, soft issues returning as warnings, a connectionCheck reminder in the response, and transplant-specific behavior (auto-stamping metadata.transplanted=true). This goes well beyond basic mutation 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?

The description is long and dense, but every sentence carries distinct operational value—build order, completeness, warnings, connection follow-ups, transplant rules, and plan metadata. It loses a point for being a single unstructured block with repeated 'umtri://' references, which makes scanning harder, though it is not wasteful.

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 9 parameters, no output schema, and no annotations, this description is remarkably self-sufficient. It covers creation rules, hierarchy constraints, warning behavior, connection next-steps, season/transplant edge cases, and plan metadata expectations, leaving no major operational gap.

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 78% (7 of 9 properties have descriptions), so the baseline is 3. The description adds meaningful semantics for `type` (the metaphor vocabulary), `parent` (root-level omission), `season` (transplant allowances), and `metadata` (implements/placeholder conventions), which exceeds what the schema alone provides. It omits `sproutedAt` and `description` but those are adequately covered by 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 opens with 'Creates a node' and immediately defines the plant vocabulary protocol (trunk/limb/twig/leaf/vein), making the resource and action explicit. It also distinguishes from siblings by explaining when to use create_api/create_edge for connections, preventing confusion with related 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 provides explicit when-to-use and when-not-to-use guidance: build leaf-first, do NOT pre-build every trunk/limb, aim for complete maps, and add connections via create_api/create_edge after leaves/veins. It also forbids season creation via MCP and details plan-rule behavior for realizing human-drawn briefs.

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 of disclosing behavioral traits. It covers slug format/uniqueness, authenticated ownership, and write-token requirement—valuable context beyond the bare 'creates'. However, it omits success/error behavior and default visibility, leaving some room for improvement.

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 the core action. Every sentence provides essential information (creation, slug constraints, ownership, auth). No redundant or filler 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?

The description plus schema adequately cover purpose, required parameters, constraints, and auth for a creation tool. Missing details like success/error responses and default visibility are not critical given no output schema and the schema's default declaration. Slightly lower due to not explicitly connecting 'ground' to 'project' in the description itself.

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%, so the schema already documents most parameter meanings. The description adds only the uniqueness constraint for slug, which is not in the schema. For name, visibility, and description, the schema provides sufficient semantics, keeping this at baseline for 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 action ('Creates a new ground') and identifies the resource. The title further clarifies 'ground (project)', distinguishing this from sibling create_* tools like create_bug or create_node. The verb is specific and the resource type is 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 implies this tool is used to create a new ground, but it does not explicitly mention when to use it over alternatives. It provides prerequisites like unique slug and write-scope token, which are useful conditions but not direct alternatives or exclusions. No explicit guidance on scenarios favoring this tool.

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?

There are no annotations, so the description carries full burden. It explicitly discloses the mechanism ('Sets removed_at') and the key behavioral trait (history preserved via time slider), adding meaningful context beyond simple 'delete' terminology. It does not mention reversibility or permissions, but the core behavior is well covered.

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 the exact action ('Sets removed_at'), and every clause adds value about history preservation. There is no filler or 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?

The description covers the core soft-delete behavior and historical visibility, which is essential for a deletion tool. However, it omits any explanation of parameters, possible output, or error conditions. Given the lack of annotations and output schema, the description is serviceable but not fully 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 description coverage is 0%. The description provides no explanation for the two parameters (id and slug), leaving the agent to guess their roles and relationship to the API entry. The parameter names alone are insufficient, especially since both are just minLength-1 strings.

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 a specific action ('Sets removed_at on the API') and resource (API entry), which distinguishes it from sibling tools like delete_edge and delete_node. The title 'Soft-delete an API entry' reinforces the same specific verb+resource.

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 by noting history is preserved and the API remains visible in past season views, which hints at soft-delete semantics. However, it does not explicitly state when to use this tool versus alternatives, nor does it name any sibling tools or exclusion criteria.

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 deletion is permanent and that bugs have no history, making the record irrecoverable. It also contrasts with update_bug's history-preserving behavior. However, it doesn't mention side effects, permissions, or response details, so it stops short of a 5.

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 main action, and every sentence earns its place: the second sentence clarifies the alternative. There is no redundancy or fluff.

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 purpose, usage, and key behavioral transparency, but completely omits parameter semantics. For a tool with two required parameters and no annotations, this is a moderate level of completeness; the gaps are noticeable but not fatal to understanding the tool's role.

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 provides bare parameter names (id, slug) with zero description coverage, and the description adds no explanation of what each parameter means, whether both are needed, or how they identify the bug. This is a critical gap for an agent to correctly construct the invocation.

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 permanently removes a bug record, specifying the verb and resource. It also distinguishes itself from update_bug by noting that for marking a bug as resolved, update_bug should be used instead, making the purpose unambiguous.

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

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

Explicitly tells when to use this tool (permanent deletion) and when not to (for 'I resolved this', use update_bug with status='resolved'). This provides clear guidance on alternatives and is a model of usage direction.

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. It only states the deletion action and a use case, without disclosing side effects, irreversibility, permissions, or error conditions. The phrase 'retire' hints at consequences but lacks specifics.

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 and front-loaded, with two short sentences: one stating the action and one providing use context. There is no fluff or redundant 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?

For a simple delete operation with fully documented parameters, the description covers purpose and use case. However, given the absence of annotations and output schema, it could benefit from more behavioral context (e.g., return value, dependencies). It is minimally adequate but not fully 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?

Both parameters (id and slug) are fully described in the schema with 100% coverage, so the baseline is 3. The description adds no parameter-specific meaning beyond what the schema already provides.

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 'Removes an edge from the ground' with a specific verb and resource, and adds context about retiring dependencies/flows. This distinguishes it from sibling tools like delete_node or delete_api.

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 a clear context: 'Use to retire dependencies/flows that no longer reflect reality.' However, it does not explicitly mention alternatives or when not to use the tool, stopping short of full guideline coverage.

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 fully carries the burden of behavioral disclosure. It reveals that the underlying REST API would cascade but the MCP layer guards against silent loss, explains that hard=true is irreversible, and outlines the specific condition (project.transplanting=true) under which the guard is lifted — all crucial behavioral traits.

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

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

The description is front-loaded with the core action, then efficiently covers the policy, the rationale, and the exception in a logical sequence. Each sentence adds essential information—no fluff or redundancy—and the use of parentheses and an EXCEPTION marker makes the structure easy to parse.

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 lacking an output schema and annotations, the description is remarkably complete for the tool's complexity. It covers the primary soft-delete behavior, the safety guard, the underlying cascade risk, the transplanting exception, and the irreversible hard-delete option. Nothing critical is missing for an agent to invoke it correctly.

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

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

The schema already provides 100% parameter coverage, including a detailed description for the 'hard' parameter that states it is permanent, only honored during transplanting, and irreversible. The main description adds contextual policy around the guard but does not introduce new parameter-level meaning beyond what the schema already offers, so a 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 opens with 'Sets removed_at on the node' which precisely and concretely defines the tool as a soft-delete operation. It distinguishes itself from sibling tools like delete_edge, delete_api, and delete_bug by targeting a node specifically, and the title reinforces this.

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 gives explicit when-to-use and when-not-to-use guidance: it states that deletion is rejected if the node has active descendants and instructs to 'delete children explicitly first'. It also details the transplanting exception where the guard is lifted and hard=true becomes available, covering both normal and exceptional usage scenarios.

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 fully carries the burden of behavioral disclosure. It reveals acceptance of two ref formats (seq and internal id), that status is ignored, the response includes impact details, that numbers are per-ground and never reused, and that a deleted bug leaves a gap. It also states the error behavior for no match.

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 longer than many but every sentence earns its place. It is front-loaded with the core purpose, then flows logically through ref formats, comparison with list_bugs, response content, and edge cases. There is no redundancy or filler.

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?

Although there is no output schema, the description explicitly lists what the response contains (full description, metadata, impact with reachedCount, reached nodes, other active bugs) and covers error behavior. It also addresses the per-ground numbering nuance and the behavior for deleted bugs, making it self-sufficient for an agent to understand the tool's results and edge cases.

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 input schema already has 100% coverage for the two parameters, but the description adds substantial meaning beyond the schema: it clarifies that 'ref' can be a human-facing seq like '14' or '#14' or an internal 'bug-<uuid>', explains that numbers are per-ground and never reused, and describes what the response includes (full description, metadata, impact). This goes well beyond the schema's terse field descriptions.

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 opens with a specific verb and resource: 'Returns a single bug by reference,' and immediately frames it as the 'cheap path' compared to list_bugs. It also explicitly contrasts with list_bugs, making the tool's unique role unmistakable.

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 when to use this tool vs list_bugs: 'Use list_bugs only to scan for bugs you cannot yet name.' It also explains the advantage of this tool (ignores status, accepts human-facing references) and clarifies the context for reviewing past fixes.

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 discloses defaults (summary view, active bugs), size implications (full view is ~3x larger), behavior for slices (boundary nodes, externalNodes stubs, soft-deleted nodes omitted), and special cases like plan:true nodes and project.transplanting. This is far beyond what a minimal description would provide.

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?

While long, the description is organized into logical sections (summary vs full, slicing, descriptions control, shape data, bugs, plan, boundaries, transplanting). It is front-loaded with the primary purpose and every sentence contributes actionable information, with no redundancy or filler.

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 that there is no output schema, the description does an excellent job of describing the response shape (summary/full fields, shape stats, childCount, iaHints), edge cases (boundary/externalNodes, transplanting), and usage workflows. For a tool with 9 parameters, this description covers all necessary context an agent needs to use it 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?

Although the schema already documents every parameter, the description adds substantial strategic context. For example, it explains that maxType='twig' is "a cheap overview" and shows how rootId, depth, and role combine to read only the relevant subtree. This enriches the schema's static definitions with real usage patterns.

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 opens by clearly stating the tool returns "the tree(nodes), edges, apis, seasons, and bugs for one ground," providing a specific verb and resource. It also distinguishes from siblings by emphasizing that it returns the whole graph, while pointing to list_bugs for richer queries and get_bug for a single named bug.

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 usage guidance, including a recommended two-call drill-down workflow: "first get_graph with maxType='trunk' (or 'limb') for a cheap skeleton, find the id you want, then call again with rootId set to it." It also explains when to use view='full', how to control payload via descriptions, and mentions that list_bugs/get_bug are better for bug-specific queries.

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 goes far beyond the basics by explaining that impact does not always flow with the arrow, that traversal is over current live structure only, and that results are a list to check, not a proven failure set. It also documents the coverage.startsWithoutConnections edge case.

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 long but well-structured and front-loaded. It starts with the core purpose, then details directions, returns, and caveats. Every sentence adds essential information—no filler or 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 and the absence of annotations and output schema, the description is remarkably complete. It explains the returned fields (reached[], bugs[], coverage), traversal semantics, limitations, and how to interpret empty results. It is self-contained for an agent to select and invoke it correctly.

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 significant meaning beyond the schema. It explains direction's effect on edge traversal (e.g., 'dependency edges backward'), the exactly-one rule for node/bug, bug-as-target behavior, and what maxDepth and coverage flags mean. This makes parameter usage much clearer.

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 ('Walks the connection graph') and the resource ('edges + apis') with a specific goal ('find which other nodes a problem would reach'). It explicitly labels itself as 'the tool for' impact analysis, distinguishing it from sibling tools like get_graph.

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 provides explicit use cases ('if this breaks / I change this') and detailed direction semantics. It does not name an alternative tool to use instead, but the 'this is the tool' phrasing gives clear context. It also adds a constraint about exactly one start (node or bug) and ground-level bug rejection.

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 explains the default status filter, the wild→chasing→catched lifecycle, the summary vs full view contents, impactCount semantics, and score meaning (0–8 change-risk). This goes well beyond what the schema alone conveys.

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 long but densely informative, with every sentence earning its place. It is front-loaded with the core purpose, then systematically covers alternatives, defaults, status semantics, returned fields, and parameter usage without filler or 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 there is no output schema, the description adequately enumerates the returned fields (id, seq, target, title, score, status, timestamps, description excerpt, impactCount) and explains parameter effects. It also references relevant sibling tools, making it complete for both selection and 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?

Although schema coverage is 100%, the description adds substantial semantic value: it explains status aliases and the active default, pairs limit with order for 'the N newest', defines view='full', and clarifies score and impactCount meanings not obvious from parameter names or enum values alone.

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 opens with a specific verb and resource: 'Scans the bugs (issues eroding the ground) of one ground.' It also explicitly distinguishes itself from the sibling get_bug tool, which covers the 'already know the number/id' case, making the purpose unmistakable.

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?

Usage guidance is explicit and actionable: use get_bug for a single known bug, use get_impact for the full blast-radius list, and pass explicit status values like 'catched' or 'all' when wanting non-default results. It also clarifies the default active filter and how limit/order can bound a scan.

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 and delivers rich detail: append-only, newest-first ordering, actor format (user:<id> vs token:<id>), field-level diff structure, and the explicit exclusion of record_commit events. This gives the agent a clear model of behavior and side-effect profile.

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 dense but every clause adds value: definition, event types, actor/diff format, use case, filtering advice, and an important exclusion. It is front-loaded with the core purpose and remains focused 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?

There is no output schema, so the description must explain return values, and it does: each event carries actor, summary, and diff for updates. It also covers ordering, event coverage, filtering, and a key exclusion, making the tool's full behavior understandable without external schemas.

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 meaningful context by explaining the effect of entityType/entityId filtering ('get a single entity's timeline') and clarifying the semantics of the returned events, going beyond the schema's bare property descriptions.

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 opens with a specific verb and resource: 'Returns the append-only change history (most recent first) of a ground,' and enumerates exact event types (create, update, delete, plan_commit). This clearly differentiates it from siblings like list_bugs or list_projects, which serve different purposes.

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 the tool ('Use it to answer "what changed, when, and by whom"') and provides concrete examples (bug status transitions, node edits). It also gives an exclusion: git commits via record_commit live in node metadata, not here, which prevents mis-selection.

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 transparency burden. It discloses the authentication scope, the summary/full view distinction, and the always-stripped icon base64 (UI-only). However, it doesn't mention ordering, pagination, or potential rate limits, which are minor gaps for a list operation. Still, the added field-level detail exceeds typical descriptions.

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, each earning its place: purpose and scope, usage guidance, and return behavior. It is front-loaded with the core action and avoids fluff. The structure is clean and scannable, with 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 low complexity (one optional parameter, no output schema), the description is complete: it specifies the full return fields for both views, the stripping behavior, and the authentication scope. It also provides the usage context needed to invoke the tool first. The lack of output schema is compensated by the detailed field list.

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?

Although the schema covers 100% of the parameter (view) with an enum and description, the tool description adds significant meaning by explaining the default ('summary') and what 'full' unlocks (preNotes, seedMeta, typeCounts, raw metadata, timestamps). This enriches the parameter understanding well 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 explicitly states the tool returns all grounds (projects) accessible to the authenticated user, using a specific verb ('Returns') and resource ('grounds'). It also mentions the latest activity timestamp and differentiates itself from sibling tools by positioning 'Use this first to discover slugs for other tools', establishing it as the entry point.

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 tool says 'Use this first to discover slugs for other tools', giving clear when-to-use guidance. It also explains the default summary view and how to switch to full view with view='full', providing practical usage context. While it doesn't name alternatives like list_bugs, the entry-point guidance is strong enough for correct selection.

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 full behavioral burden. It discloses the human-only creation constraint, chronological ordering, and the summary vs full view behavior including the specific fields returned. It doesn't cover errors or auth, but these are not critical for a read-only list operation.

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?

Three sentences, each earns its place: first states the core function, second gives an essential constraint/rule, third explains the parameter effect and output. Front-loaded and free of fluff.

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 2-parameter tool with no output schema, the description explains the return format (summary fields vs full metadata) and points to an external rule for the human-only constraint. It lacks pagination details, but the tool is simple and likely not paginated. Overall 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 coverage is 100%, so baseline is 3. The description adds value by explaining the default view ('summary') and what 'view=full' includes ('metadata'), plus listing the exact fields in the default summary. This goes beyond the schema's brief descriptions.

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 states a specific verb+resource ('Returns the seasons of a ground') and adds distinct scope ('in chronological order'), clearly differentiating it from sibling list tools like list_bugs and list_events. The purpose is immediately obvious.

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 explicit guidance that seasons are human-only and creation via MCP is prohibited, with a reference link. This acts as a 'when not to use' instruction. It doesn't explicitly contrast with sibling list tools, but the exclusion and default view explanation offer clear context.

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 deduplication by sha, appending timestamp/message, returning matched node ids, that coChangeCandidates are not auto-created, suppression for large commits, and that Umtri does not read git itself. This is comprehensive behavioral 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 detailed and well-structured, front-loaded with the core action. Each sentence adds needed context about preconditions, behavior, or output. Slight extra length from rule references, but justified for a tool with multiple caveats.

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?

Even without an output schema, the description covers return values (matched node ids, coChangeCandidates), preconditions (change must be in tree), edge cases (dedup, large commits), and dependencies (external CI supplies sha+files). This makes it complete for the tool's 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 all parameters described, so baseline is 3. The description adds little beyond schema: it restates that files are matched against metadata.implements and message is optional, but these are already in the schema. No significant new semantic detail.

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 a specific verb ('appends') and resource ('metadata.commits'), and explicitly states it records git commit metadata onto nodes. It clearly differentiates itself from sibling CRUD tools (create_node, update_node) by focusing on the commit record action.

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 states recording is the LAST step, instructs to use create_node for new units and update_node for moved files first, and warns about consequences of skipping that. It also references create_edge/create_api for co-change candidates and cites rules for commit-sync, giving practical usage 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?

With no annotations, the description fully discloses side effects and risks: 'relaxing guards so historical/structural reconstruction can resume: add/edit nodes in any season incl. past, and hard-delete mistakes' and 'it removes safety guardrails'. It also notes that settling is human-only. This gives the agent a complete picture of consequences.

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 front-loaded with the main action, then provides crucial warnings and references. Every sentence adds value: the effect, what's allowed, explicit call conditions, exclusions, and a reference to rules. It is long but not wasteful—appropriately detailed for a safety-critical tool.

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?

This tool has one parameter, no output schema, and no annotations. The description is fully self-contained: it explains the action, the side effects, the exact user-intent requirement, and the irreversible human-only step. It leaves no ambiguity for 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?

The schema covers 100% of the parameter ('slug' with 'Ground slug.'), so baseline is 3. However, the description adds meaning by specifying the parameter must be a 'rooted ground', which is a precondition not in the schema. This is useful for correct invocation and justifies a 4.

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: 'Re-opens the transplant window on a rooted ground (sets project.transplanting=true)'. It uses a specific verb and resource, and the effect is explicit. This distinguishes it from the CRUD siblings, as it's a state transition rather than a create/update/delete operation.

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-to-use guidance: 'only call this when the user has EXPLICITLY asked to switch the ground into transplanting... Never decide to re-open transplant on your own judgment'. It also states an exclusion (rooting back is human-only) and references rules. This is the gold standard for usage 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?

With no annotations, the description carries the burden. It discloses the partial-update behavior (only provided fields change) and enumerates the allowed fields, which goes beyond a simple 'update' statement. However, it does not mention return values, idempotency, 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 a single concise sentence, front-loaded with the core action 'Partial update' and immediately listing the relevant fields. 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?

The tool has no output schema and no annotations, so the description should explain the response and any important behaviors. It does not mention what is returned, how success/failure is indicated, or the role of the 'slug' parameter. The nested patch object is only minimally covered.

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 only 33% (id has a description, slug and patch do not). The description lists the patchable fields (label, description, metadata, start, end), but these are already present in the schema. It adds no meaning for 'start', 'end', 'slug', or 'metadata', leaving gaps that the description should compensate for.

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 states 'Partial update of an API' with a specific verb and resource, and lists the patchable fields. This clearly distinguishes it from sibling tools like update_node and update_bug.

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 modifying existing APIs, but does not explicitly state when to use it vs alternatives or mention any exclusions. The 'partial update' wording gives some context but no direct comparison with 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?

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses the warning on skipped states, the wholesale replacement of metadata, the need to rewrite solution to the actually-applied fix, and the parallel-agent visibility implications of in_progress.

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 longer than average, but every sentence contributes workflow guidance or behavioral caveats. It is front-loaded with the core purpose and then expands into actionable rules; slightly more brevity would improve it, but it is not padded.

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 (nested patch object, multiple patchable fields, state transitions) and no output schema, the description covers all critical behavioral aspects: transition ordering, warnings, metadata replacement, solution rewriting, and the resolved-vs-delete tradeoff. It is contextually complete for an AI agent selecting and invoking the 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 only 33%, so the description must compensate. It adds significant meaning for status (lifecycle one step at a time), solution (rewrite before resolving), metadata (wholesale replacement, include existing keys), and score (0–8 change risk). The slug parameter remains undocumented, which holds this back from a 5.

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 opens with 'Partial update of a bug' and immediately identifies the most common use: status transition. It clearly distinguishes update_bug from sibling tools like create_bug and delete_bug by specifying what parts can be patched and how status changes drive the lifecycle.

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 gives explicit when-to-use guidance: set in_progress when starting a fix, set resolved when shipped, and prefer resolved over delete to preserve history. It also explains the parallel-agent signaling rationale and notes that skipping straight to resolved is acceptable with a warning, providing clear usage context.

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

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

With no annotations, the description fully discloses the behavioral implications: type changes reclassify roles, parent changes recompute ltree paths, restrictions on past-season nodes, and the effect of transplanting mode. This is far beyond the simple 'update' implied by the title.

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 dense but every sentence adds value: patch semantics, restrictions, exceptions, validation behavior, and a reference for transplant rules. It front-loads the purpose and patchable fields before diving into edge cases.

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 thoroughly covers operation, constraints, exceptional modes, and validation for a complex update tool with no annotations or output schema. It does not describe the return value, but this is not critical given the detailed behavior and no output schema requirement.

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 parameters are already documented. The description adds meaningful context by explaining the effects of changing specific fields (type, parent, season, sproutedAt) and highlights metadata.implements as a use case, going beyond raw schema definitions.

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 'Partial update of a node' and enumerates the exact patchable fields, making the tool's purpose unambiguous. It differentiates from siblings like create_node and delete_node by focusing on modification of an existing 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 implies usage by defining what can be patched and provides detailed conditions (grown-node restrictions, transplanting mode, past-season rejection). It references create_node for validation parity, but does not explicitly contrast with other update 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.