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

Beyond the readOnlyHint annotation, the description discloses critical failure behavior: it does not raise on upstream/HTTP failure, returns a plain string beginning with 'Error:' instead of JSON, and warns the caller to check for that prefix. This is high-value behavioral context not present in 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 only a few sentences and each one earns its place: the action, the return format, and the error-handling caveat. It is front-loaded and avoids filler.

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

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

For a simple one-parameter read-only tool, the description covers the core purpose, return format, and failure mode with high clarity. The presence of an output schema means return-value details do not need to be restated, and the tool's context is adequately complete.

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

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

The single parameter is fully documented in the input schema, including an example CID ('445154'). The description does not need to add parameter details, so the baseline score of 3 is appropriate because the schema already carries the meaning.

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

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

The description clearly identifies the verb ('Get') and the resource ('compound attributes from PubChem RDF'), which distinguishes it from sibling tools like get_pubchem_compound_id. The scope is specific and immediately understandable.

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 retrieving PubChem compound attributes, but it does not explicitly state when to choose this tool over alternatives or mention any exclusions. No direct comparison with siblings such as get_pubchem_compound_id is 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?

Beyond the annotations (readOnlyHint and openWorldHint), the description details specific behaviors: internal graphs are filtered out, graph URIs containing the database substring are ranked first, and it returns a CSV list. It also discloses the error response prefix, adding transparency about output format and failure modes.

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, then proceeds to usage constraints, ranking behavior, fallback logic, and return format. Each sentence adds value without redundancy. Though a bit long, the density of relevant information justifies its length.

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

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

For a tool with 4 parameters and a complex registry logic, the description covers all necessary context: required input, alternative inputs, ranking behavior, internal graph filtering, and error handling. The presence of an output schema is complemented by the description's explanation of CSV format and 'Error:' prefix, making the tool fully understandable.

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

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

The schema descriptions already cover all parameters (100% coverage), but the description adds semantic depth: it explains the dual role of database (validation vs ranking), priority between endpoint_url and endpoint_name, and how include_system affects output. This goes beyond simple schema documentation and helps agents use parameters correctly.

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: 'Get a list of named graphs on a SPARQL endpoint.' It specifies the action (list), the resource (named graphs), and the context (SPARQL endpoint). It also distinguishes from siblings by highlighting endpoint discovery and filtering/ranking behavior, which is unique among the provided tools.

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

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

The description provides explicit usage guidance: 'ALWAYS pass database (required)' and explains when to use endpoint_url vs endpoint_name for unregistered databases, and how database value is used for ranking. It also warns about the 'Error:' prefix in return values, covering both usage conditions and error expectations.

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 signal read-only and open-world behavior, so the bar for additional disclosure is lower. The description adds concrete behavioral details: it returns a YAML-formatted string and an unknown database returns an error string listing valid database names. This goes beyond the annotations without contradicting them.

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 most important usage instruction in bold, followed by a concise definition and return behavior. Every sentence contributes meaningful information, and there is no redundant repetition of schema details.

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

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

Given the output schema and fully documented parameters, the description provides the remaining context needed: when to call it, what it returns, and how errors are surfaced. It is complete for an agent selecting and invoking 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 100%, with each parameter fully documented including db/dbname as aliases and a detailed list of valid database values. The description adds no per-parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool gets the MIE file for a specific RDF database, including its ShEx schema, RDF, and SPARQL examples. This specific verb-resource pairing and the explicit prerequisite to run before SPARQL queries distinguishes it from sibling tools like run_sparql.

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

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

The description provides explicit workflow guidance: identify all databases needed and call this tool for each before writing any SPARQL queries. It also states when not to proceed ('Do not query a database until its MIE file has been read'), giving clear usage context.

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

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

Beyond readOnlyHint and openWorldHint annotations, description discloses key error behavior: returns plain string with 'Error:' prefix (not JSON) on upstream/HTTP failure, and instructs to check for prefix before parsing. This is critical operational context not 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?

Description is compact and front-loaded: first sentence states the action, then critical error-handling details. Every sentence earns its place with no filler.

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

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

For a single-parameter lookup tool with strong annotations and output schema, the description covers purpose, error behavior, and return format. It is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% and the only parameter compound_name is already described with example. Description adds minimal extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

Description explicitly states it retrieves a PubChem compound ID (CID) for a compound name, with a clear verb+resource combination. It distinguishes from siblings like get_compound_attributes_from_pubchem by focusing on ID retrieval specifically.

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

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

Description implies usage for looking up compound IDs by name and distinguishes via example. However, it does not explicitly state when to prefer this over related PubChem tools or exclude 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 communicate that this is a read-only, open-world operation, which covers the main safety profile. The description adds the RDF Portal scope and return-key vocabulary but does not disclose additional behavioral details like authorization requirements, rate limits, or failure modes; this is adequate but not rich.

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 concise and front-loaded, but the description repeats the same return information twice: once in prose ('RETURNS a dict with two keys...') and once in a 'Returns:' block. This redundancy prevents every sentence from earning its place.

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

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

