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

Annotations indicate the tool is not read-only and not destructive. The description adds value by disclosing merging behavior for duplicates and acceptance of unknown types, which are beyond the annotations. No contradictions.

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

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

The description is well-structured with a summary line, then detailed Args and Returns sections. It is somewhat verbose but each sentence adds information. Could be slightly more concise without losing clarity.

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

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

Given the tool's simplicity (one parameter, clear purpose), the description fully covers purpose, parameters, behavior (deduplication, unknown types), and return value. It is complete for effective use.

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

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

The input schema already provides detailed descriptions for each parameter. The description's Args section largely replicates this, adding minimal new information (e.g., acceptance of unknown types). Schema coverage is effectively high despite the 0% metric, 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?

The description clearly states the verb 'Add' and the resource 'entity (node) to the active graph', with examples of entity types. It distinguishes from sibling tools like delete_entity or update_entity by specifying addition.

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

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

The description provides clear guidance on when to use the tool (e.g., placing domains, IPs, people on the investigation graph) and explains default deduplication behavior. However, it lacks explicit exclusions or references to alternative tools (e.g., maltego_import_csv for bulk adds).

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

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

Annotations indicate the tool is not read-only and not destructive, and the description adds behavioral details: it mutates by adding a directed link, returns a confirmation with link id, and raises an actionable error if an endpoint id does not exist. This goes beyond annotations.

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

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

The description is concise and well-structured: a one-line summary followed by a bullet list of parameters and return value. No unnecessary words; every sentence adds value.

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

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

The description covers all essential aspects for a simple add-link tool: purpose, prerequisites (existing entities), parameters, return value (confirmation/error). No output schema needed as return type is simple. Complete for an agent to use 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?

Despite the 0% schema description coverage metric, the description adds meaning by listing each parameter with examples (e.g., 'n0', 'n1') and clarifying optionality of label, beyond what the schema provides (which already has minLength and descriptions). The schema itself is well-documented, so the description enhances usability.

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

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

The description clearly states the verb 'Add', the resource 'directed link (edge) between two existing entities', and the scope 'on the active graph', distinguishing it from siblings like maltego_add_entity (adds entity) and maltego_delete_link (removes link).

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 specifies the prerequisite that source and target entities must exist ('between two existing entities'), providing essential context for when to use this tool. However, it does not explicitly state when not to use it or mention alternatives, 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?

Annotations already indicate idempotency and non-destructiveness. The description adds behavioral details (positions stored and persisted, deterministic) that go beyond annotations, providing useful context about 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 succinct and well-structured, with an initial action statement followed by key details, then Args and Returns sections. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (one parameter, no nested objects), the description covers all necessary aspects: action, effect, persistence, re-run guidance, algorithm options, and return type. It is fully complete for an agent to select and invoke 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 sole parameter 'algorithm' is fully described in the input schema with enum values, so the description adds no new meaning beyond the schema. The return type is noted, but parameter semantics are not enhanced.

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 that the tool computes and assigns (x, y) layout positions to entities on the active graph. This is a specific verb-resource combination, and no sibling tool performs layout, so it distinguishes well.

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 guides users to re-run after adding entities to refresh the layout and notes that layouts are deterministic. While it doesn't explicitly state when not to use, the context is clear and sufficient for the tool's simplicity.

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

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

Beyond annotations (which are minimal), the description adds important behavioral info: the graph is in-memory, becomes active, and requires explicit saving. This helps the agent understand side effects and lifecycle.

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

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

The description is concise: three sentences for behavior, then Args/Returns sections. No redundant or misleading 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?

Given the tool's simplicity (single param, no output schema), the description covers creation, active state, memory persistence, and saving relation. It is fully adequate 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?

With schema description coverage at 0%, the description adds the uniqueness constraint ('Unique name') not in the schema. However, it does not mention the max length (120) from the schema, leaving some information gap.

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 'Create a new, empty in-memory Maltego graph and make it active.' This is a specific verb+resource+outcome, distinguished from sibling tools like load_graph or open_graph.

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

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

The description provides workflow context: 'Subsequent entity/link operations target the active graph' and mentions saving with maltego_save_graph. It does not explicitly exclude alternatives but guides usage.

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

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

Beyond annotations (destructiveHint, idempotentHint), description adds that it removes all links touching the entity and returns confirmation including number of links removed or an error. This provides clear behavioral context for a destructive 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?

The description is concise with one sentence for the action and a structured Args/Returns block. It avoids unnecessary words, though the Args format could be integrated more naturally. Efficient overall.

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 deletion tool with an output schema (return value described), the description covers the main effect, return type, and error condition. It does not specify what happens if the entity doesn't exist, but that is acceptable for a simple destructive tool. Sufficient for use.

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

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

The input schema already describes entity_id with 'Id of the entity to delete (its links are removed too).' The description repeats this information without adding new meaning. With schema description coverage effectively 100% (the single parameter is described), the additional description is redundant but not harmful.

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

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

Description clearly states 'Delete an entity and all links touching it from the active graph.' This specifies the verb (delete), resource (entity and its links), and scope (active graph). It distinguishes from sibling tools like maltego_delete_link (only links) and maltego_delete_graph (entire graph).

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

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

Lacks explicit guidance on when to use this tool vs alternatives such as maltego_delete_link. Does not mention prerequisites (e.g., entity must exist) or when not to use it. The phrase 'from the active graph' implicitly indicates the context but does not fully guide 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?

Adds behavioral context beyond annotations: notes that if the active graph is removed, another graph becomes active. Annotations indicate destructiveHint=true and idempotentHint=true, and the description aligns without contradiction.

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

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

Extremely concise: two short paragraphs plus Args/Returns. Key information is front-loaded. Every sentence adds value.

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

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

Given the simplicity of the operation and the presence of output schema (though not shown), the description provides complete context: what it does, what it doesn't do, and what returns. No gaps.

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

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

The input schema already describes the 'name' parameter clearly. The description's Args section adds no new information beyond the schema, so minimal added value.

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

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

Clearly states 'Remove an open graph from the server's memory.' Differentiates from file operations by explicitly stating it does not delete .mtgx files. Distinguishes itself from sibling tools like maltego_create_graph and maltego_save_graph.

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

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

Explicitly states when to use (to remove an open graph from memory) and what it does not do (does not delete saved .mtgx file). Clear context on use, but does not name an alternative tool for file deletion.

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 discloses the return behavior: confirmation string or a note if the link ID is not found, adding context beyond the annotations. The annotations already indicate destructiveHint=true and idempotentHint=true, and the description is consistent with these. No contradictions detected.

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

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

