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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so safety and repeatability are covered. The description adds useful transformation detail beyond annotations, including removal of note statements, empty braces, and post-newline strings, plus the exact returned state.

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 core purpose and uses a scannable bullet list for removals. The Args and Returns sections add slight redundancy, but every part remains useful and the total length is reasonable for the transformation behavior it documents.

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 utility with no output schema, the description explains the input content, transformations, and returned content well enough for an agent to invoke it correctly. It does not explain session handling, but that is covered in the schema for session_id.

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

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

Schema description coverage is 50%. The undocumented required parameter, mermaid_content, is described in the description as 'the raw Mermaid class diagram content,' which adds meaning beyond the schema's bare string type. The optional session_id has a detailed schema description and does not need repetition here.

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

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

States a specific verb and resource: 'Clean a Mermaid class diagram by removing unwanted elements.' The bullet list then names exactly which elements are removed, so an agent can distinguish this utility from unrelated sibling tools like plotting or querying tools.

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

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

The description implies usage by listing the unwanted elements it removes, but it does not explicitly say when to call this tool, when not to call it, or name an alternative. In the absence of similar sibling tools, the implied scenario is adequate but not rich.

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, and the annotation title calls it 'prompt only'. The description contributes the output format (markdown, user prompts and Claude responses), but it does not confirm the 'prompt only' nature or explain that no transcript file is created — a meaningful ambiguity that annotations partly, but not fully, resolve.

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

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

A single efficient sentence with no filler. It is front-loaded, though very short relative to the ambiguity it leaves unresolved.

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

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

For a single-parameter, no-output-schema tool, the description covers the minimum, but the read-only 'prompt only' nature — the most important thing an agent needs to know to avoid expecting a persisted transcript — is conveyed only indirectly. It is adequate but incomplete.

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

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

Schema description coverage is 100% and there is only one optional parameter, so the schema fully documents session_id, including its privacy role and reuse instructions. The description adds nothing about parameters, 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 names a verb-adjacent action and resource ('creating a chat transcript in markdown format') and clarifies the content shape (user prompts + Claude responses). However, the odd phrasing 'Prompt for creating' leaves it ambiguous whether the tool generates a prompt, returns a transcript, or writes a file, and it draws no distinction from the 25 sibling tools.

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

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

There is no statement of when to use this tool versus alternatives such as create_session or end_session, nor any precondition, trigger, or exclusion. The agent must infer usage entirely from the name.

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

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

Annotations only declare readOnlyHint=false, idempotentHint=false and openWorldHint=false; the description adds material context beyond that: inactivity (60 min) and absolute (8 h) lifetimes, the fact that expired sessions DROP their plots, and that the session id is an opaque bearer token to be kept private and never guessed. This directly discloses what is lost and the security posture.

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 core action, then organized into clearly labeled WHEN TO USE / WHY / LIFETIME / RETURNS blocks. The extra length is justified because the tool is a universal prerequisite, and no sentence is filler.

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

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

There is no output schema, so the description carries the return contract and does so ('a short message containing session_id: <token>'). Combined with lifetime and re-creation guidance, nothing an agent needs to call this correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4; the description still explains what the calling convention is (extract the token from the return message and pass it as session_id on every subsequent call), which is useful even though there is no argument to document.

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

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

States a specific verb+resource ('Start a session and obtain the session_id') and immediately distinguishes itself from siblings by declaring that every other tool on the server requires the returned token. An agent can tell it apart from end_session and the plotting/query tools without opening any schema.

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

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

Explicit when-to-use: call ONCE at the start of a conversation before any other mcp-genelab tool, and again whenever a tool reports the session is unknown or expired. This is exactly the kind of ordering prerequisite an agent needs, with no reliance on inference.

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

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

Annotations already state it is a non-read-only, non-idempotent, closed-world operation, so the bar is lower. The description still adds real behavioral detail: filters execute in the Cypher query BEFORE overlap computation, and the summary always reports all four overlaps regardless of which subset is rendered. It stops short of describing the returned link's lifetime or how plots are fetched post-creation.

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

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

