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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable context: the truncation contract (total, returned, limit, truncated), the 'next_commands' widening step, and the precise effect of include_descendants (roll-up via MP ontology). No contradictions with annotations.

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

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

The description is compact (two sentences plus a signature line) with no filler. It front-loads the core purpose ('Reverse lookup: return the mouse markers...') and every sentence adds unique value. The signature line at the end reinforces parameter order.

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

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

For a read-only query tool with 3 parameters and no output schema, the description covers all essential aspects: purpose, parameter behavior (especially include_descendants), truncation handling, and the prerequisite to resolve terms. It leaves no significant gaps for an AI agent to understand invocation.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds meaning beyond the schema: it explains that include_descendants defaults to TRUE and 'rolls up annotations to more-specific child terms,' which clarifies its impact. It also provides the function signature and mentions the truncation contract, which is not in the schema.

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

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

The description clearly states the action: 'return the mouse markers (genes) annotated with a Mammalian Phenotype term.' It uses a specific verb ('return') and resource ('markers'), and distinguishes from siblings like get_marker_phenotypes (forward lookup) and search_phenotype_terms (term resolution). The 'Reverse lookup' phrasing immediately clarifies its unique role.

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

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

The description instructs users to 'Resolve a term first with search_phenotype_terms,' providing a clear prerequisite. It explains the behavior of include_descendants and mentions the truncation contract. However, it does not explicitly state when not to use this tool (e.g., for forward lookups or gene-level queries), but the sibling context helps fill that gap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds valuable behavioral context: what data it returns (counts, schema version, build time). No contradictions with annotations.

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

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

Two sentences, no wasted words, front-loads the purpose. Signature is provided at the end for clarity.

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

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

For a 0-parameter tool with no output schema, the description fully covers what the tool returns and when to use it. No gaps.

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

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

No parameters (schema coverage 100% with empty properties). The description adds no parameter info, but that's appropriate since there are none. Baseline for 0 parameters is 4, and the description doesn't need to compensate.

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 'report[s] the local MGI index status' with specific details like counts, schema version, and build time. The verb 'report' and resource 'local MGI index status' are specific, and it distinguishes well from sibling tools which focus on querying markers, phenotypes, etc.

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

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

Explicit guidance: 'Use this to confirm freshness or diagnose a data_unavailable error.' This provides clear context for when to use the tool. No explicit when-not-to-use is given, but the purpose is narrow enough that it's not needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is clear. The description adds value by detailing the returned fields (name, type, location, ids, ortholog, counts), and mentions the response_mode parameter for verbosity control. No contradictions with annotations.

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

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

The description is two sentences plus a signature line, no wasted words. Purpose is front-loaded, and all essential information is present. The structure efficiently conveys what the tool does and how to use it.

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

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

There is no output schema, so the description compensates by listing the major components of the returned record. It covers query format, response modes, and typical contents. However, it does not mention error behavior (e.g., what if query not found) or pagination, but for a single-record retrieval these are secondary.

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

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

Schema coverage is 100%, so baseline is 3. The description provides additional context for the 'query' parameter (accepted formats: MGI id, symbol, human ortholog) and shows the signature with default response_mode. This goes beyond the schema descriptions which already cover the basics.

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 'Return' and the resource 'full MGI marker record', and specifies that it resolves from multiple query types (MGI id, mouse symbol/synonym, human ortholog). It also lists the contents, distinguishing it from sibling tools that return subsets (e.g., get_marker_alleles, get_marker_diseases).

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

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

The description implies when to use this tool (to get the full marker record) but does not explicitly state when not to use it or mention alternatives. Sibling tools exist for specific aspects, but no contrast is provided. Some guidance on query flexibility is given.

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

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

Annotations already indicate readOnly, idempotent, openWorld. Description adds valuable context: truncation contract with next_commands, friendly token acceptance for allele_type, and output structure. No contradictions.

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

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

Description is comprehensive but slightly dense; includes a signature summary. Every sentence adds value, but could be slightly more concise. Well-organized: purpose, output, filter, truncation, signature.

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?

Complete for a tool with 4 params and no output schema: explains return fields, truncation contract, filter options, and query flexibility. No missing critical information.

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%, baseline 3. Description adds significant meaning: explains allele_type accepts friendly tokens (knockout, crispr), lists response_mode verbosity levels, describes query input types (symbol, MGI, HGNC), and mentions limit default/max. Goes well beyond schema descriptions.

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

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

Description clearly states it returns phenotypic alleles/mutations for a mouse marker, referencing the gene page's panel. Distinguishes from siblings like get_marker (marker details) and search_markers (searching markers) by specifying the exact resource and output.

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

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

Provides clear context for when to use (get alleles for a marker) but does not explicitly state when not to use or mention alternatives. However, the purpose is self-evident and agent can infer from sibling names.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context about output content (disease models, DO id, name, OMIM ids) and data source, but does not disclose additional behavioral traits beyond what annotations provide, meeting expectations without exceeding.

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

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