The description is extremely concise and well-structured, with a short summary followed by clear args and returns sections. Every sentence adds value with no redundancy or fluff.

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

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

The description adequately covers the tool's purpose, parameter, and return behavior, including the not-found case. It assumes the graph is active (implied by 'active graph') but doesn't explicitly state prerequisites like graph must be loaded or active, which is a minor gap. The presence of an output schema further reduces the need for detailed return documentation.

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

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

The description adds a cross-reference to maltego_list_links for obtaining the link_id, which is helpful beyond the schema's basic description. Although the schema already describes the parameter, the extra usage context enhances clarity for the AI agent.

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

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

The description explicitly states 'Delete a single link (edge) from the active graph by id.' It clearly identifies the action (delete), resource (link/edge), and simplifies by referencing the source for the ID. This distinguishes it from sibling tools like maltego_add_link or maltego_delete_entity.

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 explains the tool's intent and references maltego_list_links to obtain the link ID, providing guidance on how to prepare. However, it does not explicitly state when not to use this tool or compare it to other deletion alternatives, which would further clarify usage boundaries.

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

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

Annotations indicate readOnlyHint=false (mutating) and openWorldHint=true (potentially broad scope). The description adds that it 'Records Investigation Memory and links results back to the entity,' which goes beyond annotations. It does not contradict annotations.

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

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

The description is well-structured: front-loaded purpose, usage guidance, and behavior. The Args block is redundant with the schema but not excessive. Two sentences plus a parameter list is concise enough.

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 that runs all transforms on one entity, the description covers purpose, use case, parameters, and return type (summary string). It lacks details on potential performance impact or result volume, but with openWorldHint and output schema present, it's reasonably 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 input schema has descriptions for all parameters (entity_id, max_rounds, allow_network) with high coverage. The description's 'Args' block merely repeats these descriptions verbatim, adding no extra meaning. 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 'Run ALL applicable, available transforms on ONE entity to pivot from it.' This specifies the action (run) and resource (entity transforms), and the scope (ALL transforms) differentiates it from sibling like 'maltego_run_transform' which runs a single transform.

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

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

The description provides explicit usage context: 'Use when: you want to dig into a specific node (e.g. a pivot from maltego_identify_pivots) rather than re-running a whole investigation.' It contrasts with broader investigations and mentions recording memory, but does not explicitly name alternatives or when not to use.

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

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

The description discloses deterministic behavior, the type of information returned (properties, notes, degree, neighbours, transforms), and error handling. This adds value beyond annotations (readOnlyHint, idempotentHint) by detailing the exact output components and scope. No contradictions detected.

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

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

The description is concise and front-loaded: the first sentence captures the core purpose. Subsequent lines elaborate efficiently without redundancy. It is appropriately sized for the tool's simplicity, though some minor repetition with the schema exists.

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 is non-destructive, deterministic, and has an output schema (as indicated), the description covers the essential aspects: input parameters, output content, and error condition. It is complete for an explain tool, though it could mention the return format (markdown vs JSON) as part of the behavior.

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 provides clear descriptions for both parameters (entity_id and response_format). The description's Args section restates these but does not add new semantic meaning. With schema coverage effectively 100% (both parameters have descriptions), the baseline is 3, and no additional insight is provided.

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

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

The description clearly states it explains a single entity including its data, neighbours, and expansion possibilities. The verb 'Explain' combined with 'one entity' distinguishes it from sibling explain tools like explain_scores or explain_transform, which focus on other aspects. The first sentence is specific and actionable.

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 implicitly indicates this tool is for explaining a single entity, but it does not explicitly state when to use it over alternatives like maltego_explain_scores or maltego_explain_transform. There is no 'when-not' or explicit alternative mention, leaving the agent to infer the context from the tool name and sibling list.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral detail: returns deterministic, human-readable rationale with specific factors (sources, connectivity, type rarity, enriching properties). It does not contradict annotations.

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

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

Two sentences plus clear args list, no redundancy. Efficient structure with key information front-loaded.

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

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

Given single parameter and simple output (Markdown), the description covers purpose, parameters, and return value. Missing edge cases (e.g., invalid entity ID) but complete for typical use.

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

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

Schema description coverage is 0%, but the input schema's parameter description is minimal ('Entity id to score (e.g. 'n0').'). The tool description repeats this and adds no additional meaning or examples. Baseline is adequate but not enhanced.

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 explains how intelligence-quality scores were derived, using specific verbs and resource ('Explain how an entity's intelligence-quality scores were derived'). It distinguishes from sibling explain tools like 'maltego_explain_entity' and 'maltego_explain_transform' by focusing specifically on scores.

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

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

The description implies usage for understanding score derivation but does not explicitly state when to use this tool over alternatives like 'maltego_explain_why' or 'maltego_score_entity'. No guidance on when not to use or prerequisites.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns 'Full step detail, or an error if the execution id is unknown', disclosing potential error behavior. No contradictions.

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

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

The description is reasonably concise, with a clear front-loaded purpose and structured details. The 'Args:' section is slightly redundant with the schema but not overly verbose. Could be trimmed slightly, but overall effective.

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 presence of an output schema and annotations, the description covers the tool's purpose, required parameter, optional format, return value, and error case. It references the prerequisite tool. Adequate for the tool's simplicity.

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 includes descriptions for both parameters (transform_execution_id and response_format). The description merely repeats these, adding minimal new meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'explain' and resource 'recorded transform execution', and specifies the identifier (execution id). It distinguishes from sibling tools like maltego_explain_entity or maltego_explain_scores, which address different resources.

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 context by referencing maltego_list_investigation_steps for obtaining execution ids. It does not explicitly exclude alternatives or state when not to use, but the purpose is clear enough for an agent to infer usage context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's role is reduced. The description confirms the read-only nature and adds context (uses Investigation Memory, returns error for unknown id), but does not disclose additional behavioral traits beyond what annotations cover.

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

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

The description is concise and well-structured. It starts with a one-sentence purpose, explains the mechanism, then lists parameters and return value. Every sentence is informative without redundancy.

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

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

Given the tool's simplicity and the existence of an output schema, the description is fairly complete. It covers purpose, parameters, return value, and error handling. Could be improved by detailing the output format further, but it is sufficient for an agent to use correctly.

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

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

The input schema already describes both parameters (entity_id and response_format) with clear descriptions. The tool description essentially repeats this information, adding no new meaning. With schema coverage high, the baseline is 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's purpose: to explain why an entity is on the graph by tracing its provenance. It specifies the mechanism (Investigation Memory) and the return value (transform, triggering entity, reason). This differentiates it from siblings like maltego_explain_entity or maltego_explain_transform.

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 context on when to use the tool (to trace provenance) and notes that seed entities are identified as analyst-provided. However, it does not explicitly state when not to use it or contrast with alternative explain tools among siblings.

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

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

The description discloses the output format and round-trip behavior, adding value beyond annotations. It also mentions the return value (confirmation with path and entity count). Annotations (idempotentHint=true, destructiveHint=true) are consistent with the description's implied behavior (exporting overwrites file, but is idempotent if graph unchanged).

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

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

The description is concise, with two clear paragraphs and structured Args/Returns sections. Every sentence serves a purpose, with the main action front-loaded. No redundant information.

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

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

Given the tool's simplicity (exporting to CSV), the description fully covers the purpose, format, parameter, and return value. The round-trip context and lack of output schema are adequately addressed.

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

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

The description repeats the parameter 'path' from the input schema without adding new semantic detail. The schema itself already provides a description ('Destination file path for the export'). Therefore, the description does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly specifies 'Export the active graph's entities to a CSV file', identifying the action (export), resource (active graph's entities), and format (CSV). It also mentions round-trip compatibility with import, distinguishing it from sibling export tools like maltego_export_json.

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 states that the exported CSV can be re-imported using maltego_import_csv, providing clear context for when to use this tool. However, it does not explicitly state when not to use it or mention alternatives like maltego_export_json.

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

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