The purpose and mode table are well front-loaded, but the block restating in_promoter/in_exon/in_intron/dist_to_feature_max semantics duplicates schema descriptions verbatim and inflates a 17-param tool's prose substantially. Every sentence earns its place less often than it should because of that 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 17-parameter, four-mode tool with no output schema, the description covers the mode selection, filter interaction, significance/magnitude semantics per data type, and the return ('a link to the plot and summary statistics'). Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds semantics the schema omits: multiple location filters combine with AND, with a worked example (in_promoter=True with in_intron=False), and it clarifies that abundance significance filtering is method-aware (DESeq2 vs ANCOM-BC) and that lnfc_threshold only touches ANCOM-BC rows. Some of the threshold text merely echoes the schema, but the AND-combination and ordering semantics are genuine additions.

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

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

The opening sentence states a specific verb and resource ('Create Venn diagrams comparing differential data between 2 or 3 assays') and the data_type enumeration distinguishes it from sibling plotting/finding tools. An agent can tell what it produces and over what inputs without opening the schema.

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

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

It maps each data_type to a concrete scenario (expression/methylation/abundance/expression_methylation) and gives a conditional rule for direction_pair ('If the user names a specific pairing... pass direction_pair=hyper_down'). It never names or excludes a sibling tool (e.g. find_common_differentially_expressed_genes), so usage context is clear but alternatives are left implicit.

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=false, idempotentHint=false and openWorldHint=false, so the write/non-idempotent nature is covered. The description adds genuine context beyond that: the return payload (markdown summary, inline PNG, saved path), the color encoding scheme, method-aware significance handling, and a performance note about large assays not timing out.

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 content is long but front-loaded with the purpose and organized as scannable bullets per data type, with axis and color conventions grouped logically. Some of the per-type detail restates schema content, but nothing is wasteful enough to impede comprehension and the structure aids fast scanning.

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

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

With no output schema, the description correctly steps in to describe return values (markdown, PNG, file path) and rendering behavior. For a 10-parameter plotting tool it covers data types, thresholds, coloring and performance adequately; the only gap is the absence of prerequisite/session orchestration guidance, which the schema's session_id description partly carries.

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

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

Schema coverage is 100%, so baseline is 3, and the description meaningfully reinforces it by explaining that thresholds are magnitude filters with real units (default 1.0 = 2-fold, methylation diff in percentage points) and that the abundance significance field is method-aware. This adds interpretive value beyond the schema's field-level text, though it does overlap with several 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?

Opens with a specific verb+resource: 'Create a volcano plot for differential data from the given assay.' It then enumerates exactly which measurement types it supports and how each maps to axes, clearly distinguishing it from sibling finders (find_differentially_*) and create_venn_diagram. An agent knows precisely what this tool produces without opening the schema.

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

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

The per-data-type breakdown tells the agent which data_type to choose and which threshold applies, which is useful internal guidance. However, it never states when to prefer this over adjacent tools (e.g., the differential finders that would precede plotting) or any preconditions such as which assay types are plottable. Usage is implied through the data-type taxonomy rather than explicitly framed as when/when-not.

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

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

Annotations only declare readOnlyHint=false, openWorldHint=false and idempotentHint=true. The description adds the key behavioral facts the annotations omit: what is destroyed (output-directory setting and held plots), that termination is optional because sessions self-expire, and the follow-up requirement to re-create a session.

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

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

Three short sentences, the destructive effect front-loaded, then optionality, then the follow-up requirement. No filler or redundant restatement of the tool name.

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

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

A simple one-parameter lifecycle tool with no output schema and adequate annotations; the description covers the effect, destructiveness, optionality, and postcondition, leaving nothing an agent needs before calling it.

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

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

Schema description coverage is 100% and the session_id parameter is thoroughly documented in the schema itself (identity semantics, privacy, reuse across calls, re-creation on expiry). The description adds no parameter-level detail, so the 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?

Specific verb+resource ("End a session") plus the exact consequences of the action (discards the output-directory setting and all plots it holds). An agent can distinguish this from sibling create_session without opening either schema.

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

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

Explicitly states when to call it ("when the user is done, to free server memory promptly") and when it is unnecessary ("Optional — sessions also expire on their own"), plus the postcondition that a new create_session() is required for further calls. The alternative to calling it is named.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses registry bounds (last 8 plots, FIFO eviction), the error behavior for expired or foreign sessions, and equivalence to the resources/read URI. These are material operational facts the annotations cannot convey.

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 a single-sentence summary, then clearly labeled sections that make scanning fast. Slightly verbose in places (registry bounds restated in both description and schema), but every section carries actionable information.

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

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

