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

With no annotations, the description carries the full burden. It does disclose two real behavioral traits: the source/target nodes must already exist, and the id is auto-generated when omitted. It still omits permissions, failure modes (e.g. duplicate edges), and what mutation actually occurs, so it is only partially transparent for a mutation tool.

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, waste-free sentences with the primary purpose front-loaded and the id-generation caveat following. It is appropriately sized, though slightly terse given 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?

An output schema exists, so return values need not be explained, but for a 6-parameter mutation tool with no annotations the description is thin – missing permission requirements, edge-duplication behavior, and semantics for label/style/properties. It is the minimum viable level rather than 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 50%. The description adds meaning for 'id' (auto-generated when omitted) beyond the bare schema, but says nothing about 'label', 'style', 'properties', or the source/target semantics, leaving half the parameters undocumented in prose.

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?

States a specific verb+resource ('Connect two existing nodes'), which is clearer than a bare restatement of the name. However, it does not distinguish itself from the sibling 'edit_edge' or clarify the edge-vs-node relationship relative to 'add_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?

There is no explicit when-to-use guidance, no mention of alternatives like edit_edge or remove_edge, and no exclusions. The phrase 'two existing nodes' weakly implies the precondition that the nodes must already exist, but nothing routes the agent between this and its 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 it does disclose two useful behaviors: id auto-generated when omitted and label defaulting to id. However, it says nothing about duplicate-id handling, whether a graph must be loaded first, or permission/error behavior for a mutation tool.

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 tight sentences with no filler, and the most important default behavior is front-loaded. Every clause 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?

An output schema exists, so return values need not be explained. For a mutation tool with no annotations and 40% schema coverage, the description covers defaults but omits duplicate handling, prerequisites, and the meaning of the unrendered 'properties' parameter.

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 40% (style and position are described in-schema; id, label, and properties are not). The description usefully compensates for the undocumented id and label by explaining auto-generation and defaulting, but leaves 'properties' entirely unexplained in both places.

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?

States a specific verb and resource ('Add a node') that clearly maps to a graph mutation. It does not name or contrast with siblings like add_edge or edit_node, but the action is unambiguous on its own.

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 no when-to-use or when-not-to-use guidance, and does not mention alternatives such as edit_node for modifying an existing node. Usage must be inferred from the tool name and sibling list.

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 must carry behavioral weight; it does disclose two useful traits: patch semantics ("Only the given fields change") and a clearing convention ("" clears label/style). It omits permissions, error behavior, and how the properties arrays merge/remove relative to each other.

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 tight sentences, front-loaded with purpose and followed by the two most consequential behavioral rules. Every clause 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?

An output schema exists, so return values need not be explained, and the patch/clearing semantics are covered. However, for a 9-parameter mutation tool with zero schema descriptions and no annotations, the property-array semantics and required-id behavior are missing.

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 is the only source of parameter meaning, and it leaves major ambiguity: it lumps properties/setProperties/removeProperties under "properties" without explaining the merge vs. remove distinction, and never mentions that id is required or that newId renames the edge.

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?

States a specific verb and resource ("Edit an edge") and enumerates the editable facets (endpoints, label, style, id, properties). It is clearly distinct from edit_node/add_edge by resource name, though it never explicitly contrasts with siblings like set_style or remove_edge.

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 versus alternatives. Given siblings like set_style, remove_style, remove_edge, and add_edge, an agent gets no signal about whether editing one facet should go through those tools instead.

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. It does disclose genuinely useful semantics — set overwrites per key, remove deletes keys, properties replaces the entire list — but says nothing about permissions, reversibility, or whether edits are immediate versus requiring a save_graph call.

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 tight sentences, front-loaded with the tool's purpose, then parameter meaning, then special-key detail. No filler and nothing repeated from the schema.

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?

