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

With no annotations provided, the description carries the full behavioral disclosure burden and does so well: it warns that 'Documents already in progress will be marked FAILED' and documents the not_busy return case. It could add a bit more context about idempotency or what happens to queued documents, but the key side effects are disclosed.

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

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

Three short sentences, each with a distinct job: state the action, disclose the destructive side effect, and provide pre-call guidance. There is no filler or repetition, and the core purpose 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?

For a zero-parameter cancellation tool with an output schema present, the description covers the essential context: what gets cancelled, what happens to in-progress documents, what to check beforehand, and what is returned when nothing is running. Nothing needed to invoke the tool correctly is missing.

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

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

The tool has zero parameters, so there is no parameter meaning for the description to clarify. The schema is empty and fully covered, and the description correctly focuses on behavior rather than inventing parameter details. Baseline 4 applies for a zero-parameter tool.

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 names a specific action ('Request cancellation') and a specific resource ('currently-running indexing pipeline job'), making it clear what the tool does. It also distinguishes this from the many read-only siblings like get_pipeline_status and get_scan_status by focusing on the cancellation side effect.

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 instructs the agent to 'Use get_pipeline_status first to see what would be cancelled', giving clear pre-call guidance. It also explains the not_busy return value, which tells the agent when the tool is unnecessary because nothing is running.

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

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

No annotations are provided, so the description carries the burden. It implies a read-only check but does not explicitly state side-effect-free behavior, permissions, or return format. Since output schema exists, return format is covered, but the description lacks explicit behavioral disclosure such as 'does not modify the graph'.

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

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

Two sentences, front-loaded with the core purpose and then usage guidance. 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?

Given the single parameter and existence of output schema, the description provides the essential usage context. It doesn't cover edge cases like case sensitivity, but that's a minor gap for a simple check tool.

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

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

Schema covers the only parameter 'name' with description 'Exact entity name to check.' The description adds no new information beyond the schema, so 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 'check' and resource 'entity existence' with scope 'exact name in knowledge graph'. Clearly distinguishes from siblings like create_entity and edit_entity by naming them in usage.

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 instructs to call before create_entity or edit_entity to avoid collision, providing clear when-to-use context. No exclusions mentioned, but the guidance is actionable.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the operation is destructive, permanent, and cannot be undone, and it instructs the agent to confirm with the user. It also implies the default behavior of the two boolean parameters (off by default to preserve cache/parsed files), which adds behavioral context beyond the schema.

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 with zero waste. The destructive warning is front-loaded, the permanence is stated, and the user-confirmation instruction is included. Every sentence earns its place.

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

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

For a destructive bulk operation with an output schema and fully documented parameters, the description covers the critical safety context. It could mention what the response contains or whether the operation is synchronous, but the output schema likely covers return values, and the safety-critical information is complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds the context that both are off by default to preserve reusability, which is helpful but not a major addition beyond the schema's own descriptions.

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

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

The description states a specific verb ('deletes') and resource ('EVERY document in the knowledge base'), and the DESTRUCTIVE label plus 'permanently' makes the scope unmistakable. It clearly distinguishes itself from sibling delete_documents by targeting all documents rather than a subset.

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

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

The description explicitly says to confirm with the user before calling, which is a clear usage guideline. It doesn't explicitly name alternatives or when-not-to-use, but the destructive nature and confirmation requirement provide adequate context for an agent to know this is a last-resort operation.

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 the full burden of behavioral disclosure. It reveals that this is a mutating operation and warns about duplicate risk, but it does not explain what happens if a duplicate is attempted, whether the operation is idempotent, or what side effects occur beyond creation.

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 compact, focused sentences with no filler. The core action is front-loaded and the essential safety instruction follows immediately with no wasted wording.

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 is adequate for a simple create operation given full schema coverage and an output schema, but it is incomplete for a mutation with no annotations. It leaves unclear how duplicate entities are handled and what error or response behavior to expect, which an agent would need to invoke the 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?

Schema description coverage is 100%, so the input schema already documents both parameters, including uniqueness for entity_name and an example for entity_data. The description reinforces the uniqueness concern but does not add new parameter-level meaning.

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 ('Create'), a clear resource ('a new entity in the knowledge graph'), and a distinct scope that separates it from sibling tools like create_relation or create_document. An agent can tell exactly what action this tool performs.

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 instructs the agent to call check_entity_exists first to avoid unintended duplicates, which is a concrete and valuable usage guideline. It does not state when not to use this tool or mention alternatives like edit_entity, so it misses the bar for a full 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'create a relationship' and gives no information about idempotency, behavior if the relation already exists, directionality enforcement, or any side effects. This is a significant gap for a mutation tool.

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

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

The description is a single, front-loaded sentence that delivers the essential purpose and constraint with zero wasted words. It earns its place completely.

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 output schema exists and the parameter schemas are thorough, the description covers the core prerequisites. However, because there are no annotations, the lack of behavioral context (e.g., duplicate handling) leaves part of the tool's behavior unspecified, making it adequate but not fully complete.

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

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