For a no-output-schema lookup tool, the description covers return semantics (same bytes as resources/read), failure modes (not-in-registry, expired session), and the recovery path (re-run the source plot tool). Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents filename provenance and session_id semantics thoroughly. The description reinforces registry scope but adds little parameter-level meaning beyond what the schema states, so the baseline 3 applies.

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

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

States a specific operation (re-fetch PNG bytes) and resource (a plot previously generated in this session), and explicitly distinguishes itself from the sibling generators create_volcano_plot and create_venn_diagram by declaring it does NOT re-render. An agent can identify the tool's role without opening any schema.

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

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

Provides an explicit 'WHEN TO USE' section with three concrete cases (corrupted inline image, downstream byte consumption, re-display without re-running analysis) and a 'WHAT THIS TOOL DOES NOT DO' section naming the alternatives to use when data has changed. When-to-use, when-not-to-use, and alternatives are all covered.

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 cover the safety profile (readOnlyHint=true, idempotentHint=true, openWorldHint=false), and the description adds real net-new behavior: pooled-methylation union semantics across a list of assays ('hypermethylated if it passes the threshold in ANY of the pooled assays') and the return artifacts (four-quadrant markdown summary and inline combined CSV). It does not cover failure behavior, empty-overlap handling, or result size, but the added disclosure goes meaningfully 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 routing instruction is front-loaded, which is the right priority. However, the opening parenthetical (pooling, MethylationRegion filtering, direction categorization, lost outputs) substantially duplicates the numbered step list that follows, so some sentences do not fully earn their 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 an 11-parameter cross-analysis tool with no output schema, the description covers inputs (DE/DM thresholds, location filters, pooling), the algorithm, edge cases (replicate assays, promoter silencing), and the return artifacts. An agent has everything needed to call it correctly and interpret results.

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

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

Schema description coverage is 100%, so 3 is the baseline, but the description adds semantics the schema does not: it explains the union-across-assays semantics for a list-valued methylation_assay_id and gives a worked rationale for in_promoter=True. Thresholds and distance filters are left to the schema, which is reasonable.

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

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

The description states a precise verb+resource: 'Find differentially expressed genes that overlap with differentially methylated regions', and then enumerates the four internal steps (DE fetch, DM fetch, intersection, direction categorization). This distinguishes it cleanly from sibling probes like find_differentially_expressed_genes and find_differentially_methylated_regions, which only handle one data type.

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 routes the agent: 'USE THIS TOOL (not the `query` tool) for any expression-methylation coupling...' and names the alternative and what is lost by falling back (four-quadrant intersection logic, markdown summary, combined CSV). It also gives a concrete condition for the special case: pass in_promoter=True for the classical silencing question, and pass a list when a study has replicate methylation assays.

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

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

Annotations only cover readOnly/idempotent/openWorld, so the description carries the rest and does so well: it discloses the internal algorithm (parallel fetches, method-aware significance filtering, separate increased/decreased intersections), the null-handling of lnfc that would drop DESeq2 rows, and the output artifacts (markdown tables, inline CSV side-channel, assay-reference legend).

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 routing guidance, which is good, but the first paragraph is a single dense run-on and several facts are stated twice (log2fc populated for both methods / universal magnitude filter; lnfc is ANCOM-BC-only). Roughly a third of the text could be cut without loss.

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?

Even without an output schema, the description describes the return shape (markdown tables of common organisms with log2fc, CSV side-channel, legend) and fully covers the filtering semantics an agent needs for a 6-parameter, cross-assay intersection tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains WHY log2fc_threshold is the universal magnitude filter and WHY lnfc_threshold is method-aware (using lnfc for direction would null-filter every DESeq2 row). That rationale is not inferable from the schema text alone.

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

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

States a specific verb and resource with explicit scope: 'common differentially abundant organisms across multiple assays', distinct from the per-assay `find_differentially_abundant_organisms` sibling. The description also names the anti-pattern tool (`query`) so an agent can separate the two without opening schemas.

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

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

Explicitly says 'USE THIS TOOL (not the `query` tool)' and enumerates the triggering question phrasings ('common differentially abundant organisms across assays', 'increased in BOTH assays', 'shared abundance signals across methods'). It even explains the cost of the wrong choice (reproducing per-assay fetch + inner-join and losing the markdown/CSV output).

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

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

