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

With only idempotentHint in annotations, the description carries most of the burden and does well: case-insensitive matching, exact-name precedence over aliases, and read-mode behavior when neither add nor remove is supplied. It omits conflict/failure behavior (e.g., adding an alias that collides with an existing entity name) and whether removals affect existing edges.

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 tight sentences, purpose and effect front-loaded, then usage trigger, then behavioral caveats, then the zero-argument case. No filler and every sentence carries distinct 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 3-parameter, no-output-schema tool with full schema descriptions, this covers purpose, trigger, precedence, and the list fallback. The main gap is return-shape detail for the list mode, but the description signals that mode exists, which is the important part.

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, but the description adds real meaning beyond the schema: it explains that supplying neither add nor remove turns the call into a list operation and clarifies resolution precedence for the entity parameter. It does not document alias formatting limits or array size constraints.

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 (add/remove) plus resource (alternate names for an entity) and explains the effect: future writes and lookups resolve to it instead of creating a duplicate node. This clearly separates it from graph_merge/graph_unmerge siblings without needing to name them.

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 a concrete when-to-use trigger: 'when the user says two names refer to the same person or thing: a nickname, a maiden or married name, a first name used alone,' and the duplicate-avoidance rationale implicitly distinguishes it from merge. It stops short of explicitly naming the sibling alternative (e.g., graph_merge) or stating when not to use it.

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

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

No annotations present, so description carries full burden. It discloses the append-only action and log file path. However, it does not mention idempotency, concurrency behavior, or error handling (e.g., what happens on duplicate events). Adequate for a simple logging tool but could be more thorough.

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

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

Two dense sentences pack all essential info: action, target file, event types, and data guidance. 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?

For a logging tool with no output schema, the description is complete: it specifies the action, file location, event types, data expectations. All necessary context for correct invocation is present.

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 both parameters fully. Description adds value by explaining that data fields vary by event type and advising 'Always include relevant names/IDs,' which aids correct usage beyond 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 the tool appends events to a specific audit log, lists 16 event types, and highlights entity_resolved's role. This specificity and verb+resource clarity distinguish it from sibling tools like graph_boost or graph_merge.

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 says 'Call this during the dream process' and enumerates events. Provides context but no exclusion criteria or alternatives (e.g., when to skip logging). The description implies usage but doesn't fully guide when not to use.

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

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

The description adds key behavioral details beyond annotations: immediate persistence, weight clamping at 1.0 to prevent overflow, saturation on repeated boosts, and return of previous and new weight. No contradiction with idempotentHint.

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 concise sentences, each serving a distinct purpose: purpose, usage trigger, and behavioral details. No wasted words, front-loaded with primary action.

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

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

The description covers purpose, trigger, behavior, and return value. While it lacks explicit mention of error handling (e.g., missing edge), it is largely sufficient for a simple boost tool. No output schema exists, so the return info is valuable.

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 good parameter descriptions. The tool description adds context about user confirmation and clamping but does not significantly elaborate on individual parameters beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool increases an edge's weight when the user confirms recalled information, which is a specific verb and resource. It distinguishes it from sibling tools like graph_weaken (weight decrease) and others by tying usage to user confirmation.

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 call: when the user says 'yes', 'exactly', or confirms recalled information. However, it does not mention when not to use it or contrast with alternatives like graph_weaken for decreasing weight.

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

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

The description adds value beyond the readOnlyHint annotation by detailing the specific data included in the bundled context. However, it does not disclose any additional behavioral traits such as performance implications or return size.

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: first states purpose, second gives usage guidance, third quantifies benefit. No redundant information, perfectly front-loaded.

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

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

Given the tool's complexity (6 optional parameters, no output schema), the description adequately explains what is returned. However, it lacks details on the exact format or structure of the output, which would be helpful 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?

Schema coverage is 100%, providing baseline value. The description adds context by explaining that parameters like topic and project_cwd are for optional neighbourhood fetching and affinity scoring, linking them to the overall bundle purpose. This adds some meaning beyond the schema's 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 clearly states it bundles a session's worth of context, listing specific items like graph health, pending work, contradictions, etc. It also distinguishes itself from sibling tools by explicitly mentioning the individual tools it replaces (graph_stats, graph_query, graph_contradictions).

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

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

It explicitly instructs to use the tool at session start instead of running separate tools, and quantifies the benefit as reducing round trips from 4-5 to 1. This provides clear when-to-use and alternative 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?