Annotations indicate destructiveHint=true, but description describes it as a non-destructive export. This contradiction confuses the agent about potential side effects. No mention of file overwriting or other destructive 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-sentence overview plus a concise Args section. Every sentence provides necessary information without redundancy.

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

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

Covers purpose and usage adequately for a simple tool, but the annotation contradiction introduces uncertainty. Output schema not shown but mentioned as existing; description confirms return value.

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?

Description restates the parameter name and purpose, but the schema already includes a nearly identical description. Minimal added value; baseline score appropriate given high schema coverage.

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

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

Clearly states action (export), resource (full active graph), and output format (JSON). Distinguishes from sibling export tools (CSV, report) and mentions it's a superset of .mtgx sidecars.

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?

States it's useful for downstream tooling that doesn't read Maltego files, implying when to use. Lacks explicit alternatives or when-not-to-use but context is clear.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=true. The description adds that the tool writes to a file and is deterministic, but does not elaborate on overwrite behavior or other side effects beyond what annotations imply.

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

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

The description is concise, front-loaded with the core purpose, and efficiently organized with parameter details in a clear list. Every sentence adds value without redundancy.

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

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

The description, together with annotations and output schema, provides a thorough understanding of the tool's behavior. It could mention overwrite semantics explicitly, but overall it is sufficiently complete for effective usage.

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

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

The description adds value beyond the input schema by explaining the path-format convention (.md for markdown, .html for HTML) and linking to the sibling tool's content. This compensates for any lack of schema description coverage (0% stated, though schema has descriptions).

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

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

The description clearly states the tool writes a deterministic investigation report to a file, and explicitly distinguishes it from the sibling tool maltego_generate_report by specifying that this one writes the same content to a path.

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

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

The description provides clear guidance on when to use this tool (when you need to write the report to a file) and compares it to maltego_generate_report, which does not write to a file. It also explains the path extension convention for format selection, but does not explicitly state when not to use it.

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

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

The description reveals the algorithm ('undirected BFS'), the output format ('shortest path as a chain of entities with link labels, or a note if no path exists'), and safety implications are already covered by annotations (readOnlyHint=true). No contradictions.

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

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

The description is concise, well-structured with clear sections (purpose, use case, args, returns). Every sentence is necessary and efficient, avoiding redundancy.

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

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

The description covers the core functionality, use case, and return format. With an output schema present, return value details are not needed. It does not mention performance constraints or graph scope, but for a simple path-finding tool, it is adequately complete.

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

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

Schema description coverage is 0%, meaning the description should add value beyond the schema. However, it merely restates the parameter names and types ('Start entity id', 'End entity id') without providing additional context like acceptable id formats or entity types. This adds little to no new information.

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: 'Find the shortest relationship path between two entities (undirected BFS).' It provides a concrete example ('does this email relate to that IP, and through what?') and is distinct from sibling tools, which mainly deal with single entities or lists.

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 when to use the tool ('Use when: you want to know how two findings are connected') and gives an illustrative example. However, it does not mention when not to use it or contrast with alternative tools (e.g., maltego_explain_entity), missing some guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the report is deterministic and lists the report content, which aligns with annotations. No contradictions, and it provides additional 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 well-structured with a clear opening sentence, bullet-like list of report contents, and a separate Args section. It is concise, front-loaded, and every sentence adds value.

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

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

Given the presence of an output schema (not shown but mentioned), the description still explains the return type ('str: The full report as Markdown or HTML text'). The single parameter is fully documented. The tool is simple and the description leaves no gaps.

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

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

Schema description coverage is 0% (per context), but the description includes an Args section explaining the 'format' parameter with default and enum values (markdown or html). This adds meaningful interpretation beyond the schema's property type.

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

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

The description clearly states it generates a deterministic investigation report for the active graph, listing components like executive summary and key findings. It distinguishes from sibling tool maltego_export_report by noting that this tool returns the report inline while the sibling writes to a 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 explicitly mentions an alternative (maltego_export_report) for writing to a file, providing usage context. It does not explicitly state when not to use this tool, but the context of report generation vs. file export 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?

Annotations provide readOnly and idempotent hints. Description adds that it returns JSON or markdown, includes error handling for unknown id, and outlines the return structure, which goes beyond annotations.

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

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

The description is clear and front-loaded, though it uses a Python docstring format that is slightly longer than necessary. Every sentence adds value, but it could be more concise.

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 2 parameters, annotations, and no output schema shown, the description adequately explains return format and error behavior. It could mention the active graph context explicitly, but it is sufficient.

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

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

Schema has 0% description coverage. The description explains both parameters: entity_id with an example, and response_format with enum values, fully compensating for the lack of schema descriptions.

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

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

The description clearly states the tool fetches detailed entity data by id, distinguishing it from list-oriented and mutation siblings like maltego_list_entities and maltego_update_entity.

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 when you have a specific entity id but does not explicitly state when to prefer this over listing or explain tools. No when-not or alternative guidance is given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so the description adds value by specifying the Markdown format and one-line-per-step structure. No contradictions.

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

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