Annotations only cover the safety profile (readOnly, idempotent, openWorld=false), but the description goes well beyond that: it discloses the internal algorithm (parallel fetches via a connection pool, |log2fc| threshold filtering, separate up/down intersections) and the return format (markdown table, inline CSV side-channel, assay-reference legend). Since there is no output schema, this disclosure carries real weight.

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 routing guidance is front-loaded, which is the right priority, but the closing paragraph ('Find common differentially expressed genes across multiple assays' followed by the numbered steps) partly restates the opening sentence. Efficient overall, with one redundant segment.

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

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

With no output schema, the description correctly compensates by describing the returned table's columns, plus CSV and legend side-channels. The one soft spot is that the two distinct thresholds (adjusted p-value vs. log2fc) are not clearly separated in the prose, leaving adj_p_threshold semantics to the schema alone.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema; this establishes the baseline of 3. The description adds context for the log2fc threshold (used as '|log2fc| > threshold') but says nothing about adj_p_threshold beyond the generic step-2 'threshold' phrasing, and nothing new about session_id or assay_ids.

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

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

States a specific verb and resource ('Find common differentially expressed genes across multiple assays') and names the exact sibling it is not ('not the `query` tool'). An agent can distinguish it from query and from find_differentially_expressed_genes without opening any schema.

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

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

Explicitly enumerates trigger phrasings ('common DEGs across assays', 'genes upregulated in BOTH assays') and names the alternative (`query`), including what is lost by using the wrong tool. This is as close to unambiguous routing guidance as it gets.

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 cover the safety profile (readOnly, idempotent, not open-world), and the description adds internals beyond that: parallel fetches, filters applied inside the Cypher query so the common set reflects the filtered universe, separate hyper vs. hypo intersections, and a markdown output with an inline CSV side-channel and assay-reference legend. That is meaningfully more than the structured fields 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 routing instruction and rationale are correctly front-loaded, but the long parenthetical inventory of query-fallback losses is verbose, and the numbered 4-step list largely restates the opening paragraph and the closing filter admonition. Every sentence is relevant, yet the same points are made two or three times.

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

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

With no output schema, the description compensates by naming the return format (markdown tables of common genes with methylation_diff values, plus an inline CSV side-channel and assay-reference legend). All 8 parameters are documented and the cross-assay join semantics are explained, so nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantic guidance: location filters must be passed as parameters rather than post-filtered because they constrain the Cypher universe, and it reframes in_promoter as the way to ask 'commonly hypermethylated IN THE PROMOTER across these assays'. It does not explain the interaction between the two thresholds or the dist-to-feature units beyond the schema.

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

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

States a specific verb+resource ('Find common differentially methylated genes across multiple assays') and deliberately carves out scope against both the sibling single-assay tool and the generic `query` tool. An agent can route to it correctly from the description alone.

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

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

Opens with an explicit 'USE THIS TOOL (not the `query` tool) for ...' directive naming several trigger phrasings (cross-assay intersections, shared hyper/hypo regions, promoter-filtered variants) and explains what is lost by falling back to `query`. This is the when-to-use/when-not pattern at its strongest.

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 readOnlyHint/idempotentHint, but the description goes far beyond them: it discloses the method-aware significance branch (adj_p_value for DESeq2 vs q_value for ANCOM-BC), the lnfc-null population difference, the failure mode a naive `lnfc > 0` filter would cause, and that two separate queries are executed for the increase/decrease lists. This is exactly the kind of behavioral context annotations cannot carry.

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 routing directive, then organized into clear sections (return shape, direction field, significance filtering, magnitude filtering, query mechanics). The universality of log2fc is explained more than once across paragraphs, which is mild redundancy given the tool's genuine 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?

Though there is no output schema, the description enumerates returned fields (organism name, log2fc, lnfc, q-value, adj-p-value, group means/SDs) and fully explains the filtering pipeline an agent needs to predict results. Nothing material for correct invocation is missing.

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

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

Schema coverage is already 100%, but the description adds a real conceptual model: why log2fc (not lnfc) is the universal direction field, why lnfc_threshold is method-aware and cannot affect DESeq2 rows, and how the two significance thresholds map to their respective methods. Only session_id and top_n are left entirely to the schema, which is a minor gap against an otherwise strong semantic explanation.

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

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