Annotations indicate read-only; description adds that no GDS/APOC is needed, explains seed selection and BFS behavior, and notes community assignment logic, providing rich context beyond annotations.

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 covering purpose, algorithm, use case, output format, and alternatives—no wasted words, front-loaded with key 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?

Covers algorithm details, return structure, filtering, and alternative tools. Minor gap: no mention of behavior when no communities are found, but otherwise thorough.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description reaffirms parameter roles but does not add significant new 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?

Clearly states the tool finds clusters of densely-interconnected entities, describes the algorithm and output format, and distinguishes from siblings by advising when to use alternatives.

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

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

Explicitly advises to use graph_query or graph_search when starting from a specific entity, and explains the algorithmic constraints (greedy seed-based BFS, weight threshold, unique community assignment).

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 mark readOnlyHint=true, and description aligns by specifying it returns contradictions without mutations. Adds details on return format and default filtering of unresolved pairs.

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 well-structured sentences: purpose, usage, return format, parameter guidance. No redundant 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?

With simple schema (1 param, no output schema), description fully covers purpose, usage, return structure, parameter semantics, and resolution hints.

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 parameter with description. Description adds context: explains default behavior and when to use include_resolved=true (historical audits), building on schema.

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

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

Clearly states the tool finds contradictory facts via CONTRADICTS edges. Distinct from sibling tools like graph_audit or graph_search by focusing on contradictions.

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: during reviews, before graph_decay, or when user asks about conflicts. Also suggests resolution tools (graph_weaken, graph_relate) as 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?

Annotations provide readOnlyHint=true, and the description reinforces it by stating 'Enforced read-only via Neo4j executeRead()'. Adds context about admin-only restriction and security rationale, which goes beyond the annotation.

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

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

The description is concise with 4 sentences, front-loading the core purpose. Every sentence adds value: purpose, user responsibility, read-only enforcement, admin-only restriction. No wasted words.

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

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

Given the tool's complexity (2 parameters, no output schema), the description covers purpose, usage, constraints (admin-only), safety (read-only), and rationale. It is complete for effective 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?

Schema coverage is 100%, so baseline is 3. The description mentions the cypher parameter but does not add significant detail beyond the schema. The params parameter is an object, but no additional explanation is provided.

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

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

The description clearly states the tool executes a read-only Cypher query against the memory graph, with the user generating the Cypher. It differentiates from siblings by specifying use for custom queries not covered by other 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?

Explicitly states when to use (custom queries not covered by other tools) and when not to use (admin-only bootstrap tenant). Provides rationale for the admin restriction, preventing tenant bypass. Implies alternatives by mentioning other 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?

The description adds significant behavioral context beyond the destructiveHint annotation by detailing that decay is irreversible and requires a backup for restoration. It also mentions the return of counts per type. No contradiction with annotations (destructiveHint matches).

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 highly concise with three sentences. It front-loads the core action and then provides crucial warnings. Every sentence adds value, and there is no redundant or extraneous information.

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

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

Given the tool's complexity (applies decay to all nodes/edges with per-type half-lives), the description covers the algorithm, context (dream process), irreversibility, preview option, and return counts. It lacks explicit half-life values beyond examples, but overall provides sufficient context for an agent to use the tool 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 input schema has 100% coverage with a single parameter (dry_run) that has a clear description. The tool description reinforces the parameter's purpose, but adds no new information beyond what the schema already provides. Baseline score of 3 is appropriate.

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

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

The description clearly states it applies time-based decay to node confidence and edge weights using per-type half-lives, with specific examples (preferences ~693d, events ~99d). It also mentions it's called by the dream process during maintenance. However, it does not explicitly differentiate from sibling tools like graph_weaken or graph_prune, leaving some ambiguity about when to use decay vs. alternatives.

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

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

The description provides explicit usage guidance by recommending preview with dry_run=true first and warning that decay is irreversible without restoring from a backup. It also notes the tool is called during dream maintenance. However, it does not specify when not to use this tool or suggest alternatives, which would further improve 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?

The description adds value beyond the annotations by explicitly stating 'Cannot be undone' and that deletion includes 'all its edges', which complements the destructiveHint annotation and informs the agent of irreversible cascade 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 extremely concise, consisting of two short sentences that front-load the action and key constraints. Every sentence is meaningful and earns its place.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage context, and behavioral transparency completely. No missing information is apparent.

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?

