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

Annotations already establish readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds the key behavioral fact that no search is executed and enumerates the analysis output (complexity, intent, PICO, recommendations), which is genuine value 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?

Front-loads the core action and constraint in the first sentence, then efficiently documents args and returns. The Returns list is a bit verbose but each line conveys distinct return fields.

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 enumerating the analysis return fields. For a single-param read-only tool whose annotations cover safety, this is nearly complete; only deeper query-format guidance 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 0% and there is one parameter, so the description must carry the meaning. It only restates 'query: The search query to analyze' with no added syntax, format, or length guidance beyond the schema's minLength/maxLength constraints.

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

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

States a specific verb and resource ('Analyze a search query') and immediately scopes it with the constraint 'without executing the search', which cleanly distinguishes it from the sibling unified_search.

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 frames usage as a pre-flight step to unified_search ('understanding how unified_search will process your query before actually running it'), naming the alternative and the condition that selects this tool. It does not state when not to use it, but the routing 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 and idempotentHint=true, but the description adds substantial behavioral detail: API load control via single-PMID restriction, performance caveats for depth=3 ('~100+ API calls'), return format (Markdown summary followed by JSON graph data), and the guarantee that metadata and statistics are included regardless of format. This goes well 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-organized with clear headers, bullet lists, and practical examples, and the critical single-PMID warning is front-loaded. However, it is somewhat redundant: the output_format options are listed twice—once in the overview and again in the Args section—with overlapping wording. Some trimming would make it tighter without losing 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 five parameters, no output schema, and multiple dependent concepts, the description is remarkably complete. It covers input constraints, parameter semantics, performance behavior, output structure, format options, and example invocations. An agent has everything needed to select and invoke the tool correctly, including how to interpret the returned data.

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 the description must carry the full burden of explaining parameters, and it does. Each parameter—pmid, depth, direction, limit_per_level, output_format—receives meaningful semantics including examples, default values, allowed ranges, and format-specific use cases. The description fully compensates for the empty 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 opens with 'Build a citation tree (network) from a single article,' a specific verb-resource pairing that clearly defines the tool's function. It further distinguishes itself from siblings like find_citing_articles and get_article_references by emphasizing the visual network/lineage aspect across both citing and referenced directions, making the tool's unique purpose 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?

The description provides clear usage context: it accepts only one PMID at a time, explains multi-paper usage, and recommends defaults like depth=2 and direction='both'. However, it does not explicitly instruct when to prefer this tool over sibling tools such as find_citing_articles or get_article_references, nor does it state exclusions beyond the single-PMID constraint.

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 annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses key behavioral traits: it persists a revision-numbered chronicle, re-running creates revision N+1, artifact failure is reported without rolling back the saved chronicle, and agreement between projections is not independent evidence verification. This is rich, non-obvious 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?

Although long, the description is tightly organized and information-dense: a front-loaded definition, a concise conceptual model, then a structured Args block and Returns explanation. Every section adds decision-relevant detail for a complex 7-parameter tool, and no sentence merely restates the tool name or schema.

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 no required parameters, no output schema, and three invocation modes, the description is complete. It covers all parameter interdependencies, rendering formats, return behavior, artifact persistence, and failure semantics, leaving no critical gap an agent would need to guess about.

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 the description carries the full burden, and it delivers. Every parameter is semantically explained: topic's mutual exclusivity with pmids/chronicle_id, the special 'last' value for pmids, max_events inheritance behavior, year bounds, chronicle_id continuation semantics, and detailed return-type differences for output values.

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

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

The description opens with a precise verb-plus-resource statement: 'Build a persisted, versioned, evidence-backed Research Chronicle.' It then distinguishes itself from older one-shot timeline tools and names its role as the single entry point for research-evolution work, making it easy for an agent to differentiate this from siblings like read_research_chronicle.

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 usage conditions explicit: it replaces older one-shot timeline tools, topic mode versus pmids mode versus continuing via chronicle_id are clearly explained, and parameter-specific guidance (e.g., 'pmids="last"', 'Passing it alone re-runs the stored scope') tells the agent exactly when each invocation style is appropriate.

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, destructiveHint=true, and idempotentHint=true. The description adds meaningful behavioral context: remote callers can inspect the operator-installed configuration with no arguments, cannot mutate server-owned OpenURL settings, and should configure those via deployment or a trusted local server. It does not explicitly state what happens if a remote caller attempts mutation or whether applying a preset overwrites existing settings.

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 front-loads the core purpose and security constraint, but it is long and includes nonessential content such as the four-step 'HOW IT WORKS' explanation and detailed 'FINDING YOUR RESOLVER URL' instructions. The ASCII decoration adds visual structure but also verbosity; it is more of a user guide than a tightly focused agent tool definition.

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

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

Given no output schema, the description at least states 'Returns: Configuration status message.' It covers all invocation modes, parameter semantics, preset options, and the important remote-vs-deployment permission distinction. It would be more complete if it pointed to test_institutional_access or diagnose_institutional_access for verifying or troubleshooting the configured access, and if it described the return format more precisely.

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 well by explaining resolver_url, preset, and enable, including examples and the note that sfx, 360link, and primo require resolver_url. It maps to all three parameters and gives defaults for enable. Minor gaps: the preset 'test_free' from the schema is not documented, and the description does not state whether preset and resolver_url are mutually exclusive.

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 a specific verb and resource: 'configure your institution's link resolver for full-text access' and 'This tool configures OpenURL link resolver integration.' It is distinct from most sibling tools by name and stated purpose, though it does not explicitly contrast itself with close siblings like test_institutional_access or diagnose_institutional_access.

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

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

The description gives three concrete usage modes: preset, custom URL, and disable. It also provides an explicit boundary for remote callers: they may inspect with no arguments but cannot mutate server-owned deployment-wide settings, and should configure those at deployment time or from a trusted local server. It does not explicitly mention sibling tools like list_resolver_presets as alternatives, but the context is otherwise 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 cover read-only, idempotent, and closed-world traits, so the bar is lower. The description adds genuinely useful context beyond them: the crosswalk is 'curated' and a 'limited convenience' mapping, disclosing data-quality/coverage limitations an agent would not otherwise know.

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

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

Two tight sentences, front-loaded with the core purpose and followed by direction routing and a limitation. No filler; every clause carries 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?