States a specific verb+resource ('Return the top-N organisms with increased and decreased differential abundance for a given assay_id') and explicitly names the sibling it is not ('USE THIS TOOL (not the `query` tool)'). The scope qualifier 'for a single assay' further separates it from the find_common_* siblings. An agent can select it without opening the schema.

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

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

Gives an explicit when (any differentially-abundant-organisms, DESeq2/ANCOM-BC abundance, or increased/decreased question for a single assay) and an explicit when-not (the `query` tool), plus the concrete cost of choosing wrong (loss of markdown tables, CSV side-channel, method-aware filtering, safe lnfc handling). 'For a single assay' also implicitly routes away from the common-across-assays sibling.

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, and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the two-query execution model, the filter conditions (log2fc sign, adj_p_value), the retained markdown/CSV side-channel, and the returned columns. It stops short of describing pagination or size limits on large result sets.

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

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

Front-loads the routing decision in the first sentence and then describes behavior in short, scannable blocks. Slightly verbose in the 'Returning all passing rows' section, which partly restates the schema's top_n description, but no sentence is truly wasted.

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

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

For a read-only analysis tool with no output schema, the description fully covers invocation intent, filter semantics, the top_n=None alternative, and the returned fields, so an agent has everything needed to call it 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 coverage is 100%, so the baseline is 3. The description nonetheless adds real meaning: it explains the top_n=None bypass (return ALL passing rows), the filter semantics that the ranking applies, and the full column set returned, going beyond the schema's per-field text.

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

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

States a specific verb+resource ('Return the top-N up- and down-regulated genes for a given assay_id') and explicitly scopes to a single assay, distinguishing it from siblings like find_common_differentially_expressed_genes and the generic query 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?

Explicitly routes the agent: 'USE THIS TOOL (not the `query` tool)' for up/down-regulated genes, DEGs, or differential expression questions, and names the exact condition ('all significantly up/downregulated genes') under which top_n=None should be used instead of a ranked 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 only declare readOnly/idempotent/openWorld=false; the description goes well beyond them by disclosing that two ordered queries run (hyper descending, hypo ascending), that pooling adds an `assay_id` column and duplicates shared regions, that filters execute inside the Cypher rather than being post-applied, and that markdown is capped at 100 rows while CSV carries every row. This is unusually rich 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?

Front-loaded and well sectioned, but noticeably redundant: the 'use this tool, not `query`' instruction and the CSV/markdown benefit are stated in the opening paragraph and again in the closing 'WHEN TO USE' block, and the `top_n=None` semantics duplicate the schema description. Every sentence is relevant, but several repeat the same point.

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

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

With no output schema and 9 parameters, the description carries the full burden and does so: it explains the return shape (formatted markdown plus inline CSV side-channel), the row addressing (assay_id column), and the truncation behavior. Nothing an agent needs to call or interpret this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not carry on its own: the rationale for `top_n=None`, the warning that post-filtering an unfiltered top-N yields wrong rankings, and the note that multiple location filters combine with AND. It also restates some schema content (thresholds, pooling), which caps it at 4 rather than 5.

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

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

States a specific verb+resource (return hyper- and hypo-methylated regions for one or more assays) and immediately positions itself against the sibling `query` tool. An agent can tell what it does and that it is the canonical entry point for DMR questions without opening the schema.

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

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

Explicitly enumerates when to use it ('any hyper/hypo-methylated regions, DMRs, or differential methylation question — including all-rows requests, promoter/exon/intron-filtered queries, and pooling across replicate assays') and names the alternative (`query`) plus the cost of choosing it. Exclusions and trigger phrases are both present.

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, and closed-world scope, so the safety profile is covered. The description adds genuine behavioral value beyond that by disclosing a concrete failure mode (Neo.ClientError.Procedure.ProcedureNotFound) and the remediation (install/enable APOC), which the agent cannot derive from 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?

Two short sentences that are front-loaded with the primary purpose, with no filler. The second sentence has an awkward mid-sentence line break that slightly hurts readability but not meaning.

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 read-only introspection tool with no output schema, the description does enumerate what is returned (nodes, attributes, relationships). Combined with the error/remediation note and annotations covering safety, an agent has enough to call it correctly, though the granularity of the returned structure remains unspecified.

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

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