With 100% schema description coverage, the parameter 'id' is already well-documented in the schema. The description adds minimal extra meaning ('by ID') but does not introduce new details beyond the schema.

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

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

The description clearly states the action ('permanently delete'), the resource ('entity node and all its edges'), and specific use cases ('removing duplicate or erroneous nodes'), which distinguishes it from sibling tools like graph_merge or graph_unmerge.

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 for when to use the tool ('removing duplicate or erroneous nodes') but does not explicitly state when not to use it or mention alternatives, though the destructive hint implies caution.

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 mark readOnlyHint=true. The description adds beyond this: 'Returns up to `limit` entities ordered by `sort_by`; pagination is single-page (raise `limit` if you need more).' This discloses return behavior and pagination constraint. No contradiction with annotations.

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 purposeful. First sentence states purpose, second gives use cases and alternatives, third explains return behavior and pagination. 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?

No output schema, but description covers return behavior (up to limit entities, ordered) and pagination. Provides enough context for an agent to understand what the tool returns without needing an output schema. Minor omission: doesn't mention if count or metadata is included.

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%, baseline 3. The description adds meaning by explaining `limit` and `sort_by` behavior ('returns up to limit entities ordered by sort_by') and clarifies `search` as full-text. This slightly exceeds baseline.

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

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

The description clearly states 'Browse or search the entity catalog' and gives specific use cases: checking existence before creation and listing entities by type. It distinguishes from sibling tool graph_query by explicitly stating 'For relationship-aware lookups... use graph_query instead.'

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 when-to-use (checking existence before graph_relate, listing entities) and when-not-to-use (relationship-aware lookups) with a named alternative (graph_query). This gives clear guidance for an AI agent.

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

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

No annotations are present, so the description carries full responsibility. It discloses that the tool creates a timestamped JSONL file in the backups/ directory and that old backups are pruned automatically. It does not specify side effects on the graph itself, but 'export' implies read-only, which is acceptable.

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

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

The description is three sentences long, front-loaded with the core purpose, followed by usage guidance and behavioral detail. Every sentence adds value with no redundancy.

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

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

Given no output schema, the description adequately covers what is exported (all nodes and edges), the format (JSONL), and the destination (backups/ directory). It omits explicit mention of return values, but for a backup tool this is generally acceptable.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no extra semantics beyond what the schema already provides for the 'keep' and 'label' parameters. It mentions timestamped filenames, but that is output-related rather than parameter-specific.

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 'Export all graph nodes and edges to a timestamped JSONL backup file', specifying the exact verb ('export') and resource ('graph nodes and edges'), which distinguishes it from sibling tools like graph_delete or graph_prune.

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 recommends running 'before any risky operation, or on a weekly schedule', providing clear usage guidance. While it does not list alternatives, the context is clear enough for an agent to decide when to invoke.

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?

Describes idempotent behavior beyond the annotation, explaining that queueing same file overwrites. Also mentions async processing by nightly dream process, adding valuable behavioral 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?

Description is concise and well-structured: first sentence states main function, then usage guidance, alternative, and idempotency. Every sentence adds value without redundancy.

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

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

Covers two modes, usage guidance, and idempotency. However, no output schema exists and the description omits what status returns (e.g., backlog count). Minor gap but largely complete.

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

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

Schema coverage is 100% with clear descriptions for all parameters. The description restates the action modes but does not add new meaning beyond the schema, so baseline score applies.

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

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

Description clearly states it queues a document for async extraction or checks status, distinguishing two modes. It also contrasts with graph_relate, a sibling tool, making 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 says when to use (file for graph summarization, not needed in conversation) and when not to (inline assertions, use graph_relate). Provides clear context for decision-making.

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 annotations providing destructiveHint=true, description adds crucial details: edges between source and target dropped, edge consolidation with higher weight wins, target's embedding cleared, audit logging. No contradiction.

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?

Description is well-structured, front-loaded with key action, then details. It is slightly long but each sentence adds value.

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

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

Complex tool with many behaviors; no output schema but description mentions return behavior (dry_run preview, audit logging). Covers edge cases, destructive nature, recovery. Very complete.

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

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