Schema description coverage is 100%, so the input schema already fully documents all three parameters. The description adds no parameter-level details beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description states a clear action ('create') on a specific resource ('relationship between two entities') and includes a crucial constraint ('both already exist'), which distinguishes it from create_entity and edit_relation. An agent can immediately tell this tool is for new relations between existing nodes.

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

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

The phrase 'both already exist' implies the precondition for using this tool and hints that entities must be created first with create_entity. However, it does not explicitly name alternatives or state when not to use it, such as when editing an existing relation with edit_relation. Usage is inferred rather than 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?

With no annotations provided, the description carries full burden. It explicitly discloses destructive nature ('DESTRUCTIVE', 'permanently deletes'), irreversibility ('cannot be undone'), and async behavior ('runs in the background'), plus associated data deletion. This exceeds typical expectations and fully covers behavioral disclosure.

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

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

The description is three sentences, front-loaded with 'DESTRUCTIVE' to immediately signal risk. Every sentence adds value: destructive scope, irreversibility, and async confirmation steps. 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 has an output schema (as indicated) and no annotations, the description covers essential behavioral context: destructive nature, async execution, and post-verification steps. It does not omit critical details an agent needs to use it correctly, such as permanent deletion and confirmation mechanism.

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 schema already documents all parameters (doc_ids, delete_file, delete_llm_cache). The description does not add parameter-specific detail beyond the schema, so a baseline of 3 is appropriate. It does not introduce ambiguity or missing semantics.

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

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

The description states a specific verb ('deletes') and resource ('documents'), and clarifies scope ('permanently deletes documents and all their associated data'). It distinguishes from siblings like delete_entity and clear_all_documents by specifying it targets documents and their related data.

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 post-usage guidance ('use get_track_status or list_documents afterward to confirm') but does not explicitly contrast with alternative deletion tools (e.g., clear_all_documents). While context is clear, it lacks explicit when-not-to-use guidance relative to siblings.

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

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

No annotations are provided, so the description carries the full burden. It clearly discloses the destructive, permanent, cascading nature of the operation and warns that it cannot be undone. It does not mention verification, but for a one-parameter destructive tool this is strong transparency.

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

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

The description is two short sentences with the critical warning front-loaded. Every word adds value, and there is no redundant 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?

For a simple destructive operation with one parameter and an output schema, the description is nearly complete. It covers permanence and cascading effects, which are the key risks. It does not address missing-entity behavior, but that is unlikely to be essential for correct 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?

The schema already fully documents the single parameter with 100% coverage, so the baseline is 3. The description adds that deletion covers the entity and its relationships, but it does not clarify matching behavior or edge cases. No additional parameter guidance is strictly necessary.

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

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

The description states a specific verb ('deletes'), a specific resource ('entity'), and a clear scope ('all its relationships from the knowledge graph'). It is easily distinguished from siblings like delete_relation or delete_documents.

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

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

The description implies when to use this tool: when an entire entity and its relationships must be removed. However, it does not explicitly mention when not to use it or name alternatives, such as delete_relation or merge_entities, which would be useful given the large sibling set.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly labels the operation as DESTRUCTIVE, states that it cannot be undone, and scopes exactly what is deleted (the relation, not the entities). This is strong transparency for a destructive tool, though it does not mention permission requirements or potential side effects.

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

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

The description is two sentences with no filler. The 'DESTRUCTIVE' warning is front-loaded, followed by the precise scope of the operation and the irreversibility note. Every sentence contributes essential 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?

The tool is simple, the schema fully documents its two required parameters, and an output schema exists. The description provides the critical behavioral warnings and scope clarification, so nothing essential is missing for correct 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?

The input schema already provides complete descriptions for both parameters, source_entity and target_entity, with 100% coverage. The description adds no parameter-specific detail beyond the general notion of a relationship between two entities, so the baseline score of 3 applies.

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

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

The description uses a specific verb and resource: 'permanently deletes the relationship between two entities from the knowledge graph.' It also explicitly distinguishes itself from delete_entity by clarifying that 'entities themselves are not deleted,' which prevents confusion with a key sibling tool.

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 makes the intended use clear: removing a relationship while preserving the entities. It does not explicitly name alternatives such as create_relation or edit_relation, but the 'entities themselves are not deleted' clause provides useful context for deciding between this and delete_entity.

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

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

No annotations are provided, so the description carries the burden. It discloses the merge-on-rename behavior, which is a key behavioral trait. However, it doesn't mention side effects like whether merging deletes the original entity, whether updates are reversible, or what happens on failure. The description adds some context beyond the schema but lacks depth for a mutation tool.

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

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