Very concise—five sentences total, front-loaded with purpose, no wasted words. Clear structure with returns section.

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

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

With an existing output schema, the description sufficiently covers the return type (Markdown timeline) and purpose. Full context provided given zero parameters and simple behavior.

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?

No parameters; schema coverage is 100%. Description does not need to explain parameters, and the baseline of 4 applies.

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

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

Description clearly states it returns the chronological timeline of the active investigation, specified as a compact ordered narrative of transform executions. This distinguishes it from sibling tools like maltego_get_recent_events or maltego_list_investigation_steps.

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

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

Explicitly states usefulness for review, audit, and explaining the investigation path. Lacks explicit when-not or alternatives, but the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds context about reading from the event bus's bounded buffer and describes the return format, which is beyond what annotations provide. No contradictions.

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

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

The description is concise, well-structured with Args and Returns sections, and every sentence adds value. No unnecessary text.

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 polling tool, the description covers purpose, parameter usage, and return format. It lacks details on buffer capacity or error handling, but the overall completeness is adequate given the tool's simplicity.

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

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

The description repeats schema parameter descriptions but adds usage context for `since_seq` and explains the return format (JSON vs markdown). Since schema coverage is 0%, the tool description compensates somewhat, but the additional value is incremental.

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 returns recent investigation events and lists example event types. It does not explicitly differentiate from sibling tools like maltego_subscribe_events, but the purpose is specific 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 explains incremental polling with `since_seq`, providing clear usage guidance. It does not specify when not to use or mention alternatives, but the context is sufficient for typical use.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that it returns a string of guidance, same as MCP instructions, and is safe to call anytime.

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?

Very concise: three short paragraphs. Front-loaded with purpose, then usage, then return type. Every sentence adds value.

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

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

For a tool with no parameters and a simple string output, the description is complete: explains why, when, what it returns, and what to do next.

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?

No parameters; schema coverage is 100%. Description doesn't need to add parameter info. Baseline 4 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 clearly states it returns guidance on using the server (autonomous workflow and tool map). It distinguishes itself from sibling tools as a meta-orientation 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?

Explicit usage condition: 'Use when: you are unsure which tool to call or how the investigation flow works.' Also provides a recommended next step: 'Next: usually `maltego_investigate`.'

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

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

Annotations already declare readOnlyHint and idempotentHint, meaning the tool is safe and idempotent. The description adds algorithmic detail: it deterministically ranks entities with degree >= 2 and returns specific fields (id, value, type, degree, reason). This fully explains the behavior beyond what annotations provide.

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

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

The description is well-structured with a clear header sentence, an explanatory sentence, and a structured Args/Returns section. It is concise, front-loaded, and every sentence adds value.

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

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

Given the tool's low complexity (two parameters, no nested objects, output schema present), the description covers all necessary aspects: input parameters, algorithmic behavior, and output format. The annotations handle safety, and the description adds sufficient context for an agent to use the tool correctly.

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

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

The input schema already contains descriptions for the limit and response_format parameters (including defaults, min, max, and enum values). The description's 'Args' section essentially repeats this information without adding new meaning beyond what the schema provides. Baseline is 3 since schema_coverage is effectively high despite the context signal indicating 0% (likely a data issue).

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 identifies the most promising pivot entities in the active graph, which are entities with degree >= 2. This is a specific verb+resource combination, and it is easily distinguished from sibling tools like maltego_expand_entity or maltego_rank_entities.

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

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

The description explains that the tool finds pivots that connect many others, making them good points to pivot an investigation. It gives examples (shared IPs, central emails), which helps an agent understand when to use it. However, it does not explicitly state when not to use it or compare to alternatives, but the context is sufficient for a typical use case.

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 mutation (builds on active graph), deduplication, and handling of unknown types. Annotations confirm readOnlyHint=false, no contradiction. Missing detail on what happens if no active graph exists, but overall good 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?

Concise, well-structured description: first sentence states purpose, then format, behavior, args, returns. No fluff 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?

Covers input format, dedup, unknown types, and return value. Minor gap: does not explain how 'link_to' column works to create links. Output schema exists, so return description is sufficient.

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

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

Input schema already describes path and content parameters with good detail. Description adds context about CSV format (type,value header, optional columns) and dedup behavior, but does not significantly enhance per-parameter meaning beyond schema.

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

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