Schema coverage is 100%, so baseline 3. Description doesn't add much beyond schema for parameters, but it does mention dry_run for preview and reason for audit. However, the description is more about behavior than parameter-level specifics.

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 the tool consolidates two entities, moves edges, deletes source, and adopts properties. It clearly distinguishes from siblings like graph_unmerge (inverse) and graph_merge_suggestions (precursor).

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 says when to use (after graph_merge_suggestions or confirmed duplicates), and what not to do (same-tenant only, refuses self-merge). Mentions preview with dry_run, and alternative graph_unmerge for recovery.

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 indicate read-only and non-destructive. The description adds 'never auto-merges' and details the algorithm (embedding similarity, shared-neighbor overlap, name-token Jaccard). No contradictions.

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: purpose, read-only and algorithm, usage guidance. Every sentence provides essential information with no redundancy. Ideal conciseness for an AI agent.

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 suggestion tool without output schema, the description covers purpose, safety, algorithm, and usage. Minor gap: does not describe return format (likely a list of pairs). But given the clarity and annotations, it is nearly complete.

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

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

Schema coverage is 100% with detailed descriptions for all 7 parameters. The description provides high-level context (e.g., default weights) but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'surface' and the resource 'candidate pairs of entities likely to be duplicates'. It distinguishes from siblings like graph_merge (destructive) and graph_relate (soft alias) by mentioning alternative uses.

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 advises using this tool for triaging entity-explosion before other specific operations, naming alternatives (graph_merge, graph_relate). Provides clear when-to-use and 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?

Beyond the destructiveHint annotation, the description adds critical behavioral context: 'DESTRUCTIVE — always preview first' and 'Requires user confirmation before execute mode'. This fully discloses the tool's risks and safe usage.

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

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

Two concise sentences with no wasted words. Purpose is stated first, followed by crucial safety warnings. Highly efficient.

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

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

Given the destructiveHint annotation and complete parameter schema, the description sufficiently covers context. No output schema exists but is not critical for this operation. Could marginally improve by explicitly differentiating from graph_delete.

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% (all 5 parameters have descriptions with defaults and types). The description adds no additional parameter information beyond the schema, meeting the baseline expectation.

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 'Remove entities and edges that have decayed below threshold', specifying both the verb (remove) and the resource (decayed entities/edges). This distinguishes it from siblings like graph_delete (generic deletion) and graph_decay (likely calculates decay).

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 clear usage guidance: 'always preview first' and 'requires user confirmation before execute mode'. It implies caution but does not explicitly state when not to use or list alternatives.

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

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

readOnlyHint=true already establishes this as a safe read, so the description's added value is in return behavior: it discloses that results are up to `limit` nodes plus connecting edges within `max_hops`, each carrying weight and source provenance. That is meaningful context beyond the annotation, though it says nothing about cost, pagination, or missing-entity 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?

Three sentences, zero filler: purpose and scope first, routing decision second, return shape third. Each sentence carries distinct, non-redundant information and the discriminating constraint is front-loaded.

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

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

With 8 parameters, no output schema, and a graph traversal that could easily be misused, the description is complete enough to call correctly: it covers purpose, routing, and return semantics. The remaining parameters (min_weight, current_only, entity_types, context_level, project_context) are left entirely to the schema, which is acceptable at 100% coverage but leaves the traversal-filtering story thin.

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 goes slightly further by explaining how `limit` and `max_hops` jointly shape the result (matching nodes plus their within-depth connecting edges) rather than restating field names, which helps an agent reason about traversal depth.

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?

Opens with a specific verb+resource ("Query the memory graph by canonical entity name") and immediately names the sibling it is not: graph_search. An agent can distinguish this tool from the other 23 graph_* tools without opening either schema.

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 the selection condition ("when you know the entity name or close-to-canonical form", with examples like "Steve") and routes the other case to the alternative tool ("for natural-language phrasing or synonyms ... prefer graph_search"). When-to-use and the alternative are both spelled out.

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 state readOnlyHint=true. Description adds that it normalizes and extracts text content, and that it uses a canonical parser. Provides extra context beyond annotations.

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

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

Two concise sentences: first covers purpose and result, second covers usage guidance. No wasted words, information is front-loaded.

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

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

Given 3 params, no output schema, description covers what the tool does, what it returns, and why to use it. Missing explicit details on error handling, but adequate for a read tool.

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

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

Schema coverage is 100% (baseline 3). Description adds search location for session_id and precedence for file_path, adding meaning beyond schema. For text_only, schema already describes default and behavior.

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?