No output schema exists, so the description bears the burden of describing returns. It gestures at the mapping quality ('limited convenience crosswalk') but never describes the shape of the result (single term vs. list, ambiguity handling), leaving a gap for a mapping 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 description coverage is 0%, so the description must compensate, and it does: it explains that 'value' must be one complete ICD-9-CM or ICD-10-CM code for the icd_to_mesh direction or a MeSH term for mesh_to_icd. It does not address code formatting (dots) or the 500-char limit, so it is not exhaustive.

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: 'Query the curated ICD/MeSH crosswalk in one explicit direction.' An agent immediately knows this maps between ICD and MeSH vocabularies, and no sibling tool covers terminology crosswalking, so differentiation is moot.

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 each enum value: 'icd_to_mesh' with a complete ICD-9-CM/ICD-10-CM code, 'mesh_to_icd' with a MeSH term. It also adds a when-not caveat (not a substitute for a licensed UMLS service), which is exactly the kind of selection guidance an agent needs.

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 destructiveHint=true and idempotentHint=true, but the description adds genuinely useful context beyond them: that execution history is destroyed (not just the config) and that process-level schedules are removed only after the deletion succeeds, with isolated tenants exempt from scheduler mutation. That is real side-effect disclosure 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-loads the destructive action in the first sentence, then adds the tenant/scheduler caveat, then Args/Returns. Efficient and well-organized, though the tenant-scheduler sentence is somewhat more detailed than most callers need.

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 covers the return ('Confirmation of deletion'), the scope of destruction, and the scheduler side effect. It is nearly complete for a single-parameter destructive tool; only name-discovery and irreversibility recovery guidance are 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 0% and the description only restates the obvious ('name: Name of the saved pipeline to delete'). It does not explain the naming constraints already implied by the schema (lowercase, pattern, 64-char limit) or how to discover valid names, so it adds little beyond a bare restatement.

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 ('Permanently delete a saved pipeline configuration and execution history'), which is enough to separate it from save_pipeline, list_pipelines, and load_pipeline. It does not explicitly contrast itself with the very similar unschedule_pipeline sibling, which also touches scheduling, so sibling differentiation is only partial.

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: the word 'Permanently' hints this is the irreversible removal path, but there is no explicit when-to-use/when-not guidance and no pointer to unschedule_pipeline for the case where the user only wants to cancel scheduling. The agent must infer the boundary between delete and unschedule.

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 read-only/idempotent/open-world, but the description adds substantial operational context beyond them: a three-phase probe strategy, IP-awareness, BYO-cookie EZproxy replay, the specific env vars required, and a manual OpenURL handoff. It also discloses that a PMID is converted to a DOI before probing.

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 one-line purpose, then a numbered probe list, usage examples, and args/returns sections — well organized and largely waste-free. It is on the long side, but the length is justified by the multi-phase behavior and configuration requirements.

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 by describing the return value ('Markdown report listing every probe's status, classification, and advice'). Combined with the phase breakdown and required env vars, an agent has everything needed to invoke and interpret 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?

Schema description coverage is 0%, so the description carries the burden and largely does: 'source' is explained as exactly one PMID or DOI with the PMID-to-DOI resolution note, and try_direct/try_ezproxy are mapped to Phase 1 and Phase 2 with their defaults. Minor gap: it doesn't restate the DOI/PMID value formats already enforced by the schema patterns.

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 ('Diagnose why institutional fulltext access succeeds or fails for an article') and enumerates the three probe phases, which cleanly separates it from siblings like test_institutional_access and configure_institutional_access. An agent can identify the tool's job 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?

Explains the conditions under which each probe runs (IP allow-list auto-works; EZproxy requires env vars; OpenURL is a manual fallback) and provides concrete usage examples with try_ezproxy=False. However, it never explicitly routes the agent against alternatives such as test_institutional_access or get_fulltext, leaving that comparison to inference.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral detail beyond annotations, especially the batch failure semantics: inputs fail as a complete batch when any PMID is invalid. This is genuinely useful and not inferable from schema or 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 compact, well-organized with 'Args' and 'Returns', and front-loads the core purpose before parameter details. The bulleted pmids format list is efficient. The only minor issue is the slightly ambiguous phrase 'Inputs are string-only' after listing array support, and the 'Returns' line adds little beyond the first sentence.

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 output schema, the description covers batch input behavior and the main parameter well. But it omits the output_format parameter, does not explain return details or structure, and lacks guidance on when this tool is preferable to sibling tools. These gaps leave the agent with uncertainty about how to use the tool effectively in a larger workflow.

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 the description must compensate. It does a good job for pmids by listing accepted formats and the string-only constraint. However, it completely ignores output_format, which is surfaced only in the schema. The enum and default are self-explanatory, but the description still misses an opportunity to clarify formats like 'toon'.

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 a specific verb ('Fetch') and resource ('detailed information for ... PubMed articles'), and signals batch capability with 'one or more'. However, it does not distinguish this tool from sibling retrieval tools like get_fulltext, find_related_articles, or get_article_figures, so it falls short of full sibling 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?

The description provides no guidance on when to use this tool versus alternatives, and it does not mention any exclusions or prerequisites. While the accepted pmids formats are documented, the usage context—such as 'use this for article metadata, get_fulltext for full text'—is entirely absent.

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 read-only, idempotent, open-world, and non-destructive behavior. The description adds the PubMed Central citation data source and the forward-in-time direction, but does not cover rate limits, permissions, or detailed return behavior beyond a generic list. With annotations carrying the safety profile, this is useful added context but not exhaustive.

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 core purpose is front-loaded and the description is well organized. However, it is heavily padded with decorative separators, emojis, and repeated headers, and some content is redundant, which hurts conciseness.

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

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

Covers purpose, usage, parameters, data source, and a basic return description. Since there is no output schema, it could more precisely describe the citing-article fields or pagination behavior, but it is largely complete for a simple read tool.

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

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

Schema description coverage is 0%, so the description must compensate. It documents both parameters: the pmid format ('12345678' or 'PMID:12345678') and the limit range/default (1-100, default 10). This fully covers the two parameters and adds meaning beyond the bare 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 and resource: find articles that cite a given PubMed article, explicitly scoped as a forward citation search. The complementary tools section names get_article_references and find_related_articles and explains how they differ, so an agent can select this tool 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?

Provides explicit use cases such as tracking research impact, finding follow-up studies, identifying controversies, and literature review. It also names the backward-search and topic-based alternatives, giving clear when-to-use and when-not-to-use 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 readOnly=true, openWorld=true, idempotent=true and destructive=false, so the safety/profile burden is largely lifted. The description adds genuinely useful behavioral context: the results are algorithm-based similarity (not citation-based), which matters for interpreting output. It doesn't cover error behavior (e.g. invalid PMID) or pagination, but with annotations carrying the safety profile, a 3 is fair.

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 heavily front-loaded and clearly structured, but it is quite verbose for a 2-parameter tool, and a large portion of the diagram (the full workflow) belongs to sibling context rather than this tool's own behavior. Still, the formatting aids scanning. Adequate but oversized.

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, 2-param lookup tool with no output schema, the description is nearly complete: it explains the mechanism, the return concept ('similar papers, not citation-based'), and routing to siblings. The only real gap is that it doesn't explain the shape of returned article details, which matters slightly given no output schema exists.

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 the description must carry parameter meaning. It documents pmid with accepted formats ('12345678' or 'PMID:12345678') and the limit range (1-50, default 5), which the bare schema does not. This meaningfully compensates for the zero-coverage schema, though it could clarify whether limit=50 hits a cap or truncates silently.

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

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

The description states a specific verb and resource ('Find articles related to a given PubMed article') and explicitly differentiates itself from the two sibling citation tools (find_citing_articles, get_article_references) via the workflow diagram, naming the underlying mechanism (PubMed's 'Related Articles' algorithm). An agent can immediately tell what this does and how it differs from siblings.

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

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

The numbered workflow diagram explicitly maps each of the three citation tools to its use case: this one for discovering similar research/related directions, find_citing_articles for impact/forward citations, get_article_references for foundations. It even includes a step-by-step example workflow showing when to reach for each. This is about as explicit as when/when-not guidance 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavior beyond this: it returns raw materials rather than final queries, performs spelling correction via NCBI ESpell, does MeSH/synonym expansion, and can show PubMed's actual interpretation of a query. This gives the agent an accurate model of what the tool does and does not do.

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 purpose and then structured into two clear usage modes, which helps an agent navigate a complex workflow. It is quite long with decorative separators and redundant step numbering, but nearly every section carries operational value, so the verbosity is justified for this 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?

With no output schema, the description fully enumerates the return fields: corrected_topic, keywords, mesh_terms, all_synonyms, and suggested_queries with estimated_count and pubmed_translation. It also covers the two main invocation contexts and how to chain with siblings, so an agent has everything needed to call 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?

Schema description coverage is 0%, but the description's Args section fully compensates. It explains topic as 'a single keyword or PICO element,' defines all three strategy values with their effects on suggested_queries, states defaults for check_spelling and include_suggestions, and clarifies how the parameters affect behavior.

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

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

The description opens with a clear verb and resource: 'Gather search intelligence for a topic' and explicitly frames the output as 'RAW MATERIALS' and 'BUILDING BLOCKS for search, not finished queries.' This distinguishes it from siblings like analyze_search_query and unified_search, whose jobs are to validate and execute queries.

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 two explicit usage modes with step-by-step protocols: Mode 1 for single-topic keyword search and Mode 2 for PICO-based clinical questions. It names exact sibling tools to call before and after this tool, including validate_pico_plan, analyze_search_query, and unified_search, so an agent knows when to use this tool versus alternatives.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful context beyond annotations: it restricts to PMC Open Access articles, explains that PDF links are returned, and clarifies the effects of include_subfigures and include_tables. It does not discuss authentication or rate limits, but these are likely unnecessary for a read-only open API.

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 structured with Args, Returns, and Example sections and front-loads the core purpose. However, the return information is repeated across the opening paragraph and the Returns section, which is mildly redundant.

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 four parameters (one required), no output schema, and annotations that cover safety, the description provides example usage, return content, and parameter guidance, making it largely complete. The missing semantics for output_format and the absence of error or empty-result behavior are 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?

With 0% schema description coverage, the description compensates well for three of four parameters: source is explained with example JSON objects and a note about the discriminated union, and include_subfigures and include_tables are described in functional terms. The output_format parameter is not mentioned at all, leaving a notable gap in parameter semantics.

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

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

The description states a specific verb and resource ('Get structured figure metadata... and PDF links') and scopes it to a PMC Open Access article, clearly differentiating it from tools that fetch full text, references, or general image searches. The inclusion of output fields (label, caption, image URL, PDF links) makes the purpose 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?

The description implies use when figures from a PMC Open Access article are needed, but it does not explicitly state when to use this tool versus alternatives like fetch_article_details, get_fulltext, or search_biomedical_images. No conditions or exclusions 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 declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuine context: the backward-in-time direction, that it returns a bibliography list, and the limit range. It stops short of describing ordering or pagination behavior, but the annotation coverage lowers the bar.

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 core definition is correctly front-loaded in the first three lines, but the rest is bloated with emoji banners, ASCII rules, and a multi-step workflow example that repeats usage information already stated. Much of the decoration does not earn 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 two-parameter read tool with no output schema, the description covers purpose, direction, parameters, and usage adequately; the 'Returns' note is appropriately brief since it is itself a thin summary. Slightly more on result ordering or limit semantics would complete 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 0%, so the description must carry the load. It documents the pmid accepted formats ('12345678' or 'PMID:12345678') and the limit range/default, adding real meaning beyond the bare schema types. It could be slightly richer about what happens at the limit boundary, but it compensates well for the coverage 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?

States a specific verb and resource ('Get the references of a PubMed article') and immediately distinguishes itself from the sibling find_citing_articles by contrasting citation direction. An agent can select this 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 names the alternative (find_citing_articles), gives the condition that selects each, and lists four concrete use cases. Nothing is left to inference about when to reach for this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description adds genuine behavioral context beyond that: fail-closed batching capped at 1,000 unique PMIDs, and the guarantee that iCite transport/response failures surface as retryable errors rather than empty results.

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 purpose, then return fields, then args, then return behavior—logical and scannable. There is mild redundancy in listing the return fields once in the intro and again under 'Returns', but every section still 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?

With no output schema, the description compensates by enumerating returned fields and explaining failure semantics, which is what an agent needs to call and interpret the tool. The only real gap is the undocumented output_format parameter.

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 the description carries the full burden, and it does so well for five of six parameters: accepted PMID formats, meaningful sort_by options with a recommended value, and threshold semantics for min_citations/min_rcr/min_percentile. It omits output_format (markdown/json/toon), leaving one enum undocumented.

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 ('Get citation metrics from NIH iCite for articles'), names the upstream source, and enumerates exactly which metrics are returned. An agent can distinguish this from siblings like find_citing_articles or fetch_article_details 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?

Provides useful in-tool guidance such as accepting 'last' to reuse PMIDs from the preceding search, which implicitly ties it to the search workflow. However, it never states when to prefer this tool over siblings such as find_citing_articles or fetch_article_details, so usage is implied rather than directed.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds value by stating the return payload contents (formula, SMILES, properties), but says nothing about error behavior for invalid CIDs or rate limits on the external PubChem service.

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 one-line purpose followed by short Args/Returns blocks. No filler, though the Args/Returns labels are slightly heavy for a single-parameter 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 simple single-parameter read tool with no output schema, the description supplies enough: purpose, the parameter's meaning, and the shape of the return. The missing piece is routing guidance relative to search_compound.

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 the description must carry the load. It expands 'cid' into 'PubChem Compound ID', which is more than the bare string-typed schema property, but it omits the numeric-string format constraint captured only by the schema pattern.

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 ('Get detailed information about a compound') and names the identifying key (PubChem CID). It does not distinguish itself from the sibling search_compound, but an agent can still tell what this tool does from the name and 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?

There is no guidance on when to use this over search_compound or get_compound_literature, nor any prerequisite or CID-acquisition note (e.g., you must first call search_compound). The agent is left to infer the workflow.

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 and non-destructive, so safety behavior needs no repetition. The description adds genuine value by disclosing provenance ('NCBI's curated compound-to-publication links') and a return summary, though with no output schema this remains thin on pagination or failure 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?

Short and front-loaded, with the core purpose in the first sentence and Args/Returns scaffolding after. The Args/Returns headers are slightly mechanical but cost little and aid scannability.

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 two-parameter read tool with no output schema, the description covers purpose, both parameters, the data source, and the return shape (JSON with linked PubMed IDs). Nothing essential for a 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 description coverage is 0%, so the description must carry parameter meaning, and it does: 'cid: PubChem Compound ID' and 'limit: Maximum PubMed IDs to return (1-100)'. This maps directly to both parameters and clarifies the cid format beyond the bare 'string' pattern, though it adds nothing about what happens when no links exist.

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 ('Get PubMed articles linked to a compound') and names the underlying data source, which cleanly separates it from sibling literature tools like get_gene_literature by resource type. It stops short of explicitly naming or contrasting alternatives, so it is clear but not sibling-differentiating at the highest 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?

The description gives no when-to-use, when-not-to-use, or alternative-tool guidance; an agent must infer from the resource name that this is the right call for compound-linked literature. The mention of NCBI's curated links hints at the data source but not at usage conditions.

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 source-selection order, extended source behavior, browser-session fallback semantics, and the return shape. This is valuable beyond the annotations, which only provide openWorldHint and non-destructive flags. It does not mention potential side effects like external network calls or rate limits, but it covers the core behavioral traits 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 long but every section earns its place: source priority list, extended sources, per-parameter semantics, return value, and examples. It is well-structured with clear headings and no filler, making it easy for an agent to parse and act on.

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 7 parameters, 0% schema description coverage, and no output schema, the description is thorough enough to allow correct invocation. It covers all parameter meanings, defaults, source input formatting, behavior, and return content. No critical operational detail 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 0%, so the description carries the full burden for parameters. It explains every parameter, gives concrete source object examples, clarifies output_format choices, and details allow_browser_session's three modes. This substantially exceeds what the raw schema provides.

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

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

The description clearly states the tool retrieves fulltext from multiple sources, with a specific priority chain and a source discriminated-union requirement. It distinguishes itself from sibling tools by emphasizing multi-source fulltext retrieval rather than metadata-only or figure-specific operations.

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

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

The description gives clear context for when to use the tool: when fulltext is needed and source identifiers (PMID, PMCID, DOI) are available. It also explains how to broaden retrieval with extended_sources. It does not explicitly name alternative sibling tools or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered without the text. The description adds the return shape (symbol, name, summary, location), but says nothing about behavior for invalid/unknown gene IDs, rate limits, or external NCBI dependency despite openWorldHint=true.

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 one-line purpose followed by Args and Returns sections; every line earns its place with no filler or repetition of the schema.

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 Returns block usefully enumerates the JSON fields an agent can expect. Minor gap: no mention of error/missing-gene behavior, which matters for a single-required-param lookup 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 description coverage is 0%, so the schema only conveys the type and a regex pattern, not meaning. The description compensates by defining gene_id as an NCBI Gene ID and indicating where to obtain it, which is more than the schema provides.

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

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

States a specific verb ('Get detailed information') and resource ('a gene') keyed by NCBI Gene ID. It is clearly distinguishable from the search_gene sibling by the 'details vs search' distinction, though it never names that sibling explicitly.

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 parenthetical '(from search results or known)' implies the ID comes from a prior search, which is a useful workflow hint. However, it does not state when to use this over search_gene or get_gene_literature, nor any prerequisites or exclusions.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that it uses NCBI's curated links, which is useful behavioral context, but doesn't disclose rate limits, permissions, or return format details beyond a brief mention.

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: a clear one-sentence purpose, then a rationale, then parameter and return sections. Every part earns its place without unnecessary detail.

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 tool with two parameters and no output schema, the description covers purpose, parameters, and return type adequately. It could mention pagination or handling of large result sets, but given the limit parameter and annotations, it is largely complete.

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

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

Schema description coverage is 0%, so the description must compensate. It documents both parameters: gene_id as NCBI Gene ID and limit as maximum PubMed IDs to return (1-100), matching the schema's constraints. This fully compensates for the lack of schema descriptions, though it doesn't elaborate on format beyond 'NCBI Gene ID'.

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 (PubMed articles linked to a gene), and distinguishes itself from keyword-based search by explaining the source of the links. Sibling tools like search_gene and get_gene_details are clearly different, and get_gene_literature is explicitly about literature linked to a gene ID.

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 retrieving linked articles but does not explicitly state when to use this versus alternatives like unified_search or get_compound_literature. It notes the method is 'more precise than keyword searches', which subtly suggests preference, but lacks clear when-to-use/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 declare readOnly, idempotent, non-destructive, openWorld. The description adds valuable context beyond them: the hard dependency on prior resolver configuration and the fact that the call may return an error message rather than a link, which prepares the agent for a failure mode not captured in 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?

Front-loaded with purpose, then prerequisites, then examples. The heavy ASCII separators add noise, but every substantive section (prerequisite, per-kind examples, args, returns) 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?

With a single parameter, no output schema, and a rich annotation set, the description covers purpose, dependency, all three input shapes, and the return (link or error). 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?

Top-level schema description coverage is 0%, but the description compensates with full worked examples of each discriminated-union variant (pmid, doi, metadata), showing the 'kind' discriminator and field shapes. It also adds guidance ('easiest', 'most reliable') that the schema does not convey.

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 ('Generate institutional access link (OpenURL) for an article') and clarifies the mechanism (library link resolver to full text). An agent can distinguish it from siblings like get_fulltext or test_institutional_access 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 states the prerequisite ('Must first call configure_institutional_access()') and gives concrete usage patterns ranked by reliability ('easiest', 'most reliable'). It does not directly compare against alternatives such as get_fulltext for accessing full text, so it stops short of an explicit when-not-to-use rule.

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 destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the return shape: per-entry date, article count, new/removed articles, and status. It doesn't mention behavior for a nonexistent pipeline name, but that is a minor gap.

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

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

Front-loaded purpose sentence followed by a short diff-analysis clarification, then Args/Returns blocks. The Args section mostly restates schema facts, which is minor redundancy, but nothing is padded or confusing.

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 0% schema description coverage, the description supplies both parameter meaning and return-field detail, giving an agent enough to invoke and interpret the call. Only edge-case behavior (unknown pipeline name) is unaddressed.

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 the description must carry the burden and largely does: it explains 'name' as the saved pipeline's name and 'limit' as the maximum number of history entries with default 5. It omits the name pattern/max-length constraint and the limit's 1-100 range, which the schema does encode, so it is not fully compensating.

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 ('Get execution history for a saved pipeline') and adds the distinguishing detail that it returns diff analysis of new articles versus the previous run. It does not explicitly name how it differs from list_pipelines or load_pipeline, so it falls short of the 5 bar for sibling 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?

There is no guidance on when to call this versus alternatives like list_pipelines, load_pipeline, or read_session. The description describes the content returned but never states a use context, prerequisite (e.g. the pipeline must already exist), or exclusion.

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, so safety and repeatability are covered structurally. The description adds the useful constraint that `source` is exactly one PMID or PMCID (a scope limit not visible in annotations), but says nothing about rate limits, coverage gaps, or behavior for articles without mined terms.

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 scope constraint are front-loaded in the first three lines, and the Args/Returns block is compact and scannable. Some redundancy exists between the prose entity list ('genes, diseases, chemicals, organisms') and the later semantic_type enumeration, costing a little efficiency.

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 spends a line on return shape ('List of text-mined entities with counts and sections'). It is complete enough to call correctly, with the minor gaps of the undocumented output_format parameter and the missing EFO option.

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 the description carries the burden and largely does: it spells out the PMID/PMCID shape and enumerates the semantic_type options. It omits the `output_format` parameter entirely and omits the EFO value present in the schema enum, but the substantive parameters are well documented.

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 ('Get text-mined annotations from Europe PMC') and enumerates the entity types returned, which no sibling tool provides. An agent can distinguish this from get_article_figures, fetch_article_details, or get_fulltext without opening a 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 explains what is returned but gives no when-to-use or when-not-to-use guidance and names no alternative sibling (e.g., get_fulltext for raw text). The agent must infer that this tool is for entity extraction rather than full-text or figure retrieval.

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 the operation as read-only, idempotent, and non-destructive, lowering the burden. The description adds useful behavioral context by describing the returned table fields (name, scope, description, tags) and clarifying that empty filter values show all results. Minor gaps like ordering or pagination are not covered.

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, then uses compact Args and Returns sections. Every sentence adds information without redundancy, and the structure is easy to scan.

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 list tool with rich annotations and no output schema, the description provides sufficient completeness by documenting filter semantics and the return table fields. Minor details like ordering or pagination are omitted but are not critical 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?

Schema description coverage is 0%, so the description must carry parameter meaning. It documents both parameters well: tag with an example and empty behavior, and scope with its enum values and empty behavior. It does not mention the tag maxLength of 100 or the default values, but otherwise compensates thoroughly.

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 (saved pipeline configurations), making the tool's purpose immediately clear. However, it does not explicitly differentiate itself from sibling pipeline tools like load_pipeline or get_pipeline_history.

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 filter behavior (tag and scope) but provides no guidance on when to use this tool versus alternatives such as load_pipeline or get_pipeline_history. No exclusions or 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 establish that this is a read-only, idempotent, non-destructive, closed-world listing tool. The description adds useful context about what the presets are and that the return value includes preset URLs, which matters because there is no output schema.

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

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

The substantive content is short and front-loaded, but the large ASCII banner and emoji add visual noise without conveying additional information. The core sentences earn their place, while the decorative formatting does not.

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

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

For a zero-parameter, read-only listing tool with annotations covering safety and no output schema, the description adequately says what is returned: available presets with URLs. It could be slightly more precise about return structure, but it is complete enough to call 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?

This tool takes zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and it does not introduce any confusion about 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 states a specific verb and resource: 'List available institutional link resolver presets.' It also names the related sibling configure_institutional_access, which helps an agent distinguish listing presets from configuring access.

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 saying presets should be used with configure_institutional_access(preset="name"), but it does not explicitly say when to call this tool versus alternatives or when not to use it. The intended follow-up workflow is clear, but direct invocation guidance is only implied.

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds useful behavioral details beyond those annotations, including the two supported source formats, the restriction on local-only files for authenticated service callers, and the fact that the returned YAML can be passed onward to unified_search or save_pipeline. This gives agents a clearer model of what happens after load.

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 front-loaded with the core purpose, followed by source formats, usage examples, and return behavior. It is slightly longer than strictly necessary because the Args/Returns formatting partially duplicates information already in the schema, but every section adds practical value for correct invocation.

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

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

Given the tool's low complexity (one parameter), the description is nearly complete: it covers source variants, an important auth-related limitation, and the return value. It could arguably mention that list_pipelines can be used to discover valid saved names, but this is not essential for calling 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?

Schema coverage is 0% and the schema only defines 'source' as a string with length constraints. The description fully compensates by explaining the accepted source formats with examples ('saved:weekly_remimazolam' and 'file:path/to/pipeline.yaml') and by clarifying the authentication restriction on file paths. This adds substantial meaning beyond the bare schema.

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

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

The description states a specific verb and resource: 'Load a pipeline configuration for review or editing.' It clearly differentiates the load action from sibling tools like save_pipeline, delete_pipeline, and list_pipelines, and explains the two source types. The purpose is immediately understandable and unambiguous.

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

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

The description gives clear context for when this tool is appropriate: when a pipeline configuration needs to be reviewed, edited, or prepared for execution or saving. It also provides an explicit exclusion: local-only file sources are disabled for authenticated service callers. It does not explicitly name alternatives to avoid, but the workflow notes referencing unified_search and save_pipeline provide strong situational 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 goes well beyond the annotations by disclosing source-specific behavior, format restrictions, and a critical constraint: setting include_abstract=False requires source='local', while official payloads are returned unmodified. It also states the return shape despite the lack of an output schema, providing the agent with essential runtime expectations.

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?

Although long, the description is well-organized with tables, section headings, and examples. Every section adds operational value, and the recommendation for source='official' is front-loaded. The length is justified by the tool's multiple interacting options and format-specific constraints.

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 four parameters, no output schema, and format/source interactions, the description is remarkably complete. It covers input formats, format-by-source compatibility, return value shape, and includes three realistic examples. An agent has enough information to call this tool correctly in varied scenarios.

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 the description carries the full burden. It thoroughly explains the pmids accepted forms ('last', comma-separated, list, 'PMID:' prefix), maps each format to its intended use, and clarifies source semantics. This adds substantial 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 opens with a specific verb and resource: 'Export citations to reference manager formats.' It clearly differentiates this tool from sibling search, retrieval, and analysis tools by listing concrete output formats such as RIS, BibTeX, and CSL, making its purpose 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?

The 'When to Use' section explicitly names real-world scenarios like exporting to EndNote, Zotero, Mendeley, and generating BibTeX for LaTeX. It does not name alternatives to avoid, but the context is clear enough that an agent can infer when this tool is appropriate.

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 context about the tool's behavior (e.g., returns ImageContent, requires English terms, limitations like 'Experimental'), but it doesn't fully disclose edge cases or failure modes. The annotation readOnlyHint=true is consistent with the description, and the description adds some behavioral details 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 quite long and contains redundant explanations (e.g., repeating the workflow in different sections). It's structured with headings and examples, but it could be more concise. However, the structure helps readability, and the length is somewhat justified by the 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?

The description covers the tool's purpose, usage, examples, and search types, providing a fairly complete picture for an agent. It lacks some details like error handling or specific return format details, but overall it's comprehensive enough for basic 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 explains the 'source' parameter with examples and mentions 'context' and 'search_type' implicitly through the search types section. However, schema coverage is 0%, so the description carries more weight, but it doesn't fully explain all parameter nuances, especially 'context'.

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

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

The description clearly states the tool's purpose: it prepares a figure or image for literature search by returning the image for analysis. It includes specific action verbs and explains the workflow, which helps distinguish it from siblings like 'search_biomedical_images' or 'unified_search'.

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 detailed usage instructions, including step-by-step workflow, examples, and search types. It explicitly mentions the tool returns the image and that the host agent performs the analysis, but it doesn't explicitly differentiate when to use this tool versus alternatives like 'search_biomedical_images'.

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 readOnly/idempotent/non-destructive, and the description adds genuine behavior beyond them: session-persistent evidence, instant analysis without re-search, and the important diff caveat that absence does not prove retirement. It also discloses that output is Markdown or JSON depending on action and format.

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 action inventory, then tightly scoped bullets per action, then the request-shape note and worked examples. Every section earns its place; the examples are justified by the discriminated-union request shape.

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 by stating the return type (Markdown or JSON, action/format dependent) and describing what each action yields. All six actions are individually explained, so 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 reported as 0%, but the schema itself is highly self-documenting via consts, enums and discriminators. The description still adds meaning: `load` defaults to the latest revision, `diff`/`narrate` accept revisions, `compare` takes exactly 2-5 topics or Chronicle IDs, and enumerates valid `output` formats earlier than the enum list.

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 and resource ("Read stored Research Chronicles") and enumerates the six actions it fronts. It explicitly frames itself as the read facade over `build_research_chronicle`, so an agent can separate it from the sibling write tool without inspecting 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?

Clear context for when this tool is the right choice: chronicles persist across sessions and analysis/comparison are instant because no search is re-run. It does not name an explicit when-not-use case or point to competing read tools, but the purpose-driven context is strong.

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=false, and openWorldHint=false, so the safety profile is covered. The description adds non-obvious behavior the annotations do not: each action accepts only its own fields, local paths are redacted unless include_local_paths is set AND the server setting permits, and large artifacts require locator plus artifact_file with offset/max_chars paging.

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 one-line purpose, then a scannable action list, then a short paragraph of cross-cutting behavior; nearly every sentence carries information. The only waste is the omission of 'log' rather than an excess of text — nothing present 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?

With no output schema, the description correctly compensates by describing each action's return payload (PMIDs, cached article, summary plus optional history, artifact manifests, run envelopes, credential-free replay args). The main completeness gap is the unlisted 'log' action and the absence of any note on error/not-found or missing-session 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?

Schema description coverage is 0%, but the schema is unusually self-documenting (patterns, enums, discriminator mapping, defaults), so the burden is light. The description still adds meaning beyond the schema by explaining the two locator kinds, the artifact_file/offset/max_chars paging contract, and the dual gating on include_local_paths, though it does not explain defaults such as search_index=-1 or session_id=null.

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 ('Read session data') and then enumerates eight actions with their return payloads, so an agent can tell this apart from read_research_chronicle, fetch_article_details, and unified_search. The enumeration is incomplete, however: the schema defines nine discriminated requests but the 'log' action is omitted from the list, so an agent reading only the description would not know that action 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?

It gives real conditional guidance for the artifact path ('select an artifact_id or artifact_uri locator and use artifact_file plus offset/max_chars to page through large files') and warns that local paths are redacted unless two conditions are met. However, it never says when to choose read_session over its many siblings, nor does it state when an action is inappropriate; per-action field exclusivity is noted but not framed as selection 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 declare destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description meaningfully extends this: it discloses the environment-variable resolution order, the tenant-isolation rule for authenticated callers (output_dir/template_file ignored), and that host paths are never leaked. That is context beyond what the 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?

Front-loaded with the directive and well-sectioned under When to Use / Directory Resolution / Service Boundary / Args / Returns / Examples. The Args list is long but each entry earns its place; only minor trimming is possible.

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 9 parameters, no output schema, and zero schema coverage, this description still supplies the write semantics, directory resolution, auth-boundary caveat, and an explicit Returns description including the wiki_validation output. 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 0%, so the description carries the full burden for 9 params, and it does: pmids accepts 'last'/a string/JSON array, note_format's four values are explained, template_file placeholders are named, and include_csl_json's purpose (citation-manager handoff) is stated. Every parameter gets meaning the bare schema lacks.

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 ('Save searched articles as ... wiki/Foam/Markdown notes') and immediately positions itself against siblings by calling out unified_search as the upstream and framing itself as 'a structured alternative to generic write_file calls'. An agent can identify the tool's role without reading 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?

Includes an explicit 'When to Use' section that sequences it after unified_search and names the alternatives it replaces. The Local Directory Resolution ordering and the Authenticated Service Boundary section add conditional guidance that decides how the tool behaves in different deployment contexts.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds genuinely useful behavior beyond that: upsert/overwrite semantics on name collision, the three-way scope meaning (workspace = git-trackable, global = cross-project, auto = fallback), and a return summary. One tension is worth noting: 'upsert semantics' implies repeated identical calls converge, while idempotentHint=false, and the description does not resolve this.

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 purpose and format, then Args and Returns blocks that are easy to scan. The name constraint partially restates the schema's pattern/maxLength, a small redundancy, but otherwise every line carries 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 5-parameter mutation tool with no output schema and empty schema descriptions, the definition covers all parameters, the config format, storage-scope semantics, overwrite behavior, and the retrieval path. 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 0%, so the description must carry parameter meaning, and it does: scope is spelled out with each enum's storage implication and default, tags are described as bounded canonical tags with an example, config is tied to the unified_search pipeline format, and name's uniqueness/overwrite behavior is stated. This fully compensates for the empty 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?

States a specific verb (save) and resource (pipeline configuration) plus the reuse intent. It is clearly distinguishable from siblings like list_pipelines, load_pipeline, delete_pipeline, and schedule_pipeline 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?

Explains the practical workflow: config format matches unified_search's pipeline param, and saved pipelines are retrieved via unified_search(pipeline="saved:name"), which tells the agent what this tool pairs with. It stops short of explicit when-not guidance or prerequisites (e.g., overwrite risk is mentioned but not framed as a caution).

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, covering the mutation and external-effect profile. The description adds the cron-field requirement and clarifies that diff_mode/notify are 'stored preferences' rather than immediate actions, but doesn't disclose reversibility, auth needs, or rate limits.

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 Args/Returns sections and front-loaded purpose statement. The Returns section is somewhat filler since there's no output schema, but overall efficient and easy to scan.

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 four parameters at 0% schema coverage and no output schema, the description supplies the missing parameter semantics thoroughly. The main gap is lack of when-to-use guidance versus sibling pipeline tools.

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 the description carries the load. It documents all four parameters with meaning beyond the schema (cron field count and a concrete example, name = saved pipeline name, and the storage semantics of the two booleans). This compensates well for the undocumented 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 (schedule) and resource (saved pipeline for periodic execution). The sibling unschedule_pipeline is the clear inverse, and this description correctly claims the scheduling side without conflating them.

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

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

Implies usage (scheduling periodic execution) but never states when to use this versus save_pipeline or load_pipeline, nor any prerequisites like the pipeline already needing to exist. No exclusions or alternatives 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the critical language requirement (Open-i only supports English), the built-in translation hints, and the fact that it returns formatted results with URLs and metadata. It doesn't 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 long but well-structured with clear sections (CRITICAL, SOURCES, EXAMPLES, Args). The critical language requirement is front-loaded. The parameter documentation is repetitive with the schema enums, but the added explanations (e.g., 'x': X-ray images, 'mc': Microscopy) justify the length. Some decorative elements (box-drawing characters) add noise but don't harm readability.

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 12-parameter tool with no output schema, the description is remarkably complete. It covers the source, the language constraint, all parameter semantics, example calls, and the return format. The only minor gap is that it doesn't describe pagination or error behavior, but the examples and parameter docs are sufficient for an agent to call this 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?

Schema description coverage is 0%, so the description carries the full burden of explaining parameters. It does this thoroughly: every parameter (query, image_type, collection, limit, sort_by, article_type, specialty, license_type, subset, search_fields, video_only, hmp_type) is explained with its enum values and meaning. The examples show realistic usage patterns for each filter.

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 searches biomedical images from NLM Open-i and returns image URLs with metadata. It distinguishes itself from siblings like search_clinvar, get_article_figures, and unified_search by specifying the Open-i source and the exact output (image URLs with captions, article info, MeSH terms).

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 extensive usage guidance: when to use it (searching biomedical images), explicit language requirements (translate non-English queries to English), and examples for various filter combinations. It also implicitly distinguishes from siblings by focusing on Open-i image search rather than article retrieval or gene/compound search.

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, and non-destructive, so safety is covered. The description adds the return shape ('JSON with variant records including significance and conditions'), which is useful since there is no output schema, but it discloses no rate limits, pagination, or scoping 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 first line is well front-loaded, but the box-drawing banner section for USE CASES consumes vertical space without adding semantic content. The Args/Returns structure is efficient, but overall it is bulkier than needed.

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 2-parameter read tool with no output schema, the description covers purpose, accepted query forms, the limit bound, and the return content. It lacks pagination/ordering notes, but nothing critical to calling 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 0%, so the description must carry the load. It documents 'query' as accepting a gene name, variant, or disease condition (a real semantic addition the schema omits) and clarifies 'limit' as maximum results, compensating well for the coverage 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?

States a specific verb+resource: 'Search ClinVar for clinical variants.' The ClinVar domain distinguishes it from the many literature/gene/compound siblings, though it doesn't explicitly say how it differs from search_gene or search_compound.

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 USE CASES block gives four concrete scenarios (clinical significance lookup, disease-associated variants, gene-disease associations, pathogenicity classification), which is clear context for when to reach for it. It offers no explicit exclusions or named sibling alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds that results come back as 'JSON with compound records including names, formulas, properties' — useful since there is no output schema — but says nothing about rate limits or how PubChem misses are handled despite openWorldHint.

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 opening sentence is correctly front-loaded and the content is short, but the boxed '═══' dividers and USE CASES/Args/Returns scaffolding consume lines without adding information — decoration rather than earned structure.

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 two-parameter read-only search with no output schema, the description is adequate: it names the source, the use cases, the args, and the rough return shape. It stops short of explaining pagination, ranking, or the distinction from compound-detail siblings, leaving gaps for a tool with several close relatives.

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 the description carries the load: it labels query as 'Compound name or description' and limit as 'Maximum results (1-50)'. That compensates for both parameters, but shallowly — no format hints, examples, or handling of ambiguous 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?

States a specific verb+resource+source: 'Search PubChem for chemical compounds.' An agent immediately knows this queries PubChem. However, it does not distinguish itself from siblings get_compound_details and get_compound_literature, which are the obvious adjacent tools for compound lookups.

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 USE CASES list implies when to reach for this tool (compound info, formulas, synonyms, properties), which is more than nothing. But it gives no when-NOT guidance and never mentions the alternatives (get_compound_details for a known compound, get_compound_literature for papers), so an agent must infer the routing itself.

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, openWorldHint and non-destructive, so the safety profile is covered. Beyond that the description only adds the return shape; it says nothing about rate limits, result ordering, or relevance ranking for what is an open-world search.

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 one-line purpose, then scannable sections. The decorative separator lines and USE CASES header add formatting overhead but the content is tight and each bullet 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?

No output schema exists, so the description appropriately summarizes the return (JSON with symbols, names, locations). All three parameters are covered and the use cases frame intent — a complete-enough definition for a simple three-param search.

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 the description must compensate, and it does: it labels all three parameters and adds concrete value — organism examples ('human', 'Homo sapiens', 'mouse') and the limit range (1-50). Minor gap: it doesn't explain query matching mode (symbol vs. free-text function).

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: search the NCBI Gene database for gene information. Sibling tools like get_gene_details and get_gene_literature exist, but the description never differentiates this lookup from them, so the agent must infer the split (search vs. fetch-details).

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 USE CASES block gives clear situational context (look up function, aliases, chromosome location, find by name/function), which tells an agent when this tool applies. It stops short of naming an alternative or exclusion, so it's solid context without 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 cover readOnly/idempotent/openWorld, but the description adds meaningful behavioral context: it clarifies that the test only verifies endpoint reachability, not full-text access, which is a critical limitation not expressed in annotations. Also documents the default pmid and expected return 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?

Heavily over-styled with ASCII dividers and duplicated headers (title repeats the name, banner box, repeated 'FREE TEST OPTIONS'). The core signal is buried under decorative formatting, wasting many tokens for a one-parameter 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?

Covers purpose, limitation note, test options, argument default, and return shape. For a simple read-only test tool this is largely sufficient, with minor room to be tighter.

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% and the single pmid parameter has no description in the schema; the description explains pmid is the PMID to use for testing with a default (38353755), adding needed meaning. Baseline for 1 param with low coverage is 3, and the added detail matches that.

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 (test) and resource (institutional link resolver configuration), and enumerates exactly what is being checked: configured, reachable, valid response. Clearly distinguishable from siblings like configure_institutional_access and diagnose_institutional_access.

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 clear when-to-use context via the FREE TEST OPTIONS section explaining how to test without institutional access, and notes what the test does and does not verify. Slightly fewer explicit exclusions vs alternatives, but functional.

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 substantial behavioral detail beyond the annotations: automatic source selection, auto-relaxation on zero results, shallow vs. deep search, deduplication, ICD/MeSH expansion, Unpaywall enrichment, source alias rejection, global env-based source disabling, and pipeline dry_run/stop_at semantics. This is far richer than the sparse 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?

The description is well-structured with headers, a 'WHAT IT DOES' list, examples, and per-parameter explanations, and it is front-loaded with the core purpose. However, it is very long and contains redundancy, especially in the options section where the 'exact canonical spelling' warning appears twice and one sentence is grammatically broken ('and automatically disable multi-strategy query expansion').

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 10-parameter tool with no output schema, the description is exceptionally complete: it covers return content, source availability, environment-based configuration, pipeline actions, templates, debugging controls, and edge-case behaviors such as auto-relaxation and preprint detection. An agent has enough information to call the tool correctly across simple and complex scenarios.

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 the description carries the full burden, and it succeeds. Every parameter (query, limit, sources, ranking, output_format, filters, options, pipeline, dry_run, stop_at) is explained with defaults, valid values, examples, and behavioral effects, including canonical token spelling requirements and mutually exclusive options.

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 is a 'Single entry point for multi-source academic search' that analyzes queries and searches multiple sources, with a concrete list of behaviors (deduplicates, merges, ranks, enriches with OA links, detects ICD codes). It does not explicitly name sibling tools or state how it differs from them, so it stops short of full sibling 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?

The description gives clear context for when to use the tool: it is the unified search entry point, and users do not need to choose between PubMed, OpenAlex, CrossRef, etc. Numerous examples show when to use basic, filtered, preprint, systematic, and pipeline modes, but it does not explicitly state when to prefer sibling tools like fetch_article_details or analyze_search_query.