For a zero-parameter, read-only discovery tool with readOnlyHint and openWorldHint annotations plus an output schema, the description provides sufficient context. It covers the purpose, the resource scope, and the expected return structure, leaving no material gaps.

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

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

The tool has zero parameters and the schema coverage is complete, so there is no parameter ambiguity for the description to resolve. Per the baseline rule for tools with no parameters, a score of 4 is appropriate.

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

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

The description uses a specific verb ('Get') and a specific resource ('available SPARQL endpoints for RDF Portal'), making the tool's function immediately clear. It also distinguishes this tool from sibling tools like 'run_sparql' by focusing on endpoint discovery rather than query execution.

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

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

No when-to-use guidance or alternative-recommendation is provided. The description only restates the action and return structure, so the agent must infer that this tool is meant for discovering endpoints before running SPARQL queries.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds that it returns actual data (sequences, records), which is useful but vague. It does not disclose pagination, rate limits, or format specifics, which are partially covered by schema parameters. No contradiction with annotations.

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

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

Two short, front-loaded sentences: 'Fetch full records using efetch. Returns actual data (sequences, records, etc.)'. Every word earns its place, and the description is concise 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?

The tool is relatively simple with full schema coverage and read-only annotations, but there is no output schema, so the description bears some burden to explain return values. It only vaguely says 'actual data (sequences, records, etc.)' and doesn't address retmode/rettype interplay or how IDs are accepted (though schema covers this). It is adequate but not rich.

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

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

Schema description coverage is 100%, so parameters are already documented (db/database, ids, retmode, rettype). The description adds no additional parameter-level meaning, which aligns with the baseline of 3 when the schema covers all parameters.

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 'Fetch full records using efetch' with a specific verb and resource, and clarifies 'Returns actual data (sequences, records, etc.)'. It distinguishes from sibling tools like ncbi_esearch (search) and ncbi_esummary (summary) by emphasizing full record retrieval, though it could be more specific about which databases are supported.

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

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

Usage is implied: the description suggests this tool is for fetching full records when actual data is needed, as opposed to summaries or search. However, it does not explicitly state when to use it over alternatives like ncbi_esummary or provide exclusion criteria, leaving the agent to infer from the name and sibling tools.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses important runtime behavior: it returns formatted text with database-specific IDs, and it returns an error-prefixed text item on invalid database or query. It also warns about 70-80% recall loss without field tags, providing valuable behavioral context.

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

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

The description is long and uses bolded warnings, emojis, and repeated emphasis on field tags, but it is well organized with clear sections and examples. The verbosity is justified by the critical impact of field tags on result quality, though some repetition could be trimmed.

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 search tool with no output schema, the description covers the critical operational details: query format, field tag requirements, error behavior, and pagination parameters in schema. It does not mention NCBI rate limits or explain how the returned IDs are delimited, but the provided guidance is sufficient for successful invocation.

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

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

The input schema already documents all eight parameters, so baseline is 3. The description adds meaningful query-construction semantics, including field tag syntax, boolean operations, and worked examples for the `query` and `database` parameters, going beyond the schema's brief 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 a specific action and resource: 'Search NCBI databases using E-utilities esearch API.' It clearly states the tool returns database-specific IDs, which distinguishes it from sibling tools like ncbi_esummary and ncbi_efetch.

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 strong, explicit guidance on how to construct queries, especially mandatory field tags for Gene and ClinVar, with concrete examples and performance consequences. It does not explicitly contrast this tool with sibling retrieval tools, but the context for when to search for IDs is clear.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses the return shape ('a text item holding parsed JSON summary data') and the failure mode for invalid database or empty IDs, including the 'Error:' prefix. This is useful operational guidance, though it does not cover all possible API behaviors.

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 and front-loaded with the primary purpose, then adds a return/error note. Every sentence contributes useful information, and the RETURNS/Error sections are well structured.

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

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

For a relatively simple 3-parameter wrapper with no output schema, the description gives purpose, relationship to esearch, return format, and error handling. It could be more complete by briefly contrasting with ncbi_efetch or describing the summary fields, but the provided context is sufficient for basic correct use.

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

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

Schema description coverage is 100%, and the descriptions in the schema already explain database/db alias and the accepted ids formats. The tool description only references database/ids in the error conditions, adding little semantic value beyond the schema.

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

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

The description opens with a specific verb+resource: 'Fetch summary information for given IDs using esummary.' It clearly conveys the tool's function and positions it as a follow-up to esearch, but it does not explicitly contrast it with sibling retrieval tools like ncbi_efetch.

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?

'Useful for getting detailed info after esearch' gives contextual placement but no explicit when-to-use vs alternatives or when-not-to-use. It implies usage after esearch but doesn't name competing tools such as ncbi_efetch or list_databases.

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 annotations already declare readOnlyHint: true and openWorldHint: true, so the description doesn't need to restate that it's safe. However, the description adds only that it 'Returns a formatted list' with descriptions and example queries, which is content detail rather than behavioral context. It doesn't disclose any additional traits such as pagination, ordering, or rate limits, so it stays at baseline value.

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

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

