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 only declare readOnlyHint=true; the description adds substantial context beyond that — the greedy seed-based BFS algorithm, the fact that no GDS/APOC is required, the exclusive-assignment rule (each entity joins the first community that reaches it from a high-degree seed), the hard cap of 30 listed members, and the exclusion of communities below min_size. These are exactly the behavioral traits an agent needs to interpret results correctly.

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?

Front-loaded with the purpose and algorithm, then the return shape, then the alternative-tool routing — a sensible order. It is dense rather than padded, though the long parenthetical schema sketch of the community object is heavier than strictly necessary and could have been tightened.

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

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

There is no output schema, so the description carries the full burden of explaining returns and does so precisely: the top-level `{communities, coverage}` shape, each community's fields, the 30-member truncation, and the `{total_entities, assigned, unassigned}` coverage counters. Nothing an agent needs to call or interpret this tool 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%, so the baseline is 3, but the description adds real meaning: it explains that communities come back 'in seed order (highest-degree seed first)', that communities below min_size are dropped, and that member lists are truncated at 30 regardless of member_count. max_hops and weight_threshold are only lightly echoed beyond the schema, which keeps this short of a 5.

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

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

States a specific verb and resource ('Find clusters of densely-interconnected entities in the graph') and immediately distinguishes itself from the traversal siblings by naming graph_query and graph_search. An agent can tell this is a whole-graph community-detection tool rather than a lookup tool without opening any 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?

Gives a concrete use case ('understanding knowledge neighbourhoods, e.g. everything related to infrastructure') and an explicit exclusion rule: use graph_query or graph_search when you already have a specific entity to start from. That is a clear when-to-use and when-not-to-use routing decision.

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?

Although the only annotation is destructiveHint=true, the description adds the irreversibility and how to recover, the exemption for rule-subtype nodes and their edges, and a special dry_run behavior where edges_decayed is always 0. These details go well beyond what annotations disclose and directly affect how the agent calls the 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?

The description front-loads what the tool does, then the usage warning, then the exemption, then the return shape. Every sentence carries information the agent needs, 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?

Despite there being no output schema, the description gives the full return shape inline. Combined with the irreversibility warning and the exemption rule, the agent has everything it needs to call this destructive maintenance tool safely.

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 only one parameter, and the schema already covers dry_run at 100%. The description reinforces its meaning with the warning to preview first and the detail that dry_run reports edges_decayed as 0, which is a meaningful behavior beyond the schema text.

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 gives a specific verb and resource: applying time-based decay to node confidence and edge weights with per-type half-lives, and it illustrates it with concrete examples (~693d for preferences, ~99d for events). That is far more specific than the name alone. However, it never explains how it relates to its close siblings graph_boost and graph_weaken, so the agent must infer which one to use.

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 states the context in which the tool runs ('called by the dream process during maintenance') and gives an explicit precondition: preview with dry_run=true first, and make a graph_export backup because decay is irreversible. This tells the agent exactly how to proceed and which related tool to use first.

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?

Annotations only declare idempotentHint, and the description adds substantial beyond that: async pickup by a nightly dream process, overwrite semantics on duplicate queueing, an admin-tenant restriction on inline content, and a filesystem-reachability constraint for remote callers. It also discloses what status returns (session_cursors), which the agent could not otherwise know.

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?

Front-loads the primary action and mode split, then layers constraints; every sentence carries information. The closing session_cursors sentence is dense and packs several clauses, slightly reducing scannability, but it is not wasteful.

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

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

With no output schema, the description carries the return-value burden and does describe status output (session_cursors semantics). It stops short of describing what queue returns on success or failure, which would fully close the loop for a tool with five parameters and nested meta.

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 already 100%, so the baseline is 3; the description rises above it by explaining the rationale behind file_path versus content+file_name (remote callers can't reach the server filesystem) and the admin-tenant gating. Minor deduction because it refers to the action parameter as 'mode', which doesn't match the schema's parameter name and could momentarily confuse an agent mapping prose to fields.

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 ('Queue a document for asynchronous extraction into the memory graph') and explicitly covers the second mode ('check the ingest backlog'). The distinction between the two modes and the named sibling graph_relate makes it unambiguous against the many graph_* siblings.

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

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

Gives explicit when-to-use ('file the user wants summarized into the graph but doesn't need reflected in the same conversation') and when-not-to-use with the alternative named ('For inline assertions during a conversation, call graph_relate directly instead'). Nothing is left to inference about routing.

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 already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavior: local bge-small-en 384-dim embeddings with no external API call, a hard failure mode when the embedder is missing, and expansion limits (top 5 seeds, 30-edge cap). It stops short of describing output shape or whether similarity scores are returned.

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 with zero filler: capability first, then the discriminating use case, then the failure mode with an alternative, then the expansion caps. Every sentence carries distinct information an agent would otherwise have to guess.

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 exists, and the description only loosely implies the return is seed entities plus neighbours, without stating fields such as similarity values or entity identifiers. Given six parameters and a dual-mode operation, that is the one meaningful hole; everything else an agent needs to call it correctly 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 description coverage is 100%, so baseline is 3. The description goes past the schema by clarifying that expansion is anchored to only the top 5 seeds and capped at 30 edges — a constraint not derivable from the top_k, expand, or expand_min_weight fields themselves — which materially affects how an agent should size top_k.

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: find entities semantically similar to a natural-language query, with optional graph expansion. The dual mode (semantic seed retrieval + traversal) is named up front, and the concrete examples ("containers" → Docker, "AI tools" → Claude Code/Anthropic SDK) pin down what "semantically similar" means in practice, distinguishing it from graph_query.

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 gives the selection condition: "Best when the user's wording doesn't match canonical entity names." It also names the fallback path — if the embedder is unavailable it errors and the agent should use graph_query — which is exactly the when-not guidance an agent needs to route between 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?

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?

Goes well beyond the sole readOnlyHint annotation: it discloses the return shape {total_issues, by_severity, scope, issues}, the per-issue record fields, the severity taxonomy, and the max_issues cap on result size. It also clarifies scoping semantics (omit source_session to scan the whole graph) and marks the operation as read-only with suggested remediation tools.

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 purpose, then timing, then return contract and remediation. Every clause carries information an agent needs; there is no restatement of the title or filler.

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

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

No output schema exists, and the description compensates fully by documenting the response structure, severity levels, and truncation behavior. Combined with the scoping note and remediation pairing, an agent has everything needed to call it and act on the results.

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 still adds meaning by tying max_issues to the returned issues array ('up to max_issues records') and by restating the source_session scoping rule in terms of the scan's coverage, which helps an agent reason about results rather than just pass values.

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

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

States a specific verb (scan) and resource (recently extracted entities and edges) and enumerates the exact defect classes it looks for: generic names, reference language, isolated low-confidence entities, near-duplicates. This distinguishes it from sibling diagnostics like graph_contradictions or graph_audit without needing to open any 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?

Gives a concrete trigger ('after a dream process extraction batch') and a rationale ('before it settles into the graph'), plus explicit follow-up routing to graph_delete/graph_unmerge. It stops short of naming the other read-only diagnostics (graph_audit, graph_contradictions) as alternatives to prefer when the concern is different, so the when-not-to-use side is implied rather than stated.

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.