Cleary states verb 'read and parse', resource 'Claude Code JSONL transcript file', and what it returns. Distinguishes from sibling graph tools that are about graph operations.

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 says 'Use this instead of reading raw JSONL directly' and explains benefit (format changes only need updating this tool). Gives clear when-to-use and why.

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

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

The description adds value beyond the idempotentHint annotation by explaining that the default is idempotent and fast, and providing a time estimate (~10ms per entity). It also clarifies the effect of force=true, giving the agent a clear behavioral model.

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 consists of two concise sentences, front-loading the primary purpose and efficiently conveying the key details about behavior and performance. No unnecessary words.

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

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

For a simple tool with a single parameter and no output schema, the description covers the purpose, default vs. forced behavior, use case, and performance estimate. It is complete and self-contained.

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 describes the parameter with a default and a brief description. The tool's description adds meaningful context by explaining when to set force=true (after recipe changes), which goes beyond the schema's description.

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

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

The description clearly states the tool's action ('Regenerate semantic-search embeddings for entities') and specifies the default behavior (only missing embeddings) versus the forced re-embed mode. This distinguishes it from other sibling tools by focusing on a specific 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 context for when to use force=true ('after changing the embed-text recipe'), indicating a clear usage scenario. However, it does not mention when to avoid the tool or compare it to alternatives among siblings.

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

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

With only idempotentHint available, the description carries real weight and delivers: batch runs in one transaction so a DB failure keeps nothing, an invalid item is skipped and reported without blocking the rest, unknown relations degrade to RELATED_TO with the original preserved in proposed_relations, unknown types to Object with proposed_type, and re-assertion strengthens a capped edge with action 'strengthened'. These are exactly the non-obvious traits an agent needs before firing a mutation.

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?

Purpose is front-loaded and every clause carries information — no filler and no restatement of the title. It is a single dense paragraph with several stacked subordinate clauses (transaction behavior, fallback vocabulary, idempotency), which would scan better as short segments, but nothing is wasted.

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 13-parameter tool with nested batch objects and no output schema, the description covers the decision points that matter: mode selection, endpoint creation/matching, atomicity, per-item error handling, vocabulary fallbacks, and idempotent strengthening with a reported action. Return-value detail is minimized because there is no output schema to defer to, yet the one observable outcome ('strengthened') is named; the remaining batch relation-to-localId linkage stays with the schema.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents weight, relation, valid_at, provenance fields. The description adds meaning on top by grouping from_name/to_name/relation as the 'single mode' parameter set and tying the relation parameter to a required vocabulary with a documented fallback, which is more than the schema alone conveys.

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 opening sentence states a specific verb pair and resource: 'Create or strengthen a relationship between entities.' It goes further by explaining the auto-creation of missing endpoints and the match-by-name/case-insensitive/alias rule, so an agent immediately knows this is the graph write path rather than a read (graph_query) or maintenance (graph_prune) 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?

It explicitly splits usage into 'single mode (from_name/to_name/relation)' versus 'batch mode when extracting from a transcript or document', giving a concrete condition that selects each path. It stops short of naming sibling tools or stating when not to use this tool at all (e.g., deletion via graph_delete), so it is clear context without full routing 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?

Annotations only declare readOnlyHint=true, and the description adds genuinely useful operational context: local bge-small-en 384-dim embeddings, no external API dependency, and fallback behavior. It does not describe return shape or performance characteristics, but the added context is substantive.

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 front-loaded sentences with no filler; the purpose, mechanism, and usage condition all earn their place. Slightly dense but efficiently organized.

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 6-parameter read-only search tool with a fully documented schema and no output schema, the description covers what it does, how it works, and when to prefer it. Only the return structure (seeds plus neighbours) is left implicit, a minor 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 description coverage is 100%, so all six parameters including defaults and ranges are already documented in the schema. The description only restates the optional expansion behavior and adds nothing about entity_types, min_similarity, or expand_min_weight. Baseline 3 applies.

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

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

States a specific verb+resource ('find entities semantically similar to a natural-language query') and adds a secondary behavior ('optionally expand via graph traversal'). It clearly differentiates itself from the sibling graph_query/graph_cypher tools by naming its distinct mechanism (embeddings).

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 the best-fit condition ('when the user's wording doesn't match canonical entity names') with concrete examples, and names the alternative route ('falls back to graph_query if no embeddings available'). An agent can select this over siblings without further 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?