The description is a single, compact sentence that front-loads the primary action ('Update an entity's properties') and adds the optional rename/merge behavior. It's efficient with no wasted words, though it could be slightly more structured with a second sentence for edge cases.

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

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

The tool has 4 parameters, an output schema, and nested objects, but no annotations. The description covers the core behavior and the merge nuance, but doesn't explain return values (though output schema exists), failure modes, or permission requirements. For a mutation tool with no annotations, this is adequate but not complete.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds the high-level behavior of renaming and merging, which maps to allow_rename and allow_merge, but doesn't add detail beyond the schema. The schema's updated_data description lists accepted fields, and the description's 'properties' phrase aligns with that. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Update an entity's properties, optionally renaming it (and merging it into an existing entity of the same new name, if allowed).' This distinguishes it from sibling tools like create_entity, delete_entity, and merge_entities, though it doesn't explicitly name them. The verb 'update' and resource 'entity' are specific and clear.

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

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

The description implies usage context: use this to update properties or rename an entity, with optional merging. It doesn't explicitly state when to use this vs. alternatives like merge_entities or edit_relation, but the optional merge behavior is mentioned. The 'if allowed' phrase hints at constraints but doesn't detail them. No explicit exclusions or alternative tool names are given.

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

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

Annotations are absent, so the description carries the full burden of behavioral disclosure. It only states 'update properties' without explaining side effects, error handling, whether missing relationships are created, or permission requirements. For a mutation tool, this is a significant gap.

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

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

The description is a single, concise sentence with no redundancy. It is front-loaded with the core action and resource. While it lacks detail, it is not verbose, and the structure is efficient.

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

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

For a mutation tool with no annotations and no output schema details, the description is too sparse. It does not explain what happens on success, what errors might occur, or the expected behavior when the relationship does not exist. An agent cannot fully anticipate the tool's effects or edge cases.

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

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

Schema description coverage is 100% for all three parameters, so the schema already defines each parameter's purpose. The description adds no extra semantic nuance beyond what the schema provides, aligning with the baseline score of 3 for high schema coverage.

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

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

Description states a clear verb ('Update') and resource ('properties of an existing relationship between two entities'). It implicitly distinguishes from create/delete siblings by specifying 'existing', though it does not name any sibling explicitly. The resource is specific enough for an agent to identify the tool's role.

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

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

No guidance is provided on when to use this tool versus alternatives like create_relation or delete_relation. The description does not mention prerequisites (e.g., relationship must exist) or conditions that would make another tool more appropriate. This leaves the agent to infer usage from the name alone.

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

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

With no annotations provided, the description carries the full behavioral burden. It clearly discloses that the operation is destructive, irreversible, may reopen an inconsistent workspace, and safely no-ops when nothing is fenced.

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?

Every sentence earns its place: the destructive alert is front-loaded, the action and consequence are stated crisply, and the usage guardrail and no-op behavior finish it. The length is appropriate for the risk level.

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 destructive recovery action, the description covers why it exists, when to use it, what could go wrong, and the no-op path. The output schema existsasi and the single parameter is fully documented, so nothing essential is missing.

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

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

Schema description coverage is 100% and the single confirm parameter is already well documented in the schema. The tool description reinforces that the reset is destructive but does not add meaningfully new parameter semantics beyond what the schema provides.

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

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

The description names a specific verb and resource: 'force-clears a recovery_required fence'. It also clearly distinguishes this from siblings like cancel_pipeline and repair_source_conflict by framing the action as an un-doable recovery gate removal.

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

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

It explicitly says 'use only to recover a stuck pipeline' and 'only after checking get_pipeline_status first'. It also specifies the no-op condition, so an agent knows when the call is unnecessary.

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

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

With no annotations, the description carries the disclosure burden. It communicates non-mutating aggregation and a performance trait ('fast, low-context'), which is useful behavior beyond the schema. It does not list every possible status or zero-count behavior, but the output schema supplies the return detail.

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 focused sentences: the first states exactly what the tool returns, the second adds routing context. Every clause earns its place and the 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?

For a zero-parameter, count-only endpoint with an output schema, the description fully covers what an agent needs: what it returns, why it is preferable, and which sibling to choose instead. There are no missing prerequisites or failure modes that would be expected at this complexity level.

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 takes no parameters, and the schema has no properties, so the zero-parameter baseline of 4 applies. The description needs to add no parameter-level meaning because there is nothing to configure.

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

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

The description states a specific verb and resource: it gets counts of documents grouped by processing status. It also explicitly positions itself against list_documents, so an agent can distinguish it from sibling tools without opening schemas.

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

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

It gives an explicit when-to-use rule: prefer this tool when only counts are needed, and names list_documents as the alternative for when more detail is required. This is direct 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?

With no annotations, the description must carry the behavioral burden. It usefully discloses that output 'can be long on a large knowledge base' and that the result is 'currently' in the graph, implying a live snapshot. It does not explicitly mention read-only behavior or pagination, but the read-only nature is strongly implied by 'List' and the output schema covers the return structure.

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

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

Two sentences, no filler. The core purpose is front-loaded, and the second sentence adds an actionable caveat plus alternative tool names. Every word earns its place.

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

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

For a zero-parameter read-only listing tool with an output schema, the description is fully sufficient. It states what is returned, warns about scale, and directs users to more targeted siblings when appropriate.

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 zero parameters, so the baseline is 4. The description correctly adds no parameter information because none is needed; the empty schema already fully covers the parameter space.

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

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

The description uses a specific verb ('List'), a clear resource ('entity label (name)'), and a precise scope ('every ... currently in the knowledge graph'). It also differentiates itself from sibling tools by emphasizing 'every', which distinguishes it from get_popular_labels and search_labels.

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

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

The description gives explicit when-not-to-use guidance: 'Can be long on a large knowledge base -- prefer get_popular_labels or search_labels when looking for something specific.' This clearly routes an agent to the appropriate alternatives while implying this tool is for complete enumeration.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It adds valuable transparency by explaining truncation priority: nodes closer to the label and more connected nodes are kept first when max_nodes is exceeded. However, it does not mention potential side effects (though read-only is implied) or clarify whether edges are also subject to truncation.

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 one efficient sentence that leads with the core action and resource, then immediately provides the key behavioral detail about truncation. There is no filler or repetition of schema 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?

The tool is a straightforward read-only retrieval operation with an output schema, so the description does not need to explain return values. It covers the essential behavior (subgraph retrieval and truncation policy). The only minor gap is the lack of explicit usage guidance or alternative routing, which is already factored into the usage_guidelines score.

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 3UTE-ND. The description adds meaningful parameter semantics for max_nodes by explaining how nodes are selected when the graph exceeds the limit, which goes beyond the schema's simple 'Maximum number of nodes to return'. label and max_depth remain adequately covered by the schema.

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

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

The description states a specific verb ('Retrieve') and resource ('connected subgraph (nodes and edges) around one entity label'). This clearly distinguishes the tool from sibling graph-label tools like get_graph_labels, search_labels, and get_popular_labels, which focus on labels rather than the full graph structure.

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

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

The description implies the tool should be used when a connected subgraph around an entity label is needed, but it does not explicitly mention any alternatives or when NOT to use it. No exclusions, prerequisites, or comparative guidance is given, so the usage context is only implied.

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

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

With no annotations, the description carries the behavioral burden. It discloses that by default only a short summary of the last 10 history lines is returned, not full internal state, and that verbose returns raw full status that can be tens of kilobytes. This gives an agent important expectations about cost and output 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?

Two sentences with no wasted words: the first states the resource and what the tool reports, the second immediately gives the default behavior and the condition for changing it. Every clause earns its place.

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

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

For a simple read-only status tool with a single optional parameter and an output schema, the description is complete. It covers default behavior, verbose alternative, size caution, and the type of information returned, so an agent can invoke it correctly without further clarification.

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 for the single verbose parameter is 100% and the schema description already explains the condensed-vs-full distinction. The description adds value beyond the schema by instructing when to use verbose (only if summary is not enough) and warning about the potentially large response, which helps an agent decide parameter choice.

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 names a specific resource (LightRAG's indexing pipeline) and verb (check), and enumerates exact outputs: busy/idle, job name, progress, recent status messages. It also frames the query 'what is LightRAG processing', which separates it from sibling status tools like get_scan_status and get_track_status.

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 to use this for 'what is LightRAG processing' and instructs that verbose=true should be used only when the summary is not enough. It does not explicitly name sibling alternatives or say when another status tool should be preferred, so exclusions are missing.

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

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

With no annotations present, the description carries the behavioral disclosure burden. It transparently explains the sort criterion (node degree), the ordering direction (most-connected first), and the intended interpretation of 'popular.' It does not cover edge cases like isolated labels or exact count semantics, but the core behavior is clearly disclosed.

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

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

The description is a single well-structured sentence that front-loads the key sorting behavior and follows it with a concise, useful rationale. There is no redundant filler or excessive length.

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

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

Given the tool's low complexity (one optional parameter, full schema coverage, and an output schema present), the description is largely sufficient for an agent to select and invoke it correctly. It could add an explicit pointer to sibling tools or mention response shape, but the output schema compensates for the latter.

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

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

The schema fully documents the only parameter, limit, including its default, range, and meaning. The description does not add parameter-specific details beyond what the schema already provides, so the 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?

The description states a specific verb ('List') and resource ('entity labels'), and clarifies the distinguishing behavior: sorting by node degree, most-connected first. It clearly signals a popularity-oriented view rather than generic label listing, though it does not explicitly name sibling 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 phrase 'a quick way to see what the knowledge graph is mostly about' implies an overview/summary use case. However, it does not explicitly contrast with related sibling tools like get_graph_labels or search_labels, nor does it say when not to use this tool.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It discloses that the tool is a read-only status check and that it relates to a background process, but it doesn't describe what the response contains (e.g., progress percentage, state, error info) or whether the status is pollable. The output schema exists and may cover return values, but the description itself adds only modest 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?

The description is a single, focused sentence that front-loads the action ('Check the progress') and immediately provides the key context (background folder scan, started by `scan_documents`). 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?

For a simple one-parameter status-check tool, the description is nearly complete. It identifies the trigger (`scan_documents`), the required input (`track_id`), and the purpose. The output schema exists, so return values don't need to be described. A minor gap is not mentioning polling behavior or whether the tool is safe to call repeatedly, but the simplicity of the tool makes this a minor omission.

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 schema already documents the single parameter `track_id` as the tracking ID returned by `scan_documents`. The description reinforces this by mentioning the tracking ID, but it doesn't add new 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 tool's purpose: checking the progress of a background folder scan started by `scan_documents`. It uses a specific verb ('Check'), a specific resource ('progress of a background folder scan'), and explicitly references the initiating sibling tool, which distinguishes it from other status-related siblings like get_pipeline_status or get_track_status.

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

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

The description implies the usage context: use this tool after starting a scan with `scan_documents`, and it requires the tracking ID returned by that call. It doesn't explicitly state when not to use it or name alternatives, but the reference to `scan_documents` and the track_id parameter provide clear contextual guidance. A small gap is not mentioning that other status tools exist for different workflows.

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

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

No annotations are provided, so the description must carry the behavioral disclosure burden. While 'List' and 'Check' imply a read-only, non-mutating operation, the description does not explicitly state that it has no side effects, requires no auth, or its idempotency. For a query tool this is a minor omission, but without annotations a more explicit safety statement would be stronger.

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 tightly worded sentences: the first states the core function, the second provides situational usage. No filler, info is front-loaded, and each sentence earns its place.

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

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

The tool has no parameters and an output schema (not shown), so the description doesn't need to explain return structure. It tells the agent what the tool returns (extensions and parser engine) and when to call it. For its simple scope, this is complete.

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

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

The tool has zero parameters, so baseline is 4. The description adds no parameter-specific semantics (there are none), but it does clarify the output focus (extensions and parser engine), which indirectly informs what the empty call returns. Given the baseline for no params, this 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 states a specific verb ('List'), a clear resource ('file extensions LightRAG accepts'), and adds detail about the parser engine per extension. It distinguishes this from siblings like `upload_file` by focusing on the pre-check of supported types, making it unmistakable what the tool does.

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 instructs to 'Check this before `upload_file`' and provides a condition ('if the file's extension is not obviously supported'), giving immediate, actionable guidance on when to use it. Names the sibling it pairs with, eliminating ambiguity.

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

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

No annotations are provided, so the description carries the full behavioral burden. It clearly implies a read-only check and tells the caller what outcome is reported, but it does not disclose polling/blocking behavior, eventual-consistency semantics, error cases, or whether calling it has side effects beyond implication.

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

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

One tightly worded sentence front-loads the action and resource, then uses a dash to add the precise usage context. There is no filler or redundancy.

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

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

For a tool with a single required parameter that is fully schema-documented, plus an output schema, the description provides sufficient context: when to call it, what it operates on, and what question it answers. Nothing essential is missing.

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

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

Schema description coverage is 100%: the schema already explains that track_id is the tracking ID returned by the ingestion tools. The description adds workflow context but no new parameter-level detail such as format, length, or examples, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Check') and resource ('processing status of the document(s) associated with a track_id'), and embeds the workflow context ('after insert_text/insert_texts/upload_file') so an agent can tell this tool apart from other status-oriented siblings like get_pipeline_status or get_scan_status.

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 states when to use the tool: after insert_text/insert_texts/upload_file, and what question it answers ('whether indexing finished, and whether it succeeded'). It does not explicitly mention when not to use it or name alternatives, so it falls just short of a 5.

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

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

With no annotations, the description carries full behavioral burden. It discloses the internal mechanism (calling get_document_status_counts), states that failures from that call are allowed to raise, and guarantees 'this tool never reports healthy while authentication is broken.' This is highly transparent about what the tool does under the hood.

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 key behavior is front-loaded in the first sentence, and the subsequent explanation of why GET /health is insufficient is valuable context. The historical reference to the 'old lightrag-mcp wrapper's exact trap' is slightly non-essential but still reinforces the tool's purpose without bloating the description.

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

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

For a zero-parameter health check with an output schema present, the description covers everything an agent needs to know: what it checks, how it works, and what guarantees it provides. The return format is handled by the output schema, so no further explanation is needed.

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 zero parameters, so the schema provides nothing to document. The description correctly focuses on behavior rather than parameters. The baseline 4 applies because no parameter information is needed or missing.

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

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

The description opens with a specific verb and resource: 'Check whether LightRAG is reachable AND whether this server's credentials actually work.' It clearly distinguishes this tool from the raw GET /health endpoint and from the old wrapper, so an agent can tell exactly what it does and why it differs.

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

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

The description explicitly says 'GET /health alone is not enough' and explains why, which tells the agent when not to rely on the simple liveness probe. It also states that this tool calls get_document_status_counts to enforce auth, effectively positioning itself as the proper health check when credentials need verification.

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

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

With no annotations provided, the description discloses the key asynchronous behavior (indexing happens later; returns a track_id to poll). It does not mention side effects or authorization, but for a non-destructive text insertion this is adequate.

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 that front-load the main action and then provide the essential follow-up instruction. No filler or redundant content.

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

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

The description fully explains the call and the next step (polling get_track_status), and the existing output schema covers the track_id return. The only missing piece is explicit mention of when to prefer insert_texts, which is already captured in usage guidelines.

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 both parameters are already documented (text non-empty; file_source for attribution). The tool description adds no parameter-level meaning beyond 'single piece of raw text', matching the baseline for fully covered schemas.

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 names the specific operation 'Insert a single piece of raw text into the knowledge base' with the explicit resource (knowledge base) and distinguishes it from insert_texts by specifying 'single' and from file uploads by 'raw text'.

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

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

It gives clear workflow context: use for raw text, and after the call poll with get_track_status to await indexing. It does not explicitly enumerate alternatives like insert_texts for multiple pieces, so it stops short of a 5.

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

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

With no annotations, the description carries the behavioral burden. It discloses batch-level tracking via a single track_id and directs the caller to poll get_track_status, which surfaces an asynchronous workflow. It does not discuss partial-failure behavior or side effects, but the core execution model is transparent.

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

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

Two sentences with no filler. The core action is front-loaded, and the return/status contract is stated compactly in the second sentence. Every word contributes.

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 low complexity (two params, one required), full schema coverage, and an output schema, the description covers input, return value, and polling flow. The only notable gap is explicit routing among the sibling insert/upload tools, but the batch semantics are sufficiently clear.

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 schema already documents texts and file_sources well. The main description adds no parameter details, but the schema's file_sources description goes beyond basic semantics by advising to always set it for query() provenance. 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?

States a specific action ('Insert multiple pieces of raw text into the knowledge base'), a clear resource ('knowledge base'), and a distinguishing scope ('multiple... in one call'). This differentiates it from the sibling insert_text and upload_file tools without needing to inspect schemas.

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

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

The description implies batch usage and provides follow-up guidance ('poll with get_track_status'), but it does not explicitly contrast with insert_text or state when the batch variant should be preferred over alternatives. Usage context is present but alternatives/exclusions are left to inference.

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

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

No annotations are provided, so the description carries the full burden. It discloses pagination behavior, the trimmed per-document summary fields, total_count and has_next, and the critical failure semantics (LightRAG unreachable vs. zero documents). It doesn't mention rate limits or auth, but for a read-only listing tool the disclosed behavior is substantial.

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

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

Three sentences, front-loaded with the core purpose, then the critical failure-mode warning, then the return shape. Every sentence earns its place and the most important behavioral caveat is placed early.

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 paginated list tool with a rich output schema and 100% parameter coverage, the description covers purpose, usage, failure semantics, and return shape. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 5 parameters. The description adds context about pagination and the return shape but doesn't add meaning beyond the schema for individual parameters. 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 states a specific verb ('List documents in the knowledge base') and resource, and explicitly distinguishes this tool from the failure mode of concluding the knowledge base is empty. It also names the return shape, making it clear this is the listing tool among siblings like scan_documents or get_document_status_counts.

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

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

The description explicitly says this is the tool to use for 'how many documents are there' or 'list the documents', and warns against misinterpreting a tool failure as an empty knowledge base. This gives clear when-to-use guidance and a critical exclusion (do not conclude empty on failure).

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

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

With no annotations, the description carries the behavioral disclosure burden. It explains that conflicts are deliberately not auto-resolved because picking a winner could retire the wrong document, which is important context. It does not fully disclose side effects or auth requirements, but the verb 'List' strongly implies a read-only operation.

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

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

Two focused sentences: the first front-loads the purpose and definition, the second provides the rationale and names the resolver tool. No filler or repetition.

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 definition is complete for a paginated list tool: output schema exists, parameters are documented in the schema, and the associated repair tool is pointed to. Nothing necessary for correct invocation is missing.

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

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

Schema coverage is 100%, and both limit and cursor already have descriptions in the schema. The tool description adds no parameter-specific meaning, which is acceptable because the schema fully documents them.

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 states a specific verb and resource ('List documents whose source file name collides') and defines the term 'source conflict'. It is clearly distinguishable from the sibling repair_source_conflict and from generic list_documents.

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 explains when this tool is appropriate—when conflicts were never auto-resolved—and gives the alternative: 'Use repair_source_conflict to resolve one.' It also provides the rationale for why this tool exists in the first place.

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 explicitly discloses the two most critical behavioral traits: the merged-from entities are removed upon success, and the operation cannot be undone. It also warns the agent to double-check names first. Since no annotations are provided, the description carries the full burden, and it does so excellently by surfacing destructive, irreversible behavior.

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

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

Two sentences with zero waste. The core action is front-loaded, and the critical warning (removal + irreversibility) is placed at the end for emphasis. Every word earns its place.

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

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

The description is complete for a destructive merge operation: it states the action, the outcome, the removal behavior, and the irreversibility. The output schema exists, so return values need not be described. The only minor gap is that it doesn't explicitly state what happens to the target entity's existing relationships, though the schema's 'Created if it doesn't already exist' partially covers this.

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 schema already documents both parameters well. The description adds context by framing the parameters as 'duplicate or misspelled entities' and 'target entity', but it does not add significant new 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 states a specific verb ('Merge'), a specific resource ('duplicate or misspelled entities'), and a clear outcome ('into a single target entity'). It also distinguishes itself from sibling tools like create_entity, edit_entity, and delete_entity by describing a bulk merge-and-remove operation rather than a simple create/edit/delete.

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 clearly implies when to use this tool: when there are duplicate or misspelled entities that should be consolidated. It does not explicitly name alternative tools or state when not to use it, but the context of sibling tools (create_entity, edit_entity, delete_entity) makes the usage context reasonably clear. A brief mention of alternatives would push this to 5.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the tool retrieves context, has an LLM compose the answer, and returns response and references by default. It does not cover cost, latency, or how flags like only_need_prompt alter behavior, which limits transparency.

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

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

The description is three sentences with the core action front-loaded and no wasted words. It efficiently states purpose, usage context, and return values.

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

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

For a tool with 17 parameters and an output schema, the description covers the central purpose and return shape well, while the schema handles parameter details. It does not mention sibling query_data or prerequisites like needing ingested documents, but these are secondary given the other available 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 input schema has 100% description coverage, so all 17 parameters are already documented in structured form. The description does not add parameter-level meaning beyond the schema, which justifies the baseline score of 3.

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 answers a question using the knowledge base (RAG) over LightRAG content, with a specific verb and resource. However, it does not distinguish this tool from the sibling query_data, so the differentiation is not explicit.

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

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

The description explicitly says 'Use this for any question about the content stored in LightRAG,' giving clear context for when to invoke it. It does not mention alternatives or when not to use the tool, so it stops short of a 5.

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

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

Discloses two non-obvious behaviors: it does not invoke LightRAG's LLM to compose an answer, and the result always includes references. However, no annotations exist, so the description carries the full transparency burden for a retrieval tool, and it omits the `bypass`-mode exception and any read-only/no-side-effect caveat.

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

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

Three short, purposeful sentences: core behavior, when-to-use rule, and return guarantee. Everything is front-loaded, with no filler or repetition of schema content.

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

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

For a 13-parameter tool, the schema covers parameter semantics and the output schema covers return shape, so the description only needs selection guidance and high-level behavior. It supplies that, including the key `query` alternative; the only gap is the unqualified no-LLM claim versus the `bypass` mode.

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 13 parameters including mode semantics, so the description adds no parameter-level meaning. The description's mention of 'raw entities, relationships and text chunks' is high-level context rather than parameter guidance, matching the baseline for fully documented schemas.

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 ('retrieve') and resource ('raw entities, relationships and text chunks'), and distinguishes itself from the `query` sibling by saying the LLM does not compose an answer. The wording is slightly overbroad because the schema's `mode` enum includes `bypass`, which sends the query straight to the LLM, contradicting the absolute 'WITHOUT' claim.

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 to use this tool instead of `query` when the caller wants to compose its own answer from retrieved evidence, naming a concrete caller (Hermes). This provides a clear, actionable routing rule with no inference required.

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

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

No annotations exist, so description carries the burden. It discloses the mutation is not trivially undone, clarifies content is not deleted, and describes the dry-run/commit safety check. It doesn't state permissions/auth needs, but for a tool whose main risk is irreversible metadata change, the disclosure is strong.

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

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

Three sentences, front-loaded with the core purpose, then safety caveat and operational instruction. No filler. Every clause earns its place.

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

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

Given the 5-parameter schema with full field descriptions and an output schema, the description covers the key operational guidance: source of inputs, dry-run discipline, and irreversibility. It could mention failure modes or permission requirements, but those are not essential for an agent to invoke correctly given schema 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 coverage is 100%, so baseline is 3. Description adds value by tying canonical_source_key and primary_doc_id to the list_source_conflicts output fields and by explaining the required dry-run-echo flow for expected_candidate_count/fingerprint. It doesn't describe the output schema, but output schema exists, so that's fine.

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 states a specific verb+resource ('Resolve a source-name conflict') and names where the conflict comes from (list_source_conflicts). It also distinguishes the action from siblings like merge_entities or delete_documents by defining the conflict domain precisely, so an agent can tell this is the repair action for source-name collisions.

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?

Description explicitly instructs to dry-run first before committing, warns that committing marks candidates as duplicates and cannot be trivially undone, and tells the agent to double-check the dry-run result. It also implicitly separates dry-run and commit flows, with schema enforcing expected_candidate_count/fingerprint on commit.

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

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

No annotations are provided, so the description carries the burden. It discloses the state scope (failed, pending, interrupted) and the non-rescanning behavior, which is useful. However, it doesn't disclose whether the operation is destructive, whether it re-queues documents, or what the return value looks like. The output schema exists but its content isn't shown, so the description could add more 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?

The description is a single, well-structured sentence that front-loads the core action and then adds a clarifying exclusion. Every word earns its place; no fluff or repetition.

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

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

For a zero-parameter tool with an output schema, the description is largely complete. It clearly defines the scope of documents affected and the non-behavior. The only minor gap is the lack of detail about what happens after retry (e.g., whether it's synchronous, whether it returns a summary), but the output schema likely covers that.

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 zero parameters, so the schema is trivially complete. The description adds meaning by explaining what the tool operates on (documents in specific states) and what it avoids (rescanning). With no parameters, the baseline is 4, and the description provides sufficient context.

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

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

The description clearly states the tool's purpose: retry documents in failed, pending, or interrupted states. It also explicitly distinguishes itself from scanning for new files, which differentiates it from sibling tools like scan_documents.

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

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

The description implies when to use this tool: when documents are in failed, pending, or interrupted states and need retrying. It also explicitly states what it does NOT do (rescanning the input directory), which helps rule out alternatives. However, it doesn't explicitly name alternative tools or provide exclusion criteria beyond the rescanning note.

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

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

With no annotations provided, the description carries full behavioral burden. It discloses that the operation is asynchronous, returns a track_id, and can be skipped with a specific status when the pipeline is busy. This is more than sufficient for an agent to understand side effects and expected 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, no filler. The core action is front-loaded, followed by return behavior and an edge-case refusal. Every sentence adds actionable 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 has no parameters and an output schema exists, the description covers the essential workflow: what the scan does, what is returned, how to follow up, and when a refusal may occur. Nothing important is missing for correct 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?

The tool has zero parameters, so the schema conveys everything about inputs. The description adds no param-specific semantics, but none are needed. The baseline of 4 for a zero-parameter tool applies.

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

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

The description states a specific verb ('Trigger'), a clear resource ('LightRAG's input directory'), and a precise action (scan for new files not yet indexed). It distinguishes itself from sibling tools like get_scan_status and upload_file.

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 clearly communicates when this tool is appropriate: when new files need to be scanned into the index. It also tells the agent what to do after calling it (poll with get_scan_status) and describes a busy condition. It does not explicitly state when not to use it or list alternative tools, but the 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?

With no annotations, the description carries the behavioral disclosure burden. It does reveal that matching is fuzzy and that the operation is a lookup, which is useful, but it doesn't mention ordering, uniqueness, case sensitivity, or whether the operation is safely read-only.

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 succinct sentences: the first states the core behavior, the second gives practical usage guidance. Every phrase earns its place, and the most important 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?

The tool is simple, has a full input schema and output schema, and the description explains its role relative to query and get_knowledge_graph. It could better distinguish from label-oriented sibling tools, but this is a minor gap given the simplicity of the operation.

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

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

Schema description coverage is 100%, so the input schema already documents q and limit clearly. The description reinforces that matching is fuzzy but adds no new parameter-level details beyond what the schema provides.

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

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

The description opens with a concrete verb and resource ('Find entity labels... fuzzy-matches'), making the action and scope clear. It doesn't explicitly distinguish this tool from label-related siblings like get_graph_labels or check_entity_exists, though the fuzzy-match framing helps.

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

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

The description gives a clear usage context: locate topic-related entities before calling query or get_knowledge_graph. It doesn't state when not to use the tool or explicitly name alternative siblings, but the intended placement in a workflow is evident.

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

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

With no annotations, the description carries the full burden, and it discloses important runtime behavior: per-file outcome reporting, unsupported files being skipped rather than erroring, and non-termination on individual file failures. It does not cover every edge case such as empty directories or permission errors, but the core behavioral traits are clearly surfaced.

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 compact sentences deliver the core action, the scoping rule, failure semantics, and the key alternative. Every clause adds value without repetition.

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 is sufficient for an agent to select and invoke the tool correctly: it specifies the target, single parameter, error behavior, and relationship to upload_file. The presence of an output schema covers return-value details, so nothing critical is missing.

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

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

Schema coverage is 100% and the single parameter is well documented as an absolute path inside the Hermes container. The description adds little beyond what the schema already states, so the 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 names a specific verb and resource ('Upload every supported file directly inside a directory') and contrasts itself with upload_file via 'Use this instead of calling upload_file in a loop,' making the distinction between sibling tools 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?

It explicitly tells the agent when to use this tool over an alternative: 'Use this instead of calling upload_file in a loop.' It also sets expectations about skipping unsupported extensions and continuing after failures, which is exactly the contextual guidance needed for correct selection.

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

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

With no annotations provided, the description carries the behavioral disclosure burden and does so well by revealing pre-upload validation (existence and extension checks) and the asynchronous return pattern via track_id. It does not mention permissions, idempotency, or overwrite behavior, but it discloses the most important non-obvious behaviors for a simple upload 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?

Three sentences with no filler: purpose, validation behavior, and follow-up action are each covered in one crisp sentence. The structure front-loads the core purpose and then layers in necessary operational details.

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

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

This is a single-parameter tool with a detailed input schema and an output schema present, so the description only needs to bridge the gaps. It covers prerequisites, return value, and next step, which is sufficient for an agent to invoke 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 schema already fully documents the path parameter with a container-path example, so the baseline is 3. The description adds meaningful context by stating the file must already exist on disk and have a supported extension, which clarifies constraints on the path parameter beyond the schema's format guidance.

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

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

The description states a specific action ('Upload and index'), a specific resource ('a single file already present on disk'), and clearly scopes the tool to one file at a time, which distinguishes it from the sibling upload_directory. The purpose is immediately understandable and unambiguous.

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

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

The description explicitly tells the agent to call get_supported_file_types first if unsure, and to poll with get_track_status after receiving a track_id. It also implicitly differentiates from upload_directory by emphasizing 'single file', giving clear context for when this tool is the right choice.

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