The description is two concise sentences—one for purpose and one for return value—with no irrelevant details. The action is clear and the format of the response is front-loaded. Only essential information is included, meeting the highest standard.

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

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

Given the tool has no parameters and no output schema, the description adequately covers its full behavior: it lists databases with descriptions and example queries, and it specifies that the result is a formatted list. A small gap is the lack of context on how this tool integrates as a prerequisite for other NCBI tools, but it is not necessary for basic use.

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

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

The tool has zero parameters, and the schema coverage is 100% (vacuously). Per the rubric, zero parameters warrant a baseline of 4, and the description adds no parameter info since there is nothing to describe. This is appropriate and no points are lost.

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 ('List') and resource ('all supported NCBI databases') with the added detail of including descriptions and example queries. This distinguishes it from sibling tools like ncbi_esearch or ncbi_efetch, which search or fetch data, making the purpose 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 implies this is a discovery tool (to see which databases are available), but it does not explicitly state when to use it versus the other NCBI tools or mention any exclusions/alternatives. This is a clear gap for a tool that would logically be used as a preliminary step before querying specific databases.

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

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

With annotations already declaring readOnlyHint and openWorldHint, the description adds valuable behavioral context: invalid database/endpoint_name values fail immediately with a deterministic error and should not be retried, and results are returned as a CSV string with a header row. This goes beyond the annotations and helps set 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?

The description is dense and front-loaded with the core action, and every sentence carries critical information. It is longer than ideal due to the extensive enum lists, but those are necessary. The structure is logical, moving from basic usage to cross-database nuances to error and return behavior.

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

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

Given the tool's complexity (5 params, multiple endpoint options, cross-database scenarios, output schema), the description is thorough. It covers required parameters, valid values, endpoint priority, error behavior, and return format. The output schema exists, but the description additionally explains the CSV structure, making it fully self-contained.

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

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

Although schema coverage is 100%, the description significantly enriches parameter understanding: it lists all valid database values, explains that endpoint_url takes priority over database, and clarifies alias relationships (query vs. sparql_query). This is not merely restating schema; it provides essential operational semantics for correct usage.

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

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

The description clearly states the tool's function: 'Run a SPARQL query on an RDF database.' It uses a specific verb and resource, and the detailed guidance on single vs. cross-database queries distinguishes it from sibling search tools. However, it does not explicitly compare itself to alternatives like search_uniprot_entity, so it does not fully earn a 5.

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

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

The description provides explicit when-to-use instructions: ALWAYS pass database for single-database queries, and still pass a member database plus endpoint_name or endpoint_url for cross-database queries. It also clarifies priority and error behavior. Yet it does not mention alternatives (e.g., using search_* tools for standard queries), leaving the vs. alternatives aspect partially unaddressed.

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

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

Goes far beyond the readOnlyHint and openWorldHint annotations. It explains matching regimes (EXACT vs KEYWORD), pagination behavior (has_more semantics), empty-result hint, and error handling (returns error key instead of raising). It clarifies that total_count is capped by limit, and warns against misinterpreting truncated results. This is exemplary behavioral disclosure.

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

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

Although lengthy, the description is well-organized with bullet points, clear sections for matching regimes, return structure, and warnings. It front-loads the core purpose and then systematically adds details. Every sentence carries useful information; no filler. The structure aids readability for a complex tool.

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

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

Given the tool's complexity (9 params, multiple entity types, intricate matching semantics, detailed return structure), the description is remarkably complete. It covers all necessary aspects: input handling, behavior differences per entity type, pagination nuances, empty results, error handling, and return dict structure. The presence of an output schema doesn't reduce the value of the description's explanations.

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

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

Schema coverage is only 33%, but the description compensates extensively. It documents the multiple aliases for the query parameter (query, search, term, keyword, keywords, search_term, name) and explains the entity_type values and their matching semantics. It also clarifies the limit's effect on cross-kind results. The description provides far more parameter context than the schema alone.

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

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

The description clearly states the tool's purpose: 'Resolve a name to ChEMBL IDs across several entity kinds in one call.' It explicitly distinguishes itself as a cross-entity convenience wrapper over the ChEMBL RDF graph, and contrasts with siblings like search_chembl_target (substring fallback) and search_chembl_molecule. The verb+resource+scope are specific and unambiguous.

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

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

Provides explicit guidance: when to use entity-specific tools (if you know the kind), when to use search_chembl_target (for fuzzy/substring matching), and when to use this tool (unsure of kind, want cross-kind search). It also details the ASSAY opt-in rationale and warns about implications of the has_more flag on truncated pages. Usage boundaries and alternatives are clearly 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?

Beyond annotations readOnlyHint=true and openWorldHint=true, the description thoroughly discloses matching semantics (deterministic exact vs. SMILES flexmatch), case sensitivity, conservative structure detection, and non-raising error behavior returning an 'error' key. It also explains the extract mode's heuristic nature and 'match_type' checking. This goes far beyond what annotations provide and contains no contradictions.

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

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

