OMOPHub MCP Server

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

No annotations are provided, so the description carries the full burden. It discloses the aggregated nature (combines three operations), and labels itself as an overview tool, but doesn't explicitly state read-only behavior, error handling, or potential for large responses. The verb 'Get' implies safety, but not 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?

Two sentences, first is a clear statement of function and components; second gives usage guidance. No redundant words or irrelevant 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?

The tool is complex with 6 parameters and no output schema. The description explains the combined nature and the overview scope, and the schema covers all parameters. However, it lacks a detailed explanation of the response structure or any explicit limitations on result size beyond parameter descriptions, so not fully 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%, with thorough parameter descriptions including defaults and ranges. The main description adds no parameter-specific semantics, but the schema fully compensates, so baseline 3 applies.

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

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

The description uses specific verb 'Get', resource 'medical concept', and clearly enumerates the three components (detailed info, ancestors/descendants, mappings). It explicitly distinguishes from siblings by recommending replacing get_concept + get_hierarchy + map_concept, making 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 explicitly states 'Use this instead of calling get_concept + get_hierarchy + map_concept separately' and provides ideal use cases ('Ideal for understanding...'), giving clear when-to-use guidance. It also indirectly says this is an overview tool, with additional exclusion note in the mappings_page_size parameter description recommending map_concept for complete code lists.

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 no annotations, the description carries the full burden. It discloses fallback behavior (semantic search), optional recommendations, and unmapped handling, but does not explain output format (e.g., single vs. multiple results), ordering, or error behavior beyond the on_unmapped parameter. Adequate but not thorough.

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 concise with three sentences and an example. The main purpose is front-loaded, and the example aids clarity. Minor verbosity could be trimmed, but overall it is 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?

The description covers input parameters and general behavior but lacks details on the output structure (e.g., what fields are returned for the resolved concept and target table). With no output schema, this gap is notable. Also, given the sibling list, more contextual differentiation would improve completeness.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description adds value by explaining the 'display' parameter's role in semantic search fallback and the 'include_recommendations' parameter's relation to Phoebe recommendations. This extra context enhances understanding beyond the schema.

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

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

The description clearly states it resolves FHIR coded values to OMOP standard concepts and CDM target tables, with examples for system/code and text-only input. However, it does not explicitly distinguish itself from the sibling 'fhir_resolve_codeable_concept', which may have similar functionality.

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 examples of when to use the tool (e.g., system/code or text-only display) but lacks explicit guidance on when to choose this tool over siblings like 'map_concept' or 'fhir_resolve_codeable_concept'. Usage context is implied but not 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?

No annotations provided, so the description carries full burden. It discloses vocabulary preference hierarchy, semantic search fallback, unmapped behavior options (error or sentinel), and boolean flags for recommendations and quality. However, it does not mention return format or potential side effects like HTTP status codes or rate limits.

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

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

Two sentences, no filler, front-loaded with the core purpose. Every sentence adds distinct value: first sentence states main action and preference, second sentence covers fallback and behavior. Efficient and well-structured.

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

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

Tool has 6 parameters and no output schema. Description covers core logic but omits what the tool returns (e.g., concept ID, error details). Without an output schema, the agent lacks clarity on result structure. Also does not explain the resource_type parameter's role. Could be more 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 67%, but description adds substantial meaning: explains vocabulary preference order, the role of user_selected to override preference, fallback logic using text, and the purpose of on_unmapped, include_recommendations, and include_quality. This goes well beyond the schema's field 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 explicitly states it resolves a FHIR CodeableConcept with multiple codings, specifies vocabulary preference order (SNOMED > RxNorm > LOINC > CVX > ICD-10), and mentions fallback to text via semantic search. This is a specific verb-resource combination that distinguishes it from siblings like fhir_resolve or map_concept.

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

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

The description implies usage when handling CodeableConcepts with multiple codings and notes the fallback behavior, but does not proactively state when to use this tool versus alternatives (e.g., simpler fhir_resolve, or search_concepts). No explicit when-not-to-use or alternative suggestions.

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?

No annotations are provided, so the description bears the full burden of behavioral disclosure. It explains the three algorithms with trade-offs ('semantic' best for meaning, 'lexical' best for typos, 'hybrid' default), enforces the exactly-one-input constraint, and offers a practical tip about drug vocabulary usage. It does not describe output format or edge cases, but for a read-only similarity search this is a solid level of transparency.

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

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

The description is compact and front-loaded: it opens with the core function, uses semicolons and em-dashes to pack algorithm details, and remains under three sentences. The final tip is extra but earns its place by providing practical guidance. 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 8 parameters and no output schema, the description covers the main decision points: algorithm selection, the three input modes, and intended use cases. Filters like domain_ids and vocabulary_ids are left to the schema, which adequately documents them. It could mention default thresholds or result ranking, but overall it is sufficiently complete for a search tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful value beyond the schema by explaining algorithm behavior, clarifying that query is natural language, and emphasizing the exactly-one-of constraint. The drug vocabulary tip also enriches parameter semantics, helping agents choose appropriate inputs for RxNorm concepts.

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

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