Two sentences plus a concise signature. Front-loaded with purpose, no filler words. Every sentence adds value.

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

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

Given the tool's simplicity (1 parameter, no output schema), the description adequately explains input and output. It could optionally mention pagination or rate limits, but the openWorldHint reduces need. Generally complete for an agent's invocation.

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

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

Schema covers 100% of parameters. Description adds valuable details beyond schema: clarifies case-insensitivity, synonym support, and alternative human identifier formats (HGNC id). This enhances parameter understanding beyond basic schema.

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

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

The description clearly states it returns disease models (Disease Ontology id + name + OMIM ids) from MGI annotations, with specific verb 'Return' and resource. However, it does not differentiate from sibling tools like get_marker_phenotypes, so it's not 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 lists accepted input types (mouse symbol/MGI id or human ortholog) but provides no guidance on when to use this tool versus alternatives like get_marker_phenotypes or search_markers. No explicit when/not-to-use or alternative names.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by explaining the resolution step (human to mouse first) and listing returned fields. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with purpose, and includes a signature line. Every word adds value with no redundancy.

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

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

Given no output schema, the description lists output fields. Sibling tools are diverse and this is unique. The description is self-contained and complete for a lookup tool.

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

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

Schema coverage is 100% and includes examples. The description adds context about the resolution process and the list of returned fields, providing meaning beyond the schema alone. Baseline 3 is elevated due to this extra detail.

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's purpose: returning mouse-human ortholog mapping and cross-references. It lists specific output fields (human symbol, HGNC id, etc.) and distinguishes from sibling tools (no other tool does ortholog mapping).

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

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

The description specifies acceptable inputs (mouse symbol/MGI id or human symbol/HGNC id) and mentions the resolution process. It clearly states the input types, though it does not explicitly state when not to use or compare to siblings. However, among siblings, none are ortholog-specific, so context is clear.

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

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

Annotations already indicate safe, read-only behavior. The description adds critical details: deduplication, support ordering, truncation contract with next_commands, scope limitations, and response structure. No contradiction with annotations.

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

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

The description is lengthy but well-structured with clear sections (default behavior, full mode, response contract, mp_system, scope). Every sentence adds useful information, though could be slightly more concise.

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

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

Given no output schema, the description fully explains the response format, truncation mechanism, and scope limitations. All 4 parameters are thoroughly addressed with behavioral context. Provides enough for correct invocation.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by explaining response_mode modes (minimal/compact/standard/full), the effect of mp_system (accepts name or MP id), and providing query examples. Enhances understanding beyond schema.

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

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

The description clearly states the tool returns Mammalian Phenotype annotations for a mouse marker, with specific verb (Return) and resource (MP annotations). It distinguishes from siblings like find_markers_by_phenotype by focusing on marker-to-phenotype direction.

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

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

The description provides context on when to use (get MP annotations for a single marker) and explicitly excludes conditional and multi-genic genotypes. It advises confirming on MGI page for zero results. Does not explicitly name alternatives but scope note is helpful.

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

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

Annotations already indicate safe read-only, idempotent behavior. The description adds detail about the return structure (parents, children, top-level systems) and input format, which provides useful behavioral context beyond annotations.

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

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

The description is two sentences plus a signature line, every sentence adds value. It is front-loaded with the primary action and details are efficiently presented.

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

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

Given the complexity of an ontology term lookup, the description fully specifies the return fields and how to use the output with sibling tools. No output schema is present, but the description provides sufficient structural context.

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

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

Schema coverage is 100% with clear description and examples. The description adds little beyond restating the parameter name and format, providing no additional semantic depth.

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

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

The description specifically states the action 'Return a Mammalian Phenotype (MP) ontology term' and lists exact fields returned (id, name, definition, parents, children, top-level systems). It clearly distinguishes from sibling tools like find_markers_by_phenotype by specifying the output.

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

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

The description explicitly recommends chaining with find_markers_by_phenotype and provides the function signature. Although it does not list when not to use it, the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds valuable context about scope (single-locus, non-conditional genotypes), source (MGI_GenePheno), and potential absence of systems, which goes beyond annotations. 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?

Description is a single paragraph but well-structured, front-loading the core purpose and then adding usage guidance and scope details. Could be slightly more concise, but no unnecessary words.

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

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

Given no output schema, description adequately explains what the grid contains (top-level MP systems, distinct MP terms rolled up via ontology) and its limitations. References response fields ('scope'/'scope_note') for further detail. Complete for a single-parameter tool.

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

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

Schema coverage is 100% with description for query. Description adds meaning by clarifying that query can be mouse symbol, MGI id, or human gene symbol/HGNC id, which is not explicit in schema. Also mentions case-insensitivity and synonyms.

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

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

Description clearly states 'Return a per-system phenotype overview grid' with specific resource (phenotype overview for marker) and verb ('return'). Distinguishes from sibling tool get_marker_phenotypes by stating it provides system-level overview and then drills into one system.

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

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