The description is long but dense and well-organized with bullet points, clear sections, and front-loaded purpose. Every major behavioral nuance (exact vs extract, error handling, return keys) earns its place, though a few points (e.g., the full list of alias parameters) are repeated. Slightly verbose for the tool's complexity but justified.

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

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

Despite the output schema existing, the description adds critical operational context: return dict keys, total_count meaning, has_more semantics, matched_span/match_type under extract, the 'note' key for empty results, and the 'error' key on HTTP failure. It also addresses edge cases like bare-chain SMILES. The tool is complex, and the description covers all necessary decision paths.

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 only 33%, but the description compensates fully. It clarifies that any of seven alias parameters can carry the search string, explains mode='exact' vs 'extract' in detail with examples, and interprets the return shape tied to limit. It adds significant semantic 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 clear verb+resource statement: 'Resolve a DRUG / COMPOUND / MOLECULE (by name or structure) to a ChEMBL ID.' It immediately distinguishes itself from sibling search_chembl_target by explicitly redirecting biological target queries. The scope is precise and matches the tool name.

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

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

The description provides explicit when-to-use guidance: use for drug/compound/molecule names, and for targets use search_chembl_target instead. It also details when to use mode='extract' as a retry for strings that name drugs rather than being drugs, and warns against using it as the first call. This is exemplary usage 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 readOnlyHint and openWorldHint, but the description adds substantial behavioral detail beyond them: deterministic SPARQL with no ranking, exact versus substring match modes, unrecognized target_type raising, empty results carrying a hint, and endpoint failures returning an 'error' dict without raising. No contradiction with annotations exists.

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 highly structured: a clear purpose line, warning callout, bulleted resolution rules, filter guidance, return dict explanation, and failure-mode instructions. Every section adds necessary operational context, and the most critical caveats are front-loaded.

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

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

Given the tool's complexity—10 parameters, multiple search-string aliases, fallback matching, result disambiguation, and non-raising failure modes—the description is exceptionally complete. It explains return structure, match_mode semantics, empty-result hints, and error checking, leaving little ambiguity for an agent.

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

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

Schema coverage is only 40%, so the description must compensate, and it does thoroughly. It defines the canonical `query` parameter (UniProt accession, gene symbol, or exact protein name), lists all accepted alias parameters, explains `target_type` accepted values, and clarifies `limit` affects returned rows. This goes well beyond the sparse input 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: 'Resolve a biological TARGET (protein/receptor/enzyme) to a ChEMBL ID.' It further distinguishes itself from siblings by explicitly warning not to use it for drugs/compounds and directing users to `search_chembl_molecule` instead.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'DO NOT use this tool to look up drugs, compounds, or molecules by name... use search_chembl_molecule instead.' It also explains deterministic matching behavior, fallback substring mode, result disambiguation, and filtering via organism/target_type.

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 critical behavior: returns JSON-formatted string, on failure does NOT raise but returns a plain string starting with 'Error:' and instructs to check before parsing. This adds value beyond the readOnlyHint and openWorldHint annotations, which do not cover error handling or return 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?

The description is two sentences, front-loaded with the purpose and followed by a crucial error-handling note. Every sentence earns its place with no filler.

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

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

The tool has 8 parameters with many undocumented aliases, and the description does not explain how to construct a query or which parameter takes precedence. While the error handling and return type are covered, the overall parameter semantics remain incomplete, making it hard for an agent to use correctly without additional inference.

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 only references 'query' generically, while the schema has 8 parameters with only 25% coverage. It does not explain the relationship between the many alias parameters (name, term, search, keyword, etc.) or how they should be used, failing to compensate for the low schema coverage.

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

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

The description clearly states 'Search for MeSH ID by query', specifying the verb, resource, and input. This distinguishes it from sibling entity search tools like search_uniprot_entity or search_pdb_entity by targeting MeSH specifically.

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

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

The description provides clear context that this tool is for MeSH ID lookup, making the primary use case obvious. It does not explicitly mention alternatives or exclusions, but the MeSH-specific purpose gives sufficient guidance for when to use it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds meaningful context: it explains the return format (rich named fields), clarifies that a null total does not mean zero results, and warns about error key checking. This goes beyond the annotations and is valuable for safe invocation.

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

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

The description is concise, well-structured, and front-loaded with the purpose. It uses clear formatting (capitalized key sections) and highlights critical caveats like total null and error handling in a readable way, with no wasted words.

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

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

Given the tool's complexity (17 parameters) and low schema coverage, the description lacks essential parameter guidance. While it thoroughly explains the return format (aided by the output schema), it does not explain how to use most search filters or constraints, making correct invocation difficult for an agent.

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

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

Schema description coverage is only 24% (4 of 17 parameters have descriptions). The tool description does not compensate; it only briefly mentions the 'db' parameter and focuses on output format. Many parameters like 'name', 'ligand', 'res_min', 'res_max', 'source' remain undocumented, leaving users to guess their meaning and usage.

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

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