The description clearly states the tool's function: 'Find medical concepts similar to a reference concept, name, or natural language query.' It specifies the verb (Find), resource (medical concepts), and input types (concept_id, concept_name, query). It also distinguishes from siblings by emphasizing similarity search and naming three algorithms, plus concrete use cases like exploring related concepts and building phenotype sets.

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

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

The description provides clear usage context: 'Use this to explore related concepts, find alternative codes, or build phenotype concept sets.' However, it does not explicitly mention when not to use this tool or name alternatives like get_concept or search_concepts, even though sibling tools exist. The guidance is adequate but lacks direct exclusion or comparison.

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?

No annotations are provided, so the description carries full burden. It lists the returned fields but does not disclose error handling (e.g., behavior for invalid concept_id), rate limits, or any side effects. For a simple retrieval tool, it is adequate but has gaps.

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

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

Two concise sentences: first defines the action and returns, second states use case. No wasted words 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?

Given the tool's simplicity (1 required param, no output schema), the description covers the purpose and return fields reasonably. Minor gaps: no mention of error handling or full return structure (e.g., whether concept_id is included in response).

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 a description of concept_id as 'The OMOP concept_id (numeric identifier)'. The description reinforces it is numeric but adds no additional semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves detailed information about a specific OMOP concept by its numeric concept_id, listing specific returned fields. It distinguishes itself from sibling tools like search_concepts or explore_concept by specifying that it requires an exact concept_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 explicitly says 'Use this when you already have a concept_id and need its details,' providing clear usage context. However, it does not mention when not to use it or suggest alternative tools for searching or exploring concepts.

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?

No annotations provided, so description bears full burden. It discloses that same code can exist across vocabularies and that multiple matches may be returned. For a simple lookup, this is adequate, though it does not mention exact match behavior or response structure.

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 fluff. Front-loaded with tool purpose, then important details. Every sentence earns its place.

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

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

Given no output schema, description mentions the preferred result (standard_concept='S') but lacks details on return format or edge cases. Still, for a lookup tool, it is reasonably complete.

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

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

Schema coverage is 100% with detailed descriptions for both parameters. The description reinforces the necessity of both parameters and clarifies ambiguity, adding marginal value beyond the schema. 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 clearly states 'Look up an OMOP concept using a vocabulary-specific code and vocabulary ID.' It specifies verb (look up), resource (OMOP concept), and required parameters, distinguishing it from siblings like search_concepts or get_concept.

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 explains that both parameters are required to avoid ambiguity and provides concrete example (E11 in ICD10CM and ICD10). It advises preferring standard_concept='S' when multiple matches exist. While it doesn't explicitly state when not to use this tool, it provides clear context for its use.

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

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

With no annotations, the description carries the full burden. It discloses result capping ('capped at max_results nodes default 200'), truncation behavior ('If truncated, the response will indicate total available count'), and provides remediation guidance ('narrow with vocabulary_ids or reduce max_levels'). This adds behavioral context beyond the schema.

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

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

Three sentences, front-loaded with the core purpose, each sentence adds meaningful guidance. 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 description covers direction semantics, result limits, truncation handling, and narrowing strategies. While it lacks explicit return-structure details, the absence of an output schema is partially mitigated by the phrase 'Results are capped at max_results nodes', implying a list of nodes. Overall sufficient for a 5-param hierarchy tool.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameters by providing real-world examples for direction, explaining the purpose of 'down' for concept sets, and explaining the interplay between max_results, vocabulary_ids, and max_levels for dealing with truncation.

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 ('navigate') and resource ('vocabulary hierarchy for a concept') with concrete examples (e.g., 'Diabetes mellitus' → 'Metabolic disease'). This clearly distinguishes it from sibling tools like search_concepts or get_concept.

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 explicitly instructs when to use each direction value ('direction=''up'' for ancestors... down for descendants... both for full context') and highlights a key use case ('essential for building concept sets in phenotype definitions'). It does not explicitly name alternative tools, but the context is clear.

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

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

No annotations are provided, so the description must disclose behavioral traits. It correctly indicates this is a read-only listing operation with no destructive side effects. It mentions the output includes concept counts and metadata, giving a clear picture of what to expect. Could add more detail about pagination or sorting, but for a simple list tool this is adequate.

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 long with no wasted words. The first sentence states the action and output, the second gives usage guidance. Each sentence serves a clear purpose.

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 list tool with one optional parameter and no output schema, the description is complete. It conveys the scope (medical vocabularies), output details (concept counts and metadata), and usage context. No further information is needed for an agent to use 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?

There is one optional parameter 'search' with a max length of 200, and schema coverage is 100%. The description does not provide additional semantic detail beyond the schema, such as supported search patterns or case sensitivity. The baseline of 3 is appropriate since the schema already documents the parameter sufficiently.

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

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