An output schema exists, so return values need no explanation, and the parameter semantics are well covered. The remaining gap is operational: a mutation tool with no annotations should say whether edits persist immediately or depend on the sibling save_graph 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 0%, so the description must compensate, and it does: each of the three parameters is given distinct semantics (add/overwrite vs delete vs full replacement) and it explains the otherwise undocumented 'title'/'subtitle' keys plus a formatting constraint ('keep it short').

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?

States a specific verb and resource — 'Edit the key/value properties of the graph itself' — and the phrase 'of the graph itself' distinguishes it from the adjacent edit_node/edit_edge tools. It stops short of naming those siblings explicitly, so the differentiation is implicit rather than declared.

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 is only implied: an agent can infer this is the tool for graph-level (not node- or edge-level) properties. There is no explicit guidance on when to prefer it, and no warning about how set and properties interact when both are supplied in one call.

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 behavioral burden and does well on the important cases: partial-update semantics, key add/overwrite vs delete vs full-replace, rename cascading to connected edges, and that an empty style string clears the style. It omits error behavior for a nonexistent id and any permission/return context, but the operationally significant traits are disclosed.

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?

Five short clauses, each delivering a distinct operational fact with zero filler. The partial-update constraint is front-loaded immediately after the purpose, so the most important behavior is read first.

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?

An output schema exists, so return values need no explanation, and nested property object shapes are already in the schema. For an eight-parameter mutation tool with no annotations, the description covers the high-risk semantics well; the missing piece is failure behavior when id does not resolve.

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 compensate, and it covers the four subtle parameters (properties, setProperties, removeProperties, newId) with genuinely useful semantics about mutation mode. It says nothing about id, label, or position, leaving three of eight parameters undocumented anywhere.

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?

States a specific verb and resource ("Edit a node") and immediately narrows scope with "Only the given fields change," which pins down patch semantics. It does not name or distinguish itself from siblings like add_node, remove_node, or edit_edge, so an agent must infer the boundary from the name alone.

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?

There is no explicit when-to-use or when-not-to-use guidance relative to siblings, and no prerequisites stated. What it does provide is disambiguation between the three property parameters (setProperties vs removeProperties vs properties), which is useful selection guidance at the parameter level but not at the tool level.

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 readOnlyHint=true already declaring the safety profile, the description adds real value: the return shape (ids, brief summaries, matched fields, sorted by id) and the pagination contract. It discloses filter-AND semantics, which is behavior beyond the annotations and schema. An output schema exists, so the return-shape detail is partially redundant, keeping it below 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?

Three tight sentences, front-loaded with purpose and scope, then return shape, then filter/pagination rules. No filler; every sentence carries a distinct fact (scope, output, pagination).

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 filtered-list read tool with annotations covering safety and an output schema covering return values, the description supplies the remaining essentials: filter combination rule, unfiltered behavior, and pagination chaining. Nothing needed to invoke it correctly is missing.

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, but the description adds inter-parameter semantics the per-field docs don't: filters combine with AND, all are optional, and cursor must be the prior call's nextCursor. That is genuine 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?

States a specific verb (search or list) and resource (nodes) plus the scope boundary: without fetching the whole graph. Explicitly differentiates from sibling get_node (for details) and implicitly from load_graph/get_graph, so an agent can pick it apart from alternatives without opening schemas.

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?

Gives when-to-use context: all filters optional and AND-combined, no filters lists every node, and names the alternative get_node when details are needed. Pagination behavior (pass nextCursor as cursor) is spelled out, leaving nothing to inference.

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?

readOnlyHint=true already establishes a safe read, and the description adds genuinely new behavioral detail: YAML output leads with a comment naming the current file while JSON is plain. That format-dependent output trait is not derivable from the annotations. It stops short of covering size or pagination 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 tight sentences with the scope statement front-loaded and the format nuance second. No filler and nothing redundant.

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-parameter read tool with an output schema, the description covers scope and the one behaviorally interesting aspect of output format. Nothing an agent needs to call it correctly is missing.

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% and the single enum parameter is documented, so baseline is 3. The description goes further by explaining what the format choice actually changes in the output (filename comment present in YAML, absent in JSON), which adds meaning beyond the enum values 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?