The description clearly states it searches PDBj for structures, chemical components, or BIRD molecules, using specific verbs ('Search') and resource types ('PDBj', 'structures', 'chemical components', 'BIRD molecules'). This distinguishes it from sibling tools like search_uniprot_entity or search_reactome_entity, which target other databases.

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

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

The description implicitly indicates usage for PDBj-specific searches, but does not explicitly state when to use this tool versus alternatives or provide exclusions. It does mention the supported database types, which gives context, but lacks a direct 'use when' statement.

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?

Even though annotations already mark readOnlyHint and openWorldHint, the description adds substantial behavioral detail: the exact return dict shape, 'has_more' semantics, error dict on upstream failure, include_summation payload tradeoff, and server-side case-sensitivity normalization. No annotation contradiction exists.

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 longer than typical but every sentence carries meaningful operational guidance, with clear warnings and structured paragraphs. It is front-loaded with the core purpose and avoids filler, though a few details repeat schema descriptions.

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 fuzzy search tool with an output schema and read-only annotations, the description covers the return contract, error handling, filter normalization, and payload optimization. An agent has enough information to invoke it correctly and interpret results without significant gaps.

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

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

Schema description coverage is 50%, so the description must compensate, and it does by clarifying limit as a total cap, return format, and the species/types validation-to-casing behavior. Some parameters (name, term, search, keyword) remain undocumented outside the schema's query alias note, so it stops short of a 5.

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

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

The description opens with 'Search the Reactome pathway knowledgebase by keyword (name / fuzzy match)' and explicitly says it resolves terms to Reactome stable IDs. This is a specific verb+resource with clear scope, and it distinguishes itself from the exact-match ChEMBL search tools.

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

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

It provides direct usage context by contrasting keyword/fuzzy matching with the exact-match ChEMBL search tools, telling the agent when approximate ranked hits are expected. It also warns about case-sensitivity and error-checking behavior, which supports correct selection and invocation.

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 readOnlyHint and openWorldHint annotations, the description discloses critical runtime behavior: non-exact fuzzy matching, field-scoped syntax and wildcards, the ChEBI prefix 500-error trap and auto-correction, return dict shape with total_count/has_more, the 500-result cap, snake_casing of output keys, and the possibility of an {'error': ...} response. No contradiction with annotations exists.

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 longer than average, the description is densely informative and well-structured: opening purpose, matching semantics, return contract, error handling, and columns. Every section adds operational value, and critical caveats such as the ChEBI prefix 500 and the need to check for 'error' are emphasized without padding.

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 9 parameters, fuzzy query syntax, return-shape nuances, error cases, column enumeration, and limit bounds, the description is complete enough for an agent to select and invoke it correctly. The output schema exists, and the description still goes beyond it by explaining how to interpret total_count, has_more, snake_cased keys, and failure responses.

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

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

Schema coverage is only 33% because several alias parameters have no prose description. The tool description compensates substantially by explaining query semantics, field-scoped terms, wildcard examples, ChEBI formatting constraints, limit cap behavior, and column-name-to-key mapping. It does not describe the alias parameters (name, term, search, keyword, etc.) in prose, but the schema already documents those aliases.

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

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

The opening sentence names a specific verb, resource, and expected output: "Search the Rhea reaction database by keyword and return matching reactions." It further distinguishes the tool from exact-ID lookups and sibling entity-search tools by clarifying that matching is keyword/fuzzy across participants, equations, EC numbers, and cross-references.

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 — flexible keyword search over reaction data — and explicitly states what it is NOT for: "NOT exact-ID lookup." However, it does not name alternative sibling tools for exact-ID lookup or other database-specific searches, so the alternatives are implied rather than explicit.

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

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

This is unusually transparent: it discloses silent dropping of extra parameters, HTTP 400 on invalid field names, silent 0-row or unexpected results for ill-formed values, the exact TSV column layout, and the 'Error:' prefix on upstream failure. These details go far beyond the readOnly/openWorld annotations and contain no contradiction.

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

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

The description is longer than average, but every sentence earns its place: accepted parameters, failure modes, alias names, return format, and the required error-prefix check. It is front-loaded with the core purpose and uses structured warnings rather than padding.

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?

It covers return format, failure behavior, accepted parameter aliases, and query-field constraints, which combined with the rich query syntax in the schema makes it largely complete. Minor gaps remain, such as what happens with an empty query and any pagination behavior beyond the schema's default limit.

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 only 25% schema coverage, the description compensates by enumerating all accepted aliases (query, search, term, keyword, keywords, search_term, name) and clarifying that extra parameter names are ignored. The query parameter's syntax is already extensively documented in the schema, so the description does not need to repeat it.

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 'Search for a UniProt entity ID by query,' clearly naming the action and resource, and the subsequent details about Solr queries and TSV output clarify the scope. It distinguishes the tool from sibling search_* tools by resource, though 'entity ID' is slightly imprecise because the tool returns TSV rows rather than a single 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 gives clear context: use it for UniProt queries, express filters inside the Solr query string, and only the search string and limit are accepted. It explicitly warns against extra parameters like taxon/organism/reviewed, but it does not directly compare this tool to sibling search tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context by describing the return format (JSON string of [source_id, target_id] pairs) and the meaning of an empty array. It doesn't discuss failure modes or multi-hop edge cases, but it goes 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 two short paragraphs: the first states the purpose, the second explains the return format. It is front-loaded and every sentence contributes without verbosity. Excellent 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?