Explicitly says 'Use this for the system-level overview, then get_marker_phenotypes(mp_system=) to drill into one system.' Also specifies exclusion criteria (conditional/Cre-driven, multi-genic genotypes) and notes that not being a full mirror of MGI gene page, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already cover safety (readOnly, idempotent, etc.), but the description adds behavioral details: the content of each detail level and the fact that it serves as an entry point for discovery, which goes beyond mere annotation replication.

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 information-dense but well-structured, front-loading the primary purpose, then detailing levels. The 'Signature:' line is slightly redundant with schema but not harmful. Could be trimmed, but overall efficient.

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

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

Given no output schema, the description thoroughly covers return content for both detail levels, mentions alternative discovery methods, and provides session context. Nothing essential is missing for an agent to understand and use the tool.

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

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

While schema provides enum descriptions, the description adds substantial meaning: it explains what 'summary' and 'full' return (e.g., identity, tool list, vocabularies), significantly enhancing utility beyond the schema's terse 'summary (default, light) or full (adds vocabularies).'

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

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

The description clearly states the tool returns the mgi-link discovery surface, specifying two detail levels (summary and full) and their contents. It distinguishes itself from sibling tools, which are primarily query tools for markers, phenotypes, etc.

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

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

Explicitly instructs to call this first in a cold session or read mgi://tools / mgi://capabilities, providing clear when-to-use guidance without ambiguity.

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

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

The description goes beyond annotations (readOnly, idempotent) by detailing return fields, ambiguous query error behavior with candidate list, and human-mouse symbol collision resolution. The case-insensitivity and MGI ID format acceptance are also disclosed.

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

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

The description is well-structured, front-loaded with core purpose, and includes key details efficiently. Some sentences are dense but not overly verbose; it could be slightly tighter.

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

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

With no output schema, the description fully specifies return fields and covers edge cases (ambiguous symbols, ortholog collisions). It also explains the response_mode parameter. Given the tool's simplicity, it is complete.

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

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

Schema coverage is 100%, providing baseline. The description adds value by explaining input types for query, case-insensitivity, and example formats like 'MGI:98968'. For response_mode, it lists enum options and default, enriching understanding.

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 resolves mouse marker references to canonical MGI records, specifying three input types (mouse symbol, MGI ID, human ortholog). It distinguishes from siblings like get_marker and get_marker_ortholog by explicitly covering ortholog resolution and ambiguous handling.

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

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

The description explains what inputs it accepts and what it returns, providing clear context for use. However, it does not explicitly tell when to use this tool versus alternatives like get_marker or search_markers, limiting guidance on exclusion.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description's job is to add operational details. It does so by explaining exact-match pinning, truncation contracts with next_commands, and relevance ranking. This adds significant transparency beyond annotations, though it could mention response_mode behavior more explicitly.

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, using only a few sentences to convey purpose, behavior, exclusions, and signature. It is front-loaded with the core function and efficiently uses space without redundancy.

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

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

Given no output schema, the description fully describes the return format (ranked summaries and truncation contract) and the effect of the marker_type filter. It also mentions response_mode verbosity. Combined with rich annotations, the description is complete for agent understanding.

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%, but the description adds substantial meaning beyond schema: it explains the pinning behavior based on query, the truncation contract, the marker_type filter effect, and lists the response fields. It also provides the function signature, making parameter usage very clear.

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 performs free-text search over mouse marker symbols, names, and synonyms with relevance ranking and pinning of exact matches. It distinguishes from sibling tools by specifying it is nomenclature-only, explicitly naming alternatives like search_phenotype_terms and resolve_marker for phenotype and exact lookups.

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

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

The description explicitly states when to use (free-text nomenclature search) and when not to use (no phenotype semantics), providing alternative tool names and their purposes. This gives clear guidance against misuse.

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

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

The description adds significant behavioral context beyond annotations (readOnlyHint, idempotentHint, etc.): it discloses that the search is FTS, relevance-ranked, and includes a truncation contract with next_commands. This transparency helps the agent understand search behavior and pagination without contradictions.

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

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

The description is concise (4 sentences), front-loaded with the main purpose, and every sentence adds value (usage guidance, truncation details, signature). No redundant or unclear text.

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

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

Despite no output schema, the description lists return fields ({mp_id, name, definition, score}) and explains the truncation contract, making the tool's behavior fully understandable. Combined with clear usage guidance and parameter docs, it is contextually complete for an AI 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 100% with clear parameter descriptions. The description reiterates the parameter meaning (e.g., 'query' as free-text) and mentions the default limit, but does not add new semantic information beyond what the schema already provides. Thus, 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 a specific verb 'Free-text search' over 'Mammalian Phenotype (MP) term names and definitions', indicating the resource and action. It distinguishes from sibling tools like find_markers_by_phenotype by explicitly stating the use case and subsequent steps.

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

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

The description provides explicit guidance: 'Use this to resolve a phenotype description to an MP id' and suggests subsequent tools (find_markers_by_phenotype, get_mp_term). It also mentions the signature and default limit, leaving no ambiguity about when to invoke this tool.

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