There is only one parameter (session_id) and the schema description coverage is 100%, with a thorough explanation of session lifetime and reuse in the schema itself. The description adds nothing about the parameter, so the baseline of 3 applies.

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

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

States a specific verb (list) and resource (nodes, attributes, relationships) in the neo4j database, which is clear and concrete. It does not explicitly differentiate itself from close siblings such as get_node_metadata, get_relationship_metadata, or visualize_schema, so an agent must infer that this returns the whole graph schema rather than a per-element view.

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

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

There is no explicit when-to-use guidance versus alternatives like get_node_metadata or visualize_schema. The APOC plugin advice is conditional troubleshooting rather than usage routing, though it does give the agent a clear next step on a specific failure.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety/behavior is covered by structured data. The description adds only a scope hint ('all nodes'), with no disclosure of pagination, return shape, or size limits, so it is merely adequate given the annotation coverage.

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

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

A single front-loaded sentence with no filler. It is efficient, though the awkward 'nodes from MetaNode nodes' phrasing slightly undercuts 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?

For a simple rea d-only tool with annotations and no output schema, the definition is minimally viable. It does not explain what metadata is returned or what a 'MetaNode' is, which an agent would need to interpret results.

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

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

With schema coverage at 100% and a single optional session_id fully documented in the schema, the baseline of 3 applies. The description provides no additional parameter meaning beyond what the schema already states.

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

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

States a specific verb (Get) and resource (metadata for nodes) with a scope qualifier ('all nodes'). However, the phrase 'from MetaNode nodes' introduces unexplained jargon and the description never names the closely-related sibling get_relationship_metadata or get_neo4j_schema, so sibling differentiation is only implicit.

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 when-to-use guidance is given. Nothing indicates when an agent should call this versus get_relationship_metadata, get_neo4j_schema, or query, and no prerequisites are 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 already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered. The description goes further by disclosing session-scoped behavior (the path is tied to the same session) and the exact shape of the return (a path or a note with remediation), which is genuinely 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?

Two sentences, zero filler, with the core action front-loaded and the return-value behavior in the second sentence. Every clause earns its place.

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

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

For a read-only getter whose annotations cover the safety profile and have no output schema, the description fills the important gap by explaining what is returned (a path or an explanatory note). Complete enough to call correctly; only the session-expiry reply handling is left to the schema's session_id text.

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

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

Schema coverage is 100% and the single session_id parameter is fully documented in the schema, including the multi-user privacy rationale and the re-create-on-expiry guidance. The description adds nothing param-specific, so the baseline 3 applies.

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

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

States a precise verb+resource (return the configured output directory) scoped to the current session, and explicitly ties it to its sibling set_output_directory. An agent can distinguish it from set_output_directory without opening either schema.

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

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

The description makes the retrieval context clear and names set_output_directory as the mechanism that populates the value, plus explains the empty case and how to fix it. It does not spell out an explicit 'use this when...' trigger, but the counterpart relationship is unambiguous.

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, and openWorldHint=false, so the safety profile is covered. The description adds almost nothing beyond that — it restates scope ('all relationships') but gives no behavioral detail such as the shape of the returned metadata. With no output schema, more disclosure would have been warranted.

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

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

One sentence, front-loaded with the verb and scope, with zero waste. Nothing to trim.

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 introspection tool this is minimally adequate: annotations cover safety and the schema covers the one parameter. However, with no output schema the description never explains what the returned 'descriptions' look like, leaving the agent guessing about the response shape.

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

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

Schema description coverage is 100% and the single session_id parameter is documented in rich detail in the schema itself, so the baseline is 3. The description contributes nothing about the parameter, but nothing is missing either.

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?

Names a specific verb and resource ('Get descriptions of properties of all relationships') and implicitly distinguishes itself from the sibling get_node_metadata by scoping to relationships rather than nodes. Clear, though it never explicitly contrasts with that sibling.

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

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

Usage is only implied: an agent infers this is for schema introspection before writing queries, but there is no explicit when-to-use guidance, no mention of get_node_metadata / visualize_schema / get_neo4j_schema as alternatives, and no stated 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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), but the description adds substantial behavioral context beyond them: a session registry capped at the last 8 plots with FIFO eviction, the fact that the response contains no PNG bytes, and the three concrete save options offered. This is exactly the kind of operational detail annotations cannot express.

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 core purpose and then cleanly partitioned into WHEN TO USE, HOW IT WORKS, and LISTING AVAILABLE PLOTS sections. It is on the long side, but nearly every sentence carries distinct load-bearing information (eviction cap, no-bytes caveat, option breakdown), so little is wasted.

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

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