The description clearly states the tool lists all available medical vocabularies with concept counts and metadata. It gives specific examples (SNOMED CT, ICD-10-CM) and the verb 'list' with resource 'vocabularies' is unambiguous. Sibling tools like 'search_concepts' or 'get_hierarchy' are distinctly different, so this stands out.

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

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

The description explicitly tells when to use the tool: 'Use this to understand what terminology systems are available and their scope.' It implies a discovery purpose. While it doesn't explicitly state when not to use or list alternatives, the context from sibling tools makes it clear this is for browsing vocabularies, not concepts.

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

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

Discloses response structure: 'Returns cross-vocabulary mappings with relationship types and mapping quality.' Also reveals edge case behavior: 'If no mappings exist, the response explicitly states "No mappings found" with mapped=false — never returns ambiguous empty results.' Pagination behavior is disclosed in detail. No annotations provided, so description carries full burden and does it well.

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

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

The description is somewhat lengthy but front-loaded with the core purpose in the first sentence. Subsequent sentences add valuable behavioral and usage details. It repeats pagination guidance already in the schema, but the whole description remains readable.

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 annotations and no output schema, the description covers essential context: what the tool does, how to use it, empty-result behavior, and pagination. It gives enough for an agent to call and interpret results correctly. It also provides a practical example.

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 all parameters (100% coverage), but the description adds a concrete example and clarifies the directionality of concept_id ('always the SOURCE — results show what it maps TO'). This reinforces the parameter semantics beyond the schema.

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

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

Description clearly states 'Find mappings FROM a source concept TO equivalent concepts in other vocabularies' — specific verb, resource, and direction. The example with SNOMED to ICD10CM further clarifies. It distinguishes from siblings like 'find_similar_concepts' (similarity vs exact mappings).

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 concrete example usage (SNOMED concept_id filtered by target_vocabularies='ICD10CM') and explicit pagination instructions ('keep incrementing page until has_more is false'). It does not explicitly name alternatives but clearly describes when this tool is appropriate for cross-vocabulary mapping lookup.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool returns (IDs, names, vocabulary, domain, standard status) and the search scope, which is useful. However, it does not mention whether the operation is read-only (though implied by 'search'), how pagination works, or any limitations on search behavior. This is adequate for a search tool but leaves some gaps.

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

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

The description is concise, with two sentences and a list of examples, and it front-loads the primary purpose. The structure is efficient and easy to scan. However, there is a typographical issue ('OHCPD' instead of likely 'OHDSI'), which slightly undermines clarity and precision.

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

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

The description covers the essential context for a search tool: what it searches, what it returns, and when to use it. It provides examples and relies on the well-documented schema for parameter details. Since there is no output schema, the description's mention of return fields is important. It could be improved by stating default sorting or pagination behavior, but for a straightforward search/filter tool, it is largely complete.

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

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

The input schema already provides 100% coverage for all 6 parameters, including descriptions for query, page, page_size, domain_ids, vocabulary_ids, and standard_concept. The tool description adds example queries but does not add new meaning to the parameters themselves. Since schema coverage is high, the 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 function: searching for medical concepts across standardized vocabularies by name, synonym, or clinical term. It specifies the resource (OMOP concepts) and the action (search), and distinguishes from sibling tools like get_concept or get_concept_by_code by emphasizing term-based lookup and the return of concept IDs and metadata. The examples ('type 2 diabetes', 'metformin 500mg') further clarify the intended use.

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

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

The description explicitly says 'Use this when you need to find the OMOP concept ID for a medical term,' which provides clear context for when to invoke this tool. It does not explicitly name alternatives or when not to use it, but the use case is stated. This is sufficient but lacks the exclusionary guidance seen in the calibration example.

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 no annotations provided, the description carries the full burden. It explains the semantic matching behavior, notes that results are 'ranked by similarity score,' and gives illustrative examples. It does not cover edge cases or system limits, but the core behavioral traits are well 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 three sentences long, front-loaded with the core purpose, followed by illustrative examples and usage guidance. Every sentence adds value with no redundancy or fluff.

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

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

The tool has 6 parameters and no output schema. The description gives sufficient context for a semantic search tool, including what it returns ('concepts ranked by similarity score') and when to use it. It lacks detailed output structure, but that is not critical for understanding 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 has 100% description coverage for all 6 parameters, so the description does not need to compensate. The description reinforces the query semantics with examples but does not add significant new detail beyond the schema's parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Search for medical concepts using natural language with neural embeddings.' It differentiates from keyword search with concrete examples ('heart attack' finds 'Myocardial infarction'), making it distinct from sibling tools like search_concepts.

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

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

The description explicitly says 'Use this when the user describes symptoms, conditions, or treatments in everyday language rather than exact medical terminology.' This gives clear when-to-use guidance and implies when-not-to-use, though it does not name specific alternative tools.

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