For a tool with 4 fully described parameters and an output schema, the description covers purpose, examples, return format, and empty-array semantics. It doesn't discuss error handling or limits beyond schema, but given the annotations and schema, it is quite complete.

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

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

Schema description coverage is 100% for all 4 parameters, with detailed descriptions including examples. The description itself adds no extra parameter semantics beyond the schema; it merely repeats route examples already present in the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: converting identifiers between biological databases, with concrete examples like NCBI Gene to UniProt. This differentiates it from sibling tools like togoid_getRelation (which returns relations) and togoid_countId (which counts). The verb 'convert' plus the resource is specific.

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 ID conversion through examples, but it does not explicitly mention when to use this versus alternatives like togoid_getRelation or togoid_countId. While the purpose is clear, there is no explicit 'when not to use' guidance, though the examples effectively illustrate typical use cases.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds valuable behavioral context: it is a lightweight pre-check, it does NOT return mapped IDs, and it is a single-hop pairwise check. This goes beyond what annotations provide and clarifies the tool's side-effect-free, non-returning nature.

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 a concise bulleted list of use cases and a final clarifying note about parameter style. Every sentence adds value without unnecessary fluff.

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

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

Given the output schema exists, the annotations are present, and all parameters are documented in the schema, the description fully covers the tool's purpose, usage context, behavioral constraints, and relationship to the sibling convertId tool. No critical gaps remain.

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

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

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds meaning by explaining that source and target are passed as two separate args and that this is a single-hop pairwise check, which clarifies the parameter relationship and distinguishes it from convertId's route parameter.

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

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

The description clearly states the tool's function: 'Check how many of your IDs can be converted before doing bulk conversion.' It specifies the resource (source IDs, target database) and explicitly distinguishes itself from the sibling togoid_convertId by highlighting that this is a pre-check that does not return mapped IDs.

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

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

The description provides explicit use cases: verify ID format, estimate result size before a large convertId call, and check if a conversion route works. It also contrasts this tool with convertId's comma-joined 'route' parameter, giving clear guidance on when to use this tool versus the alternative.

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

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

Annotations provide readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds value by explaining the return structure (label, regex, prefix, examples) and clarifying that it returns config rather than data retrieved from databases. It doesn't discuss errors, rate limits, or pagination, but for a parameterless discovery call that's minor. No contradiction with annotations.

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

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

Organized with a field list and use-case bullets; each sentence adds information. A little verbose with repeated tokens like 'You can use' but I'll keep the structure as a 4 because the redundancy is minor.

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

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

For a no-parameter discovery tool it's largely complete: it states the return type and fieldseuristics. It even ties examples to a workflow (testing with countId before bulk conversion) which aids agent planning. Minor gap: it doesn't mention max result size or whether output is localized, but those are minor.

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?

Tool has zero parameters ESA, schema coverage is 100% (empty props), so there is nothing to document. Baseline 4 applies; the description correctly focuses on the return value instead of parameters.

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 first sentence states a specific verb-resource pair: 'List all databases registered in TogoID'. This clearly distinguishes it from sibling tools like togoid_getDescription or togoid_convertId, which operate on specific entities or conversions. The scope 'all databases' is explicit 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?

Three concrete use cases are listed: discovering available databases, checking ID formats, and finding sample IDs to test with countId. This gives the agent a clear sense of when to call it. However, it does not explicitly state when NOT to use it or name a sibling alternative, so it stops short of the full 5.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds behavioral context without contradiction. It explains that this is a planning tool to call early, returns a map of all source→target pairs, and includes examples of common routes, which goes beyond the annotations to convey usage semantics.

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 relatively long but well-structured with headings, bullet lists, and clear sections. It is front-loaded with the main purpose, then provides examples and usage guidance. Every section earns its place, though it could be slightly tightened without losing information.

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

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

Given that the tool has no parameters and an output schema exists, the description is complete. It explains the return type (dictionary of database pairs and metadata), provides examples, and covers when to use/not use. There are no significant gaps for the agent to misunderstand.

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

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

The tool has 0 parameters, so per the rubric the baseline is 4. The description doesn't need to explain parameters, and nothing is missing. It adds value by describing the return structure, which is not covered by the schema since there are no parameters.

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 discovers all available ID conversion routes between databases. It uses a specific verb and resource, and distinguishes from siblings like togoid_getRelation and togoid_convertId by emphasizing it returns all routes for planning.

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 includes explicit 'When to use' and 'When NOT to use' sections, providing clear conditions and alternatives such as using a single SPARQL query when databases share an endpoint or NCBI esearch for cross-referencing. This gives actionable guidance for selecting this tool vs 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 signal read-only and open-world behavior. The description adds valuable behavioral context: `regex` should be used to validate IDs, and `example` IDs should be tested with `countId` before bulk operations. It does not contradict the annotations.

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

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