Annotations already declare readOnlyHint=true, so the tool is safe. The description adds behavioral context by specifying it returns aggregate counts only and has no side effects. It does not mention any additional behaviors (e.g., rate limits), but for a simple stats tool, this is sufficient. Slight deduction for not elaborating on output structure beyond listing stats.

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 concise sentences. The first sentence immediately states the purpose and what it returns, while the second provides usage guidance and confirms no parameters. Every word adds value, and it is front-loaded with the most critical information.

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

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

Given the tool's simplicity (no params, no output schema) and the richness of sibling tools, the description is fully complete. It explains what the tool returns, when to use it, and what it does not do (aggregates only). The agent can make an informed decision without needing additional context.

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 tool has no parameters, and the input schema is empty. The description explicitly confirms 'No parameters,' which is clear and accurate. With schema coverage at 100% and no params, no additional detail is needed.

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 it returns aggregate graph health statistics (node/edge counts, average weight, etc.), using a specific verb+resource ('Graph health dashboard'). It clearly distinguishes itself from sibling tool graph_entities by noting it returns aggregates only, not individual entities.

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 clear guidance on when to use the tool: at session start, after graph_decay or graph_prune, or when debugging query output. It also explicitly excludes usage for individual entity lookup, directing users to graph_entities. This covers when-to-use and 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?

The description adds significant behavioral detail beyond the destructiveHint annotation: it explains that edges are redistributed, the original entity keeps unmoved edges, the new entity gets a stub embedding, and the action is logged to an audit trail with a reason. No contradictions with annotations.

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-loaded with the main action and purpose. Every sentence adds value: the first defines the operation and usage context, the second provides critical details about edge redistribution, embedding, audit logging, and return value.

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

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

Given the complexity of a destructive graph operation with 5 parameters and no output schema, the description is remarkably complete. It explains the behavior, side effects, return value (IDs of both entities), and follow-up action (re-embedding). No critical 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?

All 5 parameters have schema descriptions (100% coverage), so baseline is 3. The description adds value by explaining that edges_to_move specifies which edges to move and that the original entity keeps the rest. It also notes that reason is logged to audit, which is not clear from schema. However, new_entity_name and new_entity_type parameters are not elaborated beyond schema.

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

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

The description clearly states the verb 'split' and the resource 'falsely merged entity'. It distinguishes from sibling tools like graph_merge and graph_delete by specifying it's for undoing a mistaken merge. The example with 'Anna' and 'Anne' reinforces the purpose.

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 says 'Use when entity resolution made a mistake', providing clear guidance on when to use. It also advises re-deriving embeddings with graph_reembed after splitting, which is a helpful follow-up step. Implicitly, it should not be used for correct merges.

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?

Beyond annotations (readOnlyHint=true), description discloses that it returns issues with structure and severity, is non-destructive, and can scan whole graph. No contradictions with annotations.

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 covering purpose, usage, and return format with no redundant words. Information is front-loaded and each sentence adds value.

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

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

Given no output schema, description explains return structure. Covers both parameters and pairing actions. Could mention performance implications but adequate 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%, but description adds meaning by explaining the return shape and that max_issues controls output count. For source_session, clarifies behavior when omitted.

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 specifies scanning for specific quality issues (generic names, type mismatches, etc.) and distinguishes from sibling tools like graph_audit or graph_contradictions. It clearly states the tool's function of validating graph entities after extraction.

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 says 'Call this after a dream process extraction batch' and suggests pairing with graph_delete or graph_unmerge. Does not provide exclusions or alternatives, but context is clear.

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?

Describes persistence, clamping at 0.0, and error if edge doesn't exist. Adds value beyond annotations (idempotentHint) with concrete behavioral details.

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

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

Four sentences, each essential and front-loaded. No wasted words.

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

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

Covers purpose, usage, behavior, and alternatives. Missing output schema but tool's effect is straightforward; description suffices for correct use.

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

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

Schema covers all parameters with descriptions; description does not add significant new meaning beyond schema. Baseline 3 due to 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?

Clearly states the action (decrease edge weight) and context (user correction of recalled fact). Distinguishes from siblings like graph_delete and graph_relate with SUPERSEDES.

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 says when to call (user says 'no', 'that's wrong') and when not to (use graph_delete for removal, graph_relate for replacement). Provides clear alternatives.

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