With no output schema, the description carries the return-value burden itself: it describes the markdown block, the three save options, and explicitly states the response contains no PNG bytes and points to plot:// URIs instead. Nothing needed to invoke or interpret the tool correctly is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces parameter behavior with a dedicated 'LISTING AVAILABLE PLOTS' section explaining that omitting filename lists all plots, tied to a real use case ('user doesn't remember which plot'), adding mild meaning over the schema.

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

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

States a specific verb+resource with scope: 'Return guidance for saving a plot generated in THIS SESSION to the user's local filesystem.' It also names the sibling plot tools (create_volcano_plot, create_venn_diagram) and the fetch_plot/plot:// alternatives, so an agent can distinguish it without opening any schema.

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

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

Has an explicit 'WHEN TO USE THIS TOOL' section with the trigger condition ('only when the user explicitly asks for save guidance'), concrete user-phrasing examples, and the rationale that plot tools return only a short hint by default. It also routes to alternatives (fetch_plot, plot:// resource) for re-fetching bytes.

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 readOnly, idempotent, closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the structured return shape (metadata, assays with technology/measurement type/factors/materials, missions) and the 'formatted markdown + inline CSV side-channel' output behavior. It omits any caveats about missing studies or rate limits, keeping it short of a 5.

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

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

Key routing advice is front-loaded and capitalized so it cannot be missed. There is mild redundancy, however: the opening routing block and the standalone sentence 'Return detailed information about a study, including its assays with their technology and measurement types' overlap with the numbered bullet list that follows.

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

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

No output schema exists, so the description must explain return values, and it does so thoroughly via three enumerated return categories plus a worked example (OSD-267 -> 16S and ITS amplicon sequencing). Nothing needed to call the tool correctly is missing.

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

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

Schema coverage is 100%: study_id and session_id are both fully documented in the schema, including the example 'OSD-267' and the session-privacy semantics. The description reinforces that the tool centers on a study but adds no new syntax or format detail. Baseline 3 applies when the schema carries the load.

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

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

States a specific verb and resource (retrieve a study's metadata and assay inventory) and explicitly names the sibling it displaces ('not the `query` tool'). Concrete examples of questions it answers ('what assays does study X have', 'tell me about OSD-267') make the scope unmistakable.

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

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

Gives explicit when-to-use guidance ('any study-metadata question'), enumerates the qualifying question types, and warns against the wrong path ('falling back to `query`... reproduces the work this tool already does'). This is the strongest possible routing guidance.

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

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

Annotations already declare readOnly/idempotent/openWorld=false, and the description layers substantial additional behavior on top: the `total_rows` header semantics, server-side counting before truncation, side-file storage of large results, method-aware null handling on abundance edges, and required directed-arrow traversal. This is genuinely load-bearing context an agent could not infer from annotations alone.

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 correctly — the fallback-only rule and the routing table come before the schema minutiae. However the definition is very long, and a large block (node properties, relationship directions, edge field lists) duplicates information that arguably belongs in get_neo4j_schema/get_node_metadata rather than being restated in every call context.

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

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

No output schema exists, and the description compensates fully: it specifies the `total_rows`/`rows`/JSON-array response shape, truncation behavior, and how counts surface in aggregate queries. For a complex, open-ended Cypher surface with three params, nothing an agent needs to call it correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond by documenting the semantics of the graph the `query` string must target — exact node/relationship property names, edge-attribute fields, and the anti-patterns (e.g. mg.gene_symbol) that the schema cannot express. It doesn't add much on `params` or `session_id` beyond the schema, keeping it from a 5.

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

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

Opens with a specific verb+resource framing ('FALLBACK Cypher executor') and immediately nails its scope relative to siblings by naming exactly which questions it is not for. An agent can distinguish this from get_neo4j_schema, select_assays, and the find_* specialists without opening any schema.

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

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

Provides an unusually explicit when/when-not routing table that maps user question patterns to named alternative tools (find_differentially_expressed_genes, select_assays, etc.), including the instruction to resolve study→assay IDs first rather than writing Cypher. The exclusion criteria ('DO NOT call this tool when...') and the fallback conditions are stated directly.

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

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

Annotations only declare readOnly/idempotent/no-open-world; the description adds substantial non-structured behavior: a two-call stateful workflow (menu first, then indices), the even-number pairing requirement, the returned columns (technology/measurement/method/material) and the concrete loss from falling back to `query` (lost menu, lost per-match columns, lost next-step suggestions). This is well beyond what the annotations convey.

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 routing decision and two clearly bulleted modes; every section is functional. Slight redundancy across the overlapping example phrasings ('What groups / conditions / control and experimental groups...') and the repeated query-fallback warning, but nothing is truly wasted.

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

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

With no output schema, the description carries the return-value burden and does so — it describes the numbered factor-menu markdown table, the per-assay comparison framing, and the per-match columns. Missing-`study_id` handling and the session-permission note are also covered, so an agent has everything needed to call it 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 coverage is only 33% (only `session_id` documented), so the description must compensate for `study_id` and `selection` — and it does, explaining the list-vs-resolve semantics of `selection` string ('2,1'), the even-index pairing rule, and study id examples ('OSD-48', 'OSD-253'). It stops short of a full format spec for `study_id`, so not a 5.

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

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

States a specific verb+resource (list/select assays for a study) and immediately distinguishes itself from the sibling `query` tool ('USE THIS TOOL (not the `query` tool)'). Two distinct modes (list factor menu vs. resolve factor pair) are named with concrete examples, so an agent can tell it apart without opening the schema.

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

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

Explicit when-to-use with quoted user phrasings, explicit when-not ('Never use `query` for this'), and two named alternatives-by-mode: call with just `study_id` for list mode, or with `study_id`+`selection` for resolution. The condition that selects each mode is unambiguous.

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?

Far exceeds the annotations (readOnlyHint=false, idempotentHint=true): it discloses session-scoped state keyed on session_id, that other sessions cannot read or change it, that the stored path propagates as summary and save-guidance, and critically that a remote container CANNOT write to the user's local disk and why. It also explains validation is a no-op. This is exactly the behavioral context annotations cannot convey.

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?

Header-based structure and front-loading are good, but it runs ~350 words for a single-parameter setter and contains repetition — the 'serves a suggestion / cannot write to local disk' point is restated across the IMPORTANT section, the (a)(b)(c) sub-list, and VALIDATION. Several sentences could be cut without losing meaning.

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

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

With no output schema and only two parameters, the description covers everything an agent needs: when to call, what state is mutated, session keying, and the deployment caveats that shape what the agent should tell the user afterward. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: the path is stored as-is, the server cannot verify existence, and a relative or malformed path will still be accepted and only fail at save time. That validation-transparency is genuine added value over the schema text.

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

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

States a specific verb and resource ('Configure the output directory for files generated in THIS SESSION') with explicit session scoping. It clearly distinguishes itself from the read-only sibling get_output_directory and marks the session boundary. An agent knows exactly what this tool does without opening the schema.

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

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

A dedicated 'WHEN TO USE' section says to call it at the START of a session right after create_session and before any file-producing tool, naming the concrete siblings (create_volcano_plot, create_venn_diagram, CSV emitters). This is explicit when-to-use guidance with a concrete trigger point.

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, and openWorldHint=false, so the safety profile is covered. The description adds that the tool yields a prompt rather than a rendered image, but it does not say what consumes the prompt or what the returned text looks like.

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

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

A single front-loaded sentence with no filler. It is efficient, though the brevity leaves room for a clarifying clause about the prompt-only nature.

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

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

With no output schema, the description should explain what is returned and how it is used. Saying 'Prompt for visualizing' hints at text output but does not tell the agent whether it must forward the prompt to an LLM or render the Mermaid itself.

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 single session_id parameter has 100% schema coverage with a thorough description of its privacy role and re-creation behavior. The tool description adds nothing about parameters, so the baseline 3 applies.

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

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

The description pairs a clear action with its resource and output format: producing a prompt that visualizes the knowledge graph schema as a Mermaid class diagram. It is distinguishable from get_neo4j_schema, though it never names that sibling or clarify why a separate schema tool exists.

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 when-to-use guidance, no prerequisites, and no mention of the obvious alternative get_neo4j_schema or clean_mermaid_diagram. The agent must infer that this is the diagram-oriented path versus the raw schema lookup.

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