The description is well-structured and front-loaded with the tool's purpose. The return field explanation is useful and avoids serious filler. It is moderately detailed, but each part earns its place.

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

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

For a single-parameter, read-only metadata retrieval tool with annotations and an output schema, the description is complete. It explains what is returned, how to interpret the fields, and how the returned data can be used in combination with `togoid_countId`.

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

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

The input schema already documents the `dataset` parameter completely, including example values, and coverage is 100%. The description adds some contextual meaning around returned fields like `regex` and `examples`, but it does not deeply expand the dataset parameter semantics beyond what the schema provides.

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

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

The description clearly states it retrieves configuration/metadata for a specific dataset in TogoID, using a specific verb and resource. It explicitly distinguishes from the sibling tool `togoid_getAllDataset` by emphasizing 'specific database' and 'single dataset'.

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 inspecting a single dataset's metadata and mentions using `countId` for testing before bulk conversion. However, it does not explicitly tell the agent when to prefer this tool over siblings like `togoid_getAllDataset` or `togoid_getDescription`.

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

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

Annotations already declare readOnlyHint and openWorldHint; the description adds concrete return format details (dictionary keyed by dataset name) and metadata contents, consistent with those hints. No rate limits or auth requirements are mentioned, but they are not critical for a simple read-only lookup.

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

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

The description is four short, purposeful sentences: purpose, contents, use case, and return shape. It is front-loaded and contains no filler or redundancy.

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

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

For a zero-parameter metadata lookup with output schema and safety annotations, the description fully covers what the tool does, when to use it, and what it returns. It is complete enough for an agent to select and invoke correctly.

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

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

The tool has zero parameters, so the description carries no parameter explanation burden. The baseline of 4 applies because there are no parameters to document.

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

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

The description clearly identifies the tool as retrieving human-readable descriptions for all TogoID databases, including names, descriptions in English and Japanese, and organization info. This specific verb+resource pairing distinguishes it from sibling tools like togoid_getAllDataset or togoid_convertId.

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

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

The description explicitly states it is useful for understanding database contents when planning cross-database queries, giving a clear context for use. It does not name alternatives or exclusions, but the use case is specific enough to guide tool selection.

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

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

The annotations already indicate the tool is read-only (readOnlyHint: true) and may return varying data (openWorldHint: true), covering safety and variability. The description adds crucial behavioral detail: it returns a JSON string of an array of relationship objects with specific fields (forward, reverse, description), and clarifies that an empty array means no direct route exists. It also notes that it is a single-hop pairwise check. This adds context beyond the annotations without contradicting them.

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 appropriately sized. It opens with a clear purpose statement, then immediately gives usage guidance and a contrast with a sibling tool. The return format is described concisely in a separate paragraph, using bullet-like structure. Every sentence adds value, and there is no fluff or repetition.

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

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

The tool is relatively simple (2 params, no nested objects), and the schema covers both parameters fully. The output schema is present, so return values don't need to be overly detailed, but the description still gives a clear summary of the return structure. The description also clearly explains the tool's role in the broader workflow (verify before convertId), and differentiates it from other relation-related tools. It is complete for an agent to select and invoke 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?

The schema already provides examples for both parameters ('uniprot', 'ncbigene' etc.), so coverage is high. The description adds semantic meaning by framing them as 'source' and 'target' for a route check, and explicitly mentions that they are passed separately (unlike convertId). It also tells the user that these are database keys, but the schema examples already did that. The added value is the clarification of how to pass them, which is useful.

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

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

The description clearly states that the tool checks if a specific ID conversion route exists and retrieves its details. It specifies the action ('Check', 'get details'), the resource ('ID conversion route'), and differentiates it from sibling tools like togoid_convertId (which actually converts) and togoid_getAllRelation (which lists all relations).

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

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

The description explicitly states when to use this tool: 'Use this to verify that a particular source→target conversion is available before calling convertId.' It also provides a clear contrast with convertId, which takes a comma-joined route, and explains that this tool requires separate 'source' and 'target' arguments. This gives clear usage guidelines and differentiates from the closest sibling.

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

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

Annotations (readOnlyHint=true, openWorldHint=true) already indicate safe, read-only behavior. The description adds valuable context about what the guide enforces and warns about co-tenancy and unpinned SPARQL risks, going beyond the annotations. No hidden behavior is left undisclosed; it simply returns a string.

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 lengthy but well-structured: the imperative call-to-action is front-loaded, followed by stepwise workflow, measured rationale, and a critical co-tenancy warning. Each section earns its place for a tool meant to be consulted first, though it could be slightly condensed 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 simple parameterless tool, the description is exceptionally complete. It explains why to call it, what the guide contains (DATABASE CATALOG, EXPLORATION habits), and provides the co-tenancy warning essential for correct SPARQL use. The output schema further covers return value details, so no critical context is missing.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. The description compensates by explaining the guide's content and purpose, which is the relevant semantic context. A baseline of 4 is appropriate since there are no parameter semantics to clarify.

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 'Returns the v6 Usage Guide' and positions the tool as the mandatory first call, distinguishing it from sibling query/search tools. The verb 'returns' with resource 'usage guide' and the explicit scope ('before any other TogoMCP tool') make 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 explicitly instructs 'CALL THIS TOOL FIRST every turn' and provides a detailed stepwise workflow (GATE 0, STEP −1 through STEP 4) with when to use which action. It also says 'Re-run GATE 0 every turn', giving clear, concrete usage rules that differentiate it from 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses internal re-ranking behavior, match_type semantics, loose token matching pitfalls, and coverage limitations. It also clarifies that unlisted parent MONDO IDs still work downstream, adding crucial behavioral context.

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

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