Description clearly states the tool builds entities (and optional links) on the active graph from CSV. This is a specific verb-resource pair and distinguishes from sibling tools like maltego_add_entity (single entity) and maltego_import_graph (graph 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?

Describes input format and behavior (dedup, skip unknown types) well, but does not explicitly say when to use this tool over alternatives like maltego_add_entity for single entries or maltego_import_graph for graph files. Implicit usage 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?

Annotations indicate a mutable, potentially destructive operation (readOnlyHint=false, destructiveHint=false). The description adds that the tool merges data into the active graph and remaps ids, but does not detail permission requirements or error scenarios beyond mentioning an actionable error.

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 efficient and well-structured: it first states the core action and distinction, then details parameters and return value. Every sentence adds value without redundancy.

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

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

Given the presence of an output schema and annotations, the description provides all necessary context: what the tool does, how it differs from siblings, parameter explanations, and return format. No gaps.

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

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

Schema description coverage is 0% according to context, so the description fully explains both parameters: path (path to .mtgx file) and dedupe (deduplication logic). It also describes the return value, compensating for the lack of schema descriptions.

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

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

The description clearly states that the tool merges a .mtgx file into the active graph, contrasting with maltego_load_graph. It specifies the action (merge), resource (graph), and unique behavior (remapping ids, deduplication).

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 directs when to use this tool versus maltego_load_graph, and explains the dedupe parameter's role. The description provides clear context for the tool's appropriate use.

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

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

Annotations show readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds that it updates Investigation Memory, auto-detects type, builds graph, and returns a briefing without writing files. No contradiction with annotations, and it provides meaningful behavioral context beyond the structured fields.

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

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

The description is front-loaded with the primary purpose, uses bullet points for arguments, and avoids redundancy. It is slightly lengthy but every sentence adds value for a complex tool.

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

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

For a complex tool with 7 parameters and an output schema (not shown), the description covers all key aspects: entity types, parameter details, behavioral effects (graph memory), and return value (briefing string). It is sufficiently complete for an agent to use correctly.

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

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

Schema description coverage is 0% per context, but the schema itself contains detailed parameter descriptions (e.g., depth explains quick/standard/deep). The description adds minor extra context (e.g., 'deep' for 'go deep' requests) but does not significantly surpass what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states 'PRIMARY entry point — run a COMPLETE investigation in one call' and specifies supported entity types (domain, email, IPv4/IPv6, URL, bare value). It distinguishes itself from sibling tools like maltego_investigate_domain by being a unified entry point.

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

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

Explicitly says 'Use when the user wants to investigate anything' and 'This is the default for "investigate X"'. It instructs not to call summarize/list/suggest afterwards and suggests next steps (maltego_save_graph or maltego_export_report), providing clear when/not-to-use guidance.

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

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

The description discloses significant behavioral traits beyond annotations: it ensures an active graph, adds entities, runs transforms with deduplication, allows network/offline modes, sets expansion depth limits, and notes skipped transforms for missing API keys. No contradiction with annotations.

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

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

The description is well-structured with a clear opening, bullet-like argument list, and return value section. Every sentence adds value, and it is appropriately sized for the tool's complexity.

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

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

Given the orchestration nature and output schema, the description covers input, behavior, output summary, and limitations (missing API keys). It is complete without needing to explain return values due to output schema existence.

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

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

Although the input schema already describes parameters, the description adds context (e.g., 'breadth-first' for max_rounds, 'offline/passive parse-only run' for allow_network) that enhances understanding beyond schema descriptions.

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

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

The description clearly states the tool's action ('Automatically investigate a domain') and resource (domain), distinguishing it from sibling tools like maltego_investigate_email and maltego_investigate_ip. It specifies the one-call workflow of adding a domain entity and running transforms.

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

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

The description explicitly recommends this tool 'instead of chaining transforms manually', providing clear usage context. It implies when to use for automated investigation versus fine-grained control, though it does not explicitly list all alternatives.

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

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

The description discloses that it adds an entity, expands the graph, and performs network-dependent checks, aligning with annotations (readOnlyHint=false, openWorldHint=true). It references shared behavior in another tool for full details, which slightly reduces transparency but still provides solid insight into behavior beyond annotations.

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

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

The description is well-structured with an overview sentence, an Args section, and a Returns line. It is concise (about 6 sentences) and front-loaded with the core purpose. Every part adds value, including the cross-reference to the domain tool.

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

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

Given the complexity (orchestration tool with multiple steps) and the presence of an output schema (return string), the description covers inputs, behavior, and what to expect. It wisely defers to maltego_investigate_domain for detailed shared behavior, which is acceptable but leaves some details indirect.

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?

Despite the 0% schema coverage signal, the description includes an Args section explaining each parameter (value, allow_network, max_rounds) with clear, contextual explanations that add value beyond the schema's own descriptions. For example, it clarifies network transforms and expansion depth.

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

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

The description clearly states it investigates an email address, deriving domain, checking breaches, and expanding footprint. It references maltego_investigate_domain for shared behavior, distinguishing its specific focus from sibling tools like maltego_investigate_domain and maltego_investigate_ip.

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 indicates its specific purpose for email investigation and directs to the domain tool for shared behavior, but does not explicitly state when not to use it or compare to alternatives like the general maltego_investigate. Implicit guidance is clear but not fully explicit.

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

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

Annotations indicate non-readOnly, openWorld, not idempotent, not destructive. The description adds context: it makes network calls via reverse DNS and host-intelligence providers (Shodan, Censys), and provides an 'allow_network' parameter to control network behavior. This goes beyond annotations without contradiction.

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

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

The description is concise with two sentences of purpose, structured args list, and return mention. It front-loads the key action. Some redundancy with schema info but overall 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 moderately complex tool that expands the graph, the description covers inputs, actions, and references sibling for shared behavior. An output schema exists, so not detailing returns is acceptable. It could mention side effects like adding entities to the active graph, but overall sufficient.

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

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

The input schema already has detailed descriptions for all parameters (value, max_rounds, allow_network). The description in the text repeats the schema info and adds an example IP and clarifies max_rounds bounds. Since schema coverage is high, the description adds marginal value.

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 investigates an IPv4 address by performing reverse DNS, port, and service discovery. It adds an IPv4 Address entity and expands the graph. It references the sibling tool 'maltego_investigate_domain' for shared behavior, distinguishing its focus on IP addresses.

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 explains it investigates IP addresses and points to a sibling for shared behavior, but does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or alternative conditions are provided.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds value by explaining the opt-in mechanism, the data recorded (runs, successes, yield), and return format, without contradicting annotations.

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

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

Two concise sentences front-load the purpose, followed by necessary details in a second paragraph. No extraneous information.

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

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

With no parameters, rich annotations, and output schema present, the description covers return type and opt-in prerequisite. Lacks exact note wording when learning is disabled, but otherwise 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?

No parameters exist, so schema coverage is 100%. The description compensates by explaining the return value and opt-in behavior, meeting the baseline for 0 params.

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

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

The description clearly states the verb 'Show' and the resource 'cross-investigation learning stats', and distinguishes this tool from siblings like maltego_next_best_actions by specifying it focuses on statistics, not actions.

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 explains when to use (to view learning stats) and prerequisites (opt-in via env vars), but does not explicitly exclude alternatives or provide when-not-to-use guidance.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing the return formats (markdown and JSON), pagination behavior (offset, limit, has_more, next_offset), and that it operates on the active graph. No contradictions.

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

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

The description is concise with clear sections (Args, Returns) and front-loads the main purpose. Every sentence adds value without repetition. The structure is easy to parse for an AI agent.

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

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

Given the tool has 5 parameters and an output schema, the description fully covers the input and output. It explains pagination, filtering, and both response formats. No missing information; the tool is complete for a list 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?

Despite schema description coverage being 0%, the description thoroughly documents all parameters with additional context: type_filter (Maltego type), value_contains (case-insensitive substring), limit (range 1-500, default 50), offset, and response_format (enum with defaults). This adds significant meaning beyond the schema's property descriptions.

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

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

The description clearly states 'List entities on the active graph' with specific verb and resource. It distinguishes from sibling tools like maltego_get_entity (single entity) and maltego_list_links by focusing on entities with optional filtering and pagination.

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 documents parameters and their defaults, making it clear how to use the tool. However, it does not explicitly state when not to use it or compare to alternatives like maltego_get_entity. The context is implied but not explicitly stated.

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

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

Annotations provide readOnlyHint, idempotentHint, destructiveHint. Description adds that the catalog is a 'curated subset' and that custom types also work, which provides extra context beyond annotations.

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

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

Description is well-structured with a purpose, usage, and parameter description. No redundant sentences; front-loaded with the most important information.

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

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

For a simple tool with one optional parameter, the description covers what it does, how to use it, and what it returns (Markdown). The presence of an output schema and annotations further reduces the need for more detail.

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

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

Schema description coverage is 0%, so description carries the burden. The description explains the 'category' parameter with example values (infrastructure, personal, social, organization, location) and confirms it is optional, adding meaning beyond the schema.

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

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

Description clearly states the tool lists supported Maltego entity types from the built-in catalog, and explicitly connects it to discovering type IDs for maltego_add_entity. This distinguishes it from sibling tools like maltego_list_entities.

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

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

Description instructs to use this to discover valid type ids for maltego_add_entity. It notes the catalog is a curated subset and that custom types work, but does not explicitly specify when not to use it, though 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?

Annotations already provide readOnly, idempotent, and non-destructive hints. The description adds that it returns a Markdown bullet list with entity/link counts and marks the active graph, which is useful behavioral detail beyond annotations.

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

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

The description is extremely concise: two sentences covering purpose and return value. Every sentence adds value with no redundancy.

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

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

Given zero parameters, full annotations, and an output schema, the description provides all necessary context: what it does, what it returns, and a behavioral note. Nothing is missing for a simple list 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?

There are no parameters, and the schema description coverage is 100%. The description is not required to add parameter meaning, so a baseline score of 4 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 lists all open graphs and marks the active one. This distinguishes it from sibling tools that create, delete, or rename graphs.

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 does not explicitly state when to use this tool versus alternatives. While the purpose is clear, there is no guidance on when to prefer this over other graph listing or info tools.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds valuable context that the tool returns the investigation's reasoning trace, not just graph data. No contradictions with annotations.

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

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

The description is concise and well-structured, front-loading the purpose, then detailing parameters and returns in a clear, bullet-like format. Every sentence adds value.

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

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

Given the tool's complexity (nested object parameter, no schema descriptions), the description fully covers parameter details and return format, with no obvious gaps. Output schema exists, so return details are sufficient.

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

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

Despite 0% schema description coverage, the description thoroughly explains each parameter (limit/offset for pagination, status filter, response_format) and the return format, adding significant meaning beyond the raw schema.

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

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

The description clearly states it lists recorded investigation steps (procedural memory) for the active graph, explaining what each step records (transform execution details). This differentiates it from sibling tools like maltego_list_transforms or maltego_list_entities.

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

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

The description implies usage is for the active graph's reasoning trace, but it does not explicitly state when to use this tool over alternatives or provide exclusions. The context is clear enough for basic use.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. Description adds pagination details and response format behavior, going beyond annotations without contradiction.

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

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

Description is front-loaded with purpose and includes structured Args/Returns sections. It is fairly concise but could be slightly shorter by omitting obvious parameter 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?

Covers pagination and response format. Output schema exists, reducing need to explain return values. Lacks context about requiring the active graph to exist, but otherwise complete for a read-only list 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?

Input schema has descriptions for all subproperties (limit, offset, response_format). The description mainly repeats schema info ('limit/offset for pagination', 'response_format: markdown or json') without adding new 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?

Description clearly states 'List links (edges) on the active graph, with pagination', specifying the verb 'list' and resource 'links on the active graph'. This distinguishes from sibling tools like maltego_add_link and maltego_delete_link.

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 explicit guidance on when to use this tool versus alternatives. Usage is implied for viewing edges, but no exclusions or when-not conditions are provided.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds that the tool returns a Markdown list and explains what machines do, complementing the safety profile without contradicting it.

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 four sentences, front-loads the purpose, and contains no unnecessary words. Every sentence adds value.

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

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

With zero parameters, complete annotations, and an output schema, the description fully covers the tool's purpose and behavior. No gaps remain.

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

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

There are no parameters, and schema coverage is 100%. The description does not need to add parameter details, so baseline 4 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 lists available investigation machines, defines them as reusable workflow templates, and gives an example. It distinguishes from siblings like maltego_run_machine and maltego_list_transforms.

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 explains what machines are and explicitly mentions maltego_run_machine as the tool to run one, providing a clear alternative. It gives enough context for when to use this tool, though it doesn't explicitly exclude other cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying the return format (Markdown list), grouping by tier, and including configuration status and env vars.

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 plus a return line, concise and front-loaded. Every sentence provides necessary information without redundancy.

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

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

Given no parameters, comprehensive annotations, and an existing output schema, the description fully explains the tool's behavior and return value (Markdown list with configuration details).

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

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

There are no parameters, so the baseline per rules is 4. The description correctly focuses on the tool's output without needing to elaborate on inputs.

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

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

The description explicitly states the tool lists OSINT transform providers and their configuration status. It clearly distinguishes from sibling list tools (e.g., list_transforms) by focusing on providers and their env-var requirements.

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

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

The description implies usage for checking provider configuration but does not explicitly state when to use it versus alternatives or mention when not to use it.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds context about the local provider needing no API keys and the return format, which is useful beyond the annotations.

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

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

The description is well-structured with a clear main sentence, a brief explanation of transforms, and an Args/Returns section. It is concise yet informative, with no wasted words.

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

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

Given the simplicity of the tool (one optional parameter, read-only, idempotent), the description provides all necessary context: what it does, what it returns, and the provider nuance. No gaps.

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

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

The description explains the only parameter (input_type) in the Args section, but the schema also includes a description for that field. The description adds value by contextualizing the purpose and return format.

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 lists available transforms with optional filtering. It distinguishes from sibling tools like maltego_run_transform and maltego_explain_transform by focusing on listing. The explanation of what transforms are adds clarity.

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 mentions the purpose and optional filtering, but does not explicitly state when to use this tool versus alternatives like maltego_run_transform. However, the context is clear enough for an agent to decide.

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?

Adds detail beyond annotations: mentions that entities, links, properties, and layout positions are parsed, and full round-trip editing is supported. Annotations (readOnlyHint=false, destructiveHint=false) are consistent with loading behavior. No contradiction.

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

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

Front-loaded with the main purpose in the first sentence, followed by an explanation of equivalence and parameter details. Some redundancy with the schema's parameter description, but overall concise and well-structured.

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?

Provides a good overview of what the tool does, what it loads, and that it returns a summary or error. However, it does not mention potential error conditions (e.g., file not found) or permissions needed, leaving minor gaps.

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

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

Schema description coverage is high (the single 'path' parameter is described in the schema as 'Path to an existing .mtgx file to load.'). The tool description repeats this information without adding new semantic details, so no additional value beyond the schema.

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

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

Clearly states that the tool loads an existing .mtgx file as a new active graph for continuing investigations. However, the claim of equivalence to maltego_open_graph may cause confusion between two seemingly identical sibling tools, reducing differentiation.

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?

Implies usage for continuing investigations by loading an existing file, but provides no explicit guidance on when to use this tool versus alternatives like maltego_open_graph or maltego_import_graph. No when-not-to-use or selection criteria.

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

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

The description adds significant behavioral context beyond annotations: it explains the ranking factors (entity importance, information gain, etc.), mentions Investigation Memory to avoid re-suggestions, and states it is deterministic and explainable. Annotations already indicate readOnlyHint and idempotentHint, which align with the description.

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 well-structured and concise: a clear purpose statement, explanation of ranking logic, explicit supersession, then args and returns. 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 tool's simplicity (one parameter), the description covers the input, output format, and decision logic. The expected return structure is described, and the output schema exists for further detail. No gaps.

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

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

The description details the params object with limit (1-50, default 10) and response_format (markdown or json, default markdown), adding meaning beyond the schema which only provides brief descriptions. However, the schema already includes defaults and constraints, so the description adds moderate value.

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 recommends the most valuable next moves, acting as a decision engine. It uses specific verb 'recommend' and resource 'next best actions', and explicitly distinguishes from sibling maltego_suggest_next_steps by stating it supersedes it with richer reasoning.

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 when deciding what to do next' and 'Supersedes maltego_suggest_next_steps with richer reasoning', providing clear context and an alternative to avoid.

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 silent (no readOnly, destructive, idempotent hints set), but description adds useful context: parses GraphML, creates entities/links, remembers source path for re-save, and returns summary. No contradictions.

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

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

Three paragraphs, well-structured with main action first, then details, then args/returns. Minimal waste, though some redundancy with schema 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 simple file-open tool, description includes all necessary context: how it processes the file, what it returns, and integration with save. Output schema exists but description already explains return value.

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

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

Schema coverage is 0%, so description fully covers the single required param 'path' with clear meaning and context (path to .mtgx file). Also notes remembered path behavior beyond schema.

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

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

Description uses specific verb 'Open' and resource 'existing Maltego .mtgx file', clearly distinguishing from siblings like create or import. Includes details about parsing GraphML and remembering source path for save.

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?

Implies usage for opening existing files only, but does not explicitly state when to use this vs alternatives like load_graph or import_graph. No exclusion criteria or sibling comparisons.

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

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

Annotations already show readOnlyHint and idempotentHint; description adds 'deterministic' and explains scoring and ordering behavior beyond annotations.

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

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

Two short paragraphs with clear structure: purpose, behavior, args, returns. No fluff.

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

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

Covers purpose, behavior, and parameters. Could clarify which entities are ranked (e.g., current graph), but overall sufficient given annotations and output schema.

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

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

Schema has descriptions for both parameters (limit and response_format), so baseline is 3. Description restates defaults and ranges but adds no new 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?

Clearly states the tool ranks entities by investigation priority, deterministic. Distinguishes from siblings like maltego_score_entity and maltego_list_entities.

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

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

Implies usage when prioritized list is needed, but does not explicitly state when not to use or provide alternatives.

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

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

With annotations already indicating non-read-only and non-destructive, the description adds that the return value includes actionable errors for unknown or duplicate names. This provides additional behavioral context beyond the annotations.

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

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

The description is very concise: a single sentence for the purpose, followed by a bullet list of arguments and the return value. 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 rename tool with one required parameter and an output schema, the description fully covers inputs and outputs. It is sufficiently complete given the tool's simplicity.

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

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

The description lists the parameters and their types, but the schema also provides similar descriptions. Given the context indicates 0% schema description coverage, the description compensates somewhat, but it largely repeats the schema information.

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 'Rename an open graph', which is a specific verb+resource combination. It distinguishes from sibling tools like maltego_create_graph and maltego_delete_graph.

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

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

The description explains that it defaults to the active graph and that graph_name is optional. It also describes the return value. However, it does not explicitly state when not to use this tool or provide alternatives.

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

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

The description adds behavioral context beyond annotations: it clarifies that both in-memory and on-disk stores are cleared, and that the operation is a no-op when learning is disabled. Annotations already indicate destructiveness and idempotence, so the description complements them well.

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

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

The description is very concise, consisting of three short sentences. It is front-loaded with the main action, followed by edge-case behavior and a return type. 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?

With no parameters and an output schema that indicates a simple confirmation string, the description is complete. It covers the main purpose, edge case, and return type, leaving no ambiguity for a simple reset action.

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

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

There are no parameters, so schema coverage is 100%. The description provides no parameter information, which is appropriate as there are none. Baseline 4 is suitable.

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 clears the cross-investigation learning store, both in-memory and on disk, and is a no-op when learning is disabled. This is a specific verb-resource combination that distinguishes it from siblings like maltego_learning_stats.

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 mentions when it's a no-op (learning disabled) but does not provide explicit guidance on when to use it vs. alternatives, such as when learning stats are unnecessary or when a reset is needed. Usage context is implied rather than explicit.

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

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

The description adds behavioral details beyond annotations: ensures active graph, seeds entity, expands per recipe, skips missing transforms gracefully, and returns a summary. Annotations declare openWorldHint and non-destructive; description aligns and extends.

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

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

The description is concise yet thorough: a clear purpose statement, followed by structured Args and Returns sections. No redundant information, and front-loaded with essential 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?

Given the tool's complexity (running a machine with overrides), the description covers all necessary aspects: prerequisites, process, parameter details, and return format. It also mentions error handling, making it complete for an agent.

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

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

The description includes an Args section that explains the purpose of each parameter (e.g., 'e.g. passive_domain' for machine_name), adding value over the schema descriptions. Schema coverage is 0%, but the description compensates well.

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 runs an investigation machine, explains the process (ensuring graph, seeding, expanding), and distinguishes it from similar tools like run_transform (single transform) and investigate_* (higher-level).

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

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

It provides guidance to use maltego_list_machines for available machines, and describes the behavior (skips missing transforms). However, it does not explicitly state when not to use this tool (e.g., for single transforms use maltego_run_transform), but the context with siblings provides differentiation.

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

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

Annotations provide basic read/write hints, while the description adds key behavioral details: results are added to the graph by default, de-duplication occurs, and it returns a summary or error. This goes beyond annotations by explaining mutation and dedup 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?

The description is well-structured with a clear first sentence, followed by a bullet list of arguments and a return value section. It is concise without excess, though the bullet list could be integrated into prose. Overall, efficient and front-loaded.

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

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

Given the tool's complexity (running a transform, modifying the graph) and the presence of an output schema, the description adequately explains behavior, results, and error handling. It covers de-duplication, graph modification, and return format, leaving few gaps.

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

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

The input schema already provides detailed descriptions for each parameter, so the description's docstring-style listing adds minimal new meaning. Schema description coverage appears high despite context stating 0%, but the description does not significantly enhance parameter understanding beyond what the schema offers.

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

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

The description clearly states the action ('run a transform'), the resource ('entity in the active graph'), and the purpose ('discover related entities'). It distinguishes this tool from siblings like maltego_list_transforms and maltego_expand_entity by specifying the exact operation and its outcome.

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 the tool (to run a transform on an entity) but does not explicitly exclude alternatives or provide when-not-to-use scenarios. It references maltego_list_transforms for discovering transforms, which aids usage, but no explicit guidance on comparing with similar tools like maltego_run_machine.

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

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

Annotations already indicate idempotent and destructive hints. The description adds context about default path behavior (re-saves to original path) and mentions opening the file in Maltego CE, going beyond annotations without contradiction.

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

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

The description is concise, front-loaded with the main purpose, and structured with a headline, body, and Args list. Every sentence adds value without redundancy.

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

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

For a simple write tool with annotations and an output schema, the description covers the purpose, parameters, behavior (default path), and return value (absolute path or error). No major gaps.

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

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

Schema description coverage is 0%, but the description compensates with an Args section explaining both parameters: path (defaults to original source) and graph_name (defaults to active). This adds meaning beyond parameter names.

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

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

Description clearly states it saves a graph to a .mtgx file, distinguishing it from export tools like maltego_export_csv or maltego_export_json. It specifies verb (save), resource (graph), and format (.mtgx), with details about active vs named graph.

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

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

Usage is implied by the format specification and mention of opening in Maltego CE, but no explicit guidance on when to use this vs alternatives (e.g., export functions) or when not to use it.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive nature. The description adds that the computation is deterministic and provides the exact output structure. No contradictions; the description adds value beyond annotations.

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

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

The description is concise, front-loaded with purpose, and every sentence adds essential information: the scores returned, the derivation, the parameter, and the return format. 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?

The description fully covers the tool's behavior for a single parameter tool. It explains the output structure in detail, compensating for the lack of an explicit output schema in the provided data. It also mentions the derivation source (graph structure and Investigation Memory), which is sufficient for an agent to understand the tool's effect.

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 includes a description for entity_id, so the description adds no new semantic value. It only repeats the parameter meaning. With schema description coverage at 0% (possibly misreported), the description does not compensate but also does not harm. 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 it computes intelligence-quality scores for one entity deterministically, specifying the five scores returned. This distinguishes it from siblings like maltego_rank_entities (multiple entities) and maltego_explain_scores (explanation). The title 'Score Entity' reinforces this.

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

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

The description explicitly limits scoring to a single entity ('for one entity') and mentions deterministic behavior. It does not explicitly state when to avoid using it or point to alternatives, but the context of one entity vs. many is clear enough for an agent to infer.

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

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

Annotations indicate idempotentHint true, readOnlyHint false, destructiveHint false. The description aligns: it confirms making a graph active returns confirmation/error. It adds no new behavioral traits beyond confirming the action is on an already-open graph, which is already implied. Minimal added value over annotations.

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

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

The description is extremely concise: one sentence for purpose, then a bullet for Args and Returns. No fluff, front-loaded with actionable verb. 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 simple tool with one parameter, the description covers the action, required input, and expected output (confirmation/error). There is no missing information given the low complexity. The output schema is not shown but described sufficiently.

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

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

The input schema already describes the required 'name' parameter as 'Name of an already-open graph to make active.' The tool description repeats this info (name as string) but adds a reference to malteco_list_graphs. Since schema coverage is effectively 100% with its own description, the tool description adds little new semantic value.

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 'Make a previously-opened graph the active target for entity/link operations.' It specifies the verb ('Make active'), resource (graph), and distinguishes from sibling tools like malteco_create_graph or malteco_open_graph by emphasizing 'previously-opened'.

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 after opening a graph and references malteco_list_graphs. It provides clear context but does not explicitly state when not to use it or mention alternatives beyond the list_graphs hint. A stronger exclusion could improve it.

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

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

Annotations declare the tool is not read-only, not destructive, not idempotent. The description adds key behavioral details: it turns on live mode and buffering, returns a subscription id, and clarifies that MCP stdio cannot push events, so polling is required. No contradiction with annotations.

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

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

The description is four sentences. It front-loads the main purpose, then explains implications, optionality, and return value. Every sentence earns its place with no redundancy.

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

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

Given no parameters and an existing output schema, the description fully covers the tool's purpose, mechanism, and context. It explains the need for polling and the optional nature of real-time mode, which is complete for a subscribe 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?

There are zero parameters, so the description does not need to add parameter meaning. Schema coverage is 100% trivially. Baseline for 0 params is 4.

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

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

The description clearly states the tool enables real-time investigation mode and returns a subscription ID. It distinguishes itself from sibling tools by explaining that events must be polled via maltego_get_recent_events because MCP stdio cannot push.

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 explains when to use this tool (to enable real-time mode) and that polling is required. It notes that real-time mode is optional and does not change .mtgx behavior, implying it can be skipped if not needed. It references the alternative poll 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?

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive hint. The description adds behavioral details: deterministic, prioritization of most-connected entities, and flagging of unavailable transforms. No contradictions.

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

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

Well-structured with clear sections and front-loaded key message. Somewhat verbose with legacy note and rationale, but each sentence adds value. Could be slightly tighter but overall 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 simple tool with one parameter and an output schema (mentioned but not shown), the description covers purpose, usage, behavioral traits, and parameter details adequately. No gaps remain.

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

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

The description repeats parameter info already present in schema (limit, response_format with defaults). Schema has high coverage (properties have descriptions), so baseline is 3. Description adds minimal new meaning beyond restating schema details.

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

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

The description clearly states it is a 'legacy simple heuristic for next transforms' and specifies what it does: deterministically recommends transforms, prioritizing most-connected entities. It explicitly distinguishes from sibling tool maltego_next_best_actions by calling that the preferred alternative.

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 advises to 'prefer maltego_next_best_actions' for real recommendations and states that this tool is for basic heuristic lists. It provides clear when-to-use and alternatives guidance.

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