States a specific verb (Return) and resource (the whole current graph) and enumerates the payload contents (properties, styles, nodes, edges). The word 'whole' plus the enumeration cleanly separates it from siblings like get_node and find_nodes.

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 is implied: an agent can infer this is for retrieving the entire graph rather than a single node. However, it never states when to prefer it over get_node/find_nodes or how it relates to load_graph, so routing is left to inference.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's main added value is the retrieval scope (properties plus connected edges). It does not disclose behavior for a missing or invalid id (error vs empty result), which matters for a lookup tool, so it only clears the annotated bar partially.

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?

One sentence, front-loaded with the action and resource, with zero filler. Every clause carries 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?

An output schema exists, so return shape need not be restated. However, the zero-coverage id parameter and the undisclosed not-found behavior leave gaps that matter given the many sibling node tools an agent must choose between.

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 single 'id' parameter is documented nowhere, and the description never explains what identifier is expected (node key, name, UUID) or its format. With one required parameter and no compensating text, the description leaves the caller guessing.

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?

States a specific verb ('Return') and resource ('node') and adds scope detail — properties plus all connected edges — which differentiates it from the plural search-style sibling find_nodes. It does not explicitly name any sibling to route against, so it stops short of a 5.

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?

There is no when-to-use guidance, no exclusions, and no mention of alternatives such as find_nodes for lookup or get_graph for whole-graph retrieval. The agent must infer from the name alone whether this is the right call.

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 well: it discloses the persistent side effect that later changes are auto-saved to this file, and that a missing path silently starts an empty graph rather than erroring. It omits error/permission behavior and whether the previous current file is discarded.

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 short sentences, front-loaded with the load action, then side effect, then edge case. Every sentence earns its place with no filler.

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

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

A mutation-style, state-changing tool; the description covers format inference, persistence behavior, and the missing-file case, and an output schema exists so return values need no explaining. Only failure/permission semantics are unaddressed.

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 single path parameter is documented, and the description adds real meaning by explaining that the extension selects the parser (.json vs YAML). That is genuine added value beyond the schema's generic 'Path to the graph file'.

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?

States a specific verb (open/load) and resource (graph file) plus format handling and the stateful consequence of loading. It implicitly contrasts with siblings like get_graph (read-only) and save_graph, though it never names an alternative explicitly.

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 context is implied: call this to open a file and make it the working graph, and a missing file yields an empty graph. There is no explicit when-not or comparison to get_graph, so an agent must infer that get_graph reads the current graph rather than loading one.

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?

destructiveHint=true already declares this is an irreversible mutation, so the safety profile is covered by annotations. The description adds nothing beyond that—no note about whether the edge id must exist, whether removal cascades, or what happens on failure.

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 terse sentence with the action front-loaded and no wasted words. It is efficient, though the extreme brevity leaves little content to structure.

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?

An output schema exists, so return values need not be described. Still, for a destructive mutation tool the description is thin: it omits any note on id obligations, failure behavior, or relationship to add_edge/edit_edge, leaving real gaps.

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 carry parameter meaning; 'by id' only weakly indicates the single argument identifies the edge. No format, source, or lookup guidance is provided for the id.

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?

States a clear verb+resource: removing an edge, identified by id. However, it does nothing to distinguish itself from siblings like remove_node, edit_edge, or remove_style, which an agent must infer.

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 versus edit_edge (for modifying) or remove_node (for nodes). The agent gets no conditions, prerequisites, or exclusions to route between the removal 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?

Annotations declare destructiveHint=true, so the destructive nature is already known. The description usefully adds that all connected edges are also removed, which is non-obvious behavior beyond the annotation. However it doesn't disclose whether auth is required or whether removal is reversible/undoable.

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?

One sentence, front-loaded with the verb and resource, and efficiently communicates the cascade effect. 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?