The description is longer than average but every paragraph adds substantive context: purpose, ranking logic, and coverage limitations. It is front-loaded with the core purpose and then provides necessary caveats, though some internal references (e.g., TogoMCP RDF databases) could be trimmed.

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

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

Given the tool's complexity and the presence of an output schema, the description is exceptionally complete: it covers return field semantics, ranking order, edge cases, alternatives, and downstream integration. No critical behavioral aspect is left unexplained.

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

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

The schema already fully describes both parameters (`query` and `limit`) with types, ranges, defaults, and examples, so the description adds no new parameter-level detail. The baseline 3 is appropriate given complete schema coverage.

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

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

The description clearly states the tool resolves a disease term to MONDO/MedGen IDs for variant search, giving a specific verb and resource. It distinguishes itself from sibling tools by explicitly linking its output to `search_variant`'s `disease_id` parameter.

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

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

The description explicitly explains when to use this tool: to resolve a disease term before calling `search_variant`. It also provides an alternative — using OLS4 or the `mondo` RDF database to resolve canonical MONDO IDs directly — and warns that the resolver is not exhaustive.

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 readOnlyHint/openWorldHint annotations, disclosing the endpoint's loose token matching, lack of relevance order, client-side re-ranking, match_type values, and false-positive risk. It also explains the symbol/name echo behavior and the absence of approved-vs-alias status, giving the agent actionable behavioral 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?

The description is front-loaded with a clear purpose sentence, then each subsequent sentence earns its place by explaining workflow placement, matching quirks, and result interpretation. Despite being detailed, it is free of filler and tightly organized around helping the agent avoid a real failure mode.

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-step lookup tool with an output schema and complete parameter schema, the description is fully complete: it covers purpose, input semantics, workflow linkage, output field interpretation, and caveats. Nothing important is left unexplained for safe invocation.

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

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

The input schema already covers both parameters at 100%, so the baseline is 3, but the description adds meaningful query semantics: loose token matching, exact/prefix/word/fuzzy re-ranking, and the significance of match_type. The limit parameter is not expanded beyond the schema, but the added query behavior justifies a slightly higher score.

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: 'Resolve a human gene symbol/alias to its HGNC ID for variant search.' It clearly distinguishes this from sibling tools like togovar_search_disease and togovar_search_variant by framing it as the gene-resolution step for the variant workflow.

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

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

The description explicitly positions this as 'the FIRST step of the two-step variant workflow' and states that the returned hgnc_id is what search_variant takes as gene_hgnc_id. It also gives strong when-to-use caution: check match_type and do not blindly feed the first hgnc_id downstream unless the top hit is exact.

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

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

Despite having readOnlyHint and openWorldHint annotations, the description goes far beyond them, disclosing the paging cap of 10,000 with HTTP 400, the peculiarity of `total` being constant, the statistics granularity caveats, and the round-trip to SPARQL conditions. This provides critical behavioral context that annotations do not cover.

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

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

The description is long but every section serves a purpose: the statistics caveats, paging cap, and SPARQL mapping are critical for correct usage. The use of bold headers and bullet-like structure improves readability, though it could be slightly more concise without losing essential warnings.

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

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

Given the tool's complexity (20 parameters, output schema, advanced features), the description is remarkably complete. It covers filtering logic, count semantics, statistics pitfalls, paging limitations, SPARQL integration, and workflow prerequisites. This is one of the most thorough descriptions for a complex tool, leaving little ambiguity.

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 80% schema description coverage, many parameters are well-described in the schema, and the description adds value by explaining the `stat` parameter in depth, the two-step workflow for gene_hgnc_id and disease_id, and noting the importance of limiting results. However, some parameters like max_frequency and min_frequency lack description beyond the schema, but the description's coverage is strong.

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

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

The description clearly states the verb ('Search') and resource ('TogoVar for human genome variants with population frequencies'). It also differentiates from siblings by emphasizing the integration of allele frequencies and clinical significance, and explicitly mentions 'no SPARQL counterpart elsewhere in TogoMCP', distinguishing it from run_sparql and related tools.

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

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

The description provides extensive guidance on when to use this tool, including a two-step workflow for gene/disease filters (referencing togovar_search_gene and togovar_search_disease). It also explains when not to use SPARQL (when variant lacks tgv_id) and notes the REST backend is larger than SPARQL, helping choose between tools.

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