An output schema exists, so return values needn't be explained. But for a destructive operation with an undocumented required id parameter, the description leaves gaps about parameter meaning and any preconditions.

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% and the single parameter 'id' is undocumented in the schema. The description does not clarify what the id refers to (node id vs other identifier). Baseline 4 for 0 params doesn't apply since there is 1 param; with no schema docs the description should compensate but doesn't.

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?

States a specific verb (remove) and resource (node), plus the cascade effect on connected edges. Distinguishable from remove_edge, though it doesn't explicitly name that sibling.

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 over remove_edge or before/after other operations. The cascade behavior is stated but no when-to-use or alternatives context is given.

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?

Annotations already declare destructiveHint=true, and the description adds genuinely useful context beyond that: nodes/edges referencing the removed style fall back to the default look. This predicts the side effect on dependent entities, which the annotation alone does not convey. It stops short of covering failure modes or whether the fallback is reversible.

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?

One compact sentence with the operation front-loaded and the side effect immediately following. Every clause 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?

An output schema exists, so return values need not be explained. The description covers what the tool does and its main destructive consequence; the remaining gap is the undocumented id parameter, which is minor for such a small 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?

There is a single required parameter (id) with 0% schema description coverage, so the description carries the full burden and does not name or explain it. 'A style' weakly implies id identifies the style to delete, but no format, source, or lookup guidance is given.

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?

Specific verb (Remove) plus resource (a style), which clearly identifies the operation and contrasts with the sibling set_style. It doesn't explicitly name the alternative, but the purpose is 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?

Usage is only implied by the name — 'remove a style' tells the agent this is the deletion path versus set_style for applying styles, but there is no explicit when-to-use guidance or prerequisite (e.g. whether the style must be unused or what happens if id is invalid). Adequate but with real gaps.

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 usefully discloses a real side effect (the saved path becomes the current file) and the format-inference rule, but says nothing about overwriting existing files, permission requirements, or failure behavior for an unspecified path.

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 tight sentences, front-loaded with the core action, with the conditional path behavior following immediately. Every clause carries 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 zero-required-parameter tool with an output schema (so return values need no explanation), the description covers the main behavioral question. It leaves overwrite/error semantics unstated, which is a minor but real 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 100%, so baseline is 3, and the description adds meaning the schema lacks: the format is inferred from the file extension (.json → JSON, otherwise YAML). It does not clarify directory creation or relative-path resolution.

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 and resource ('Save the current graph') and immediately qualifies the scope of the save. It contrasts functionally with load_graph in the sibling set, though it never names an alternative explicitly.

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 clearly explains the two operating modes: with a path it saves a copy there; without one it saves the current graph. This is conditional usage guidance, but it gives no guidance on when to prefer saving a copy versus saving in place, and names no 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 carries the full burden. It does disclose the meaningful behavior that the operation is a replace-by-id upsert and that mismatched node/edge fields are rejected, which is useful. However, it omits permissions, whether built-in styles can be overwritten, and whether persistence requires save_graph.

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, front-loaded with the create/replace behavior, followed by usage and the validation constraint. No filler, though the color-format example sits slightly apart from the main point.

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 16-parameter mutation tool with no annotations, the description covers the core behavior and the key validation rule, and an output schema presumably documents the return. It still leaves open operational context such as persistence requirements and permission needs, which matters for a write-style 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 75%, so most parameters are already documented, and the description reinforces the node/edge field restriction and CSS color format rather than adding new syntax. It clarifies the 'target' semantics and id-based replacement but leaves several parameters (textColor, name) without added meaning. Baseline 3 is appropriate given the schema does most of the work.

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?

States a specific verb+resource ('create or replace a reusable style in the graph styles') and clarifies the upsert-by-id semantics, distinguishing it clearly from the sibling remove_style. The agent immediately knows this writes a style definition rather than manipulating nodes or 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?

Explains how the created style is consumed ('Assign it via the "style" field of nodes/edges') and imposes a concrete applicability rule ('Fields marked "Nodes only" / "Edges only" are rejected for the other target'). It does not state prerequisites such as whether the graph must be loaded or saved, but the usage context is otherwise clear.

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