can-immune

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

With no annotations, the description carries the full burden. It details the return contents: 'total counts of mutations, genes, and unique mutant peptides, plus how many cell lines, tissues, and cancer types are covered, and the data sources.' This discloses the behavioral trait of returning aggregate statistics. It does not mention side effects, but the read-only nature is clear.

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, front-loaded with the core function, then lists return values, and ends with usage guidance. Every sentence adds value without redundancy. It is appropriately sized for a simple 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?

Even without an output schema, the description enumerates the return payload in detail (counts of mutations, genes, peptides, cell lines, tissues, cancer types, data sources). It also provides usage context and parameter information, making it a complete description for a zero-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?

The tool takes no parameters, so the schema is empty. The description explicitly states 'No parameters,' reinforcing this. There is nothing else needed for parameter semantics, matching the baseline for zero-parameter tools.

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 the headline size of the CAN-IMMUNE database in one call.' This distinguishes it from sibling tools that lookup specific entries or list options. The verb 'Get' and resource 'database' make the function clear.

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

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

Gives explicit usage context: 'Use this first to size the resource or to answer "how big is the database / how many X are there" questions.' This implies when to reach for this tool over others, though it does not explicitly name alternatives or exclusions.

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

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

With no annotations, the description carries the full burden. It discloses the return structure ({id, title, text, url, metadata}) and explains that text is the full JSON profile, matching get_gene/get_cell_line. It also mentions the id format. It doesn't cover error handling, but for a read-only fetch this is reasonably transparent.

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 exactly two sentences, each containing crucial information: purpose, input example, output format, relationship to siblings, and the prerequisite. 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 single-parameter read tool with no output schema, the description covers purpose, usage, input format, output structure, and prerequisite. It also references sibling tools for context. It lacks edge-case behavior, but that is minor and not needed for this simple 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 the schema already describing the id format and examples. The description largely repeats the examples without adding new parameter-level semantics. Thus, 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 'fetches the full record for an id returned by search', which is a specific verb+resource. It also distinguishes itself from siblings by referencing that it returns the same data as get_gene/get_cell_line, clarifying its 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?

It explicitly instructs to 'Always call search first to obtain a valid id', establishing a clear usage prerequisite. It does not explicitly exclude alternatives like get_gene/get_cell_line, but the reference to them implies when fetch is appropriate (when you already have a search id).

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 the full burden. It discloses the return fields, mentions a link, and explicitly states 'Returns an error field if the name is not found'. This is thorough for a read-only lookup tool, though it doesn't explicitly state that it's a read-only operation.

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: purpose, return details, and usage/error behavior. It is front-loaded with the primary action and contains no redundant content, though it's slightly longer than absolutely necessary.

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 returns a rich profile and there is no output schema or annotations, the description adequately covers return contents, error behavior, and usage context. It includes all key details to set expectations without 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?

Schema description coverage is 100% with a clear description of the 'name' parameter including examples and a suggestion to use search first. The tool description adds no additional 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 'Get the full profile for one cancer cell line by exact name'. It lists specific return contents (tissue, cancer type, mutations, etc.) and explicitly contrasts with search_cell_lines by emphasizing 'full profile' vs. search, making its 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?

Explicit guidance is provided: 'Use after search_cell_lines, or when the exact name is known, for a deep dive on one line.' This tells the agent when to use this tool and implicitly when not (when unsure of exact name, use search).

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

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

With no annotations, the description carries full burden. It fully discloses the return contents and explicitly mentions that an error field is returned if the symbol is not found. It does not explicitly state read-only behavior, but 'Get' makes this evident; the error-handling disclosure is a strong positive.

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 yet information-dense: purpose first, then return summary, then usage context, then error behavior. Every sentence adds unique value; no word is wasted.

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

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

Given the tool's simplicity (1 parameter, no output schema, no annotations), the description covers everything needed: what it returns, error behavior, and when to use it. It fully compensates for missing structured metadata.

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 parameter description provides concrete meaning beyond the schema: 'Exact HGNC gene symbol' with examples and a note to use search_genes first if unsure. Schema coverage is 100%, and the description enriches the single parameter with practical guidance.

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 begins with 'Get the full profile for one gene by exact symbol' — a specific verb+resource that clearly states the action. It also enumerates the returned data fields, distinguishing it from sibling tools like get_gene_mutations and search_genes.

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 use after search_genes or when the symbol is already known, and says it answers detailed questions about a single gene. This clearly establishes when this tool is appropriate and names the alternative for symbol 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 fully carries the burden. It discloses that results are capped at limit (max 100), ordered by mutation ID, and lists every column returned. This goes beyond a simple read operation and gives the agent clear expectations for performance and output 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?

The description is two concise paragraphs. The first sentence is a crisp purpose statement, and the second paragraph efficiently enumerates the fields. There is no fluff; every sentence serves a distinct role in explaining the tool's 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?

For a simple list tool with 2 parameters and no output schema, the description covers purpose, row schema, ordering, limit behavior, and provides a fallback for complete data. It is sufficiently complete for an agent to invoke and interpret results without 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?

Schema coverage is 100% for both parameters. The description adds context beyond the schema by explaining that limit caps the output as a 'bounded sample' and exists for speed, which helps the agent reason about trade-offs. This is a modest but meaningful enhancement over 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 opens with 'List individual mutations in a gene', which is a specific verb+resource+scope statement that clearly differentiates from sibling tools like get_gene or search. It also details the exact row contents, making 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?

It clearly states this tool returns a bounded sample, and for a complete table of a heavily-mutated gene, directs users to the gene page on the website. While it doesn't name sibling tools like get_gene, the alternative for the full dataset is explicit, giving good when-to-use and when-not-to-use context.

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

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

With no annotations provided, the description carries the full burden. It transparently discloses that the tool only reads cached predictions, does not compute new ones, and returns cached=false with a note if nothing is cached. It also lists the return fields (best binding core, %Rank_EL, binder level, %Rank_Neo). This goes beyond simple schema information and sets correct 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 three concise sentences. The first sentence front-loads the core purpose, the second details the return values and behavior, and the third clarifies the limitation and alternative. Every sentence contributes valuable information with no redundancy or 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 lookup tool with two well-documented parameters and no output schema, the description covers the essential context: what the tool does, what it returns, its limitation (cached only), and the fallback behavior when no cache exists. It also provides an alternative for new predictions. This is complete for the tool's complexity.

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 with descriptions and examples for both parameters (allele and peptide). The description mentions the parameters but adds no new semantic detail beyond 'peptide + HLA allele'. Per the rubric, baseline 3 is appropriate when schema_coverage is high.

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: 'Look up a CACHED MHC-I binding prediction for a peptide + HLA allele.' It uses a specific verb ('look up'), identifies the resource (MHC-I binding prediction), and explicitly scopes to cached data. This clearly distinguishes it from siblings which are generic database/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?

The description provides explicit usage guidance: it notes that this tool does NOT run new predictions and only reads cached ones, and directs users to an alternative ('interactive button on the mutation page of the website') for generating new predictions. This is a clear when-to-use vs. when-not-to-use with an explicit 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?

The description discloses the output fields ('total mutations, unique samples, and unique genes') and ordering ('most-mutated first'), providing useful behavioral context. With no annotations, this helps the agent understand the return format. It doesn't address edge cases like empty results, but for a simple list tool this is acceptable.

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 primary action, and every sentence adds value. It is appropriately 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?

The tool is simple with one optional parameter, and the description explains what is returned and the ordering. Since there is no output schema, this return information is essential and provided. The use case is also given, making it contextually 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%: the single 'limit' parameter is fully described with type, default, and range. The description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description uses the specific verb 'List' with the resource 'cancer types (histology)' and specifies the ordering ('ranked by mutation burden'). It clearly differentiates from sibling tools like list_tissues by focusing on cancer types and mutation burden.

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 a clear use case: 'Use to see which cancer types dominate the database or to pick one for further drill-down on the website.' However, it does not mention alternatives or when not to use, falling short of explicit exclusions.

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

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

No annotations are provided, so the description carries the full burden. It describes the scope (COSMIC primary-tissue samples only), the output fields (total mutations, unique samples, unique genes), and the ordering (most-mutated first), which is helpful 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?

Two sentences: the first states the primary purpose, the second provides details and alternative guidance. No redundant phrases.

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 lacking an output schema, the description clearly details the return value structure and context. With one well-documented parameter and simple behavior, the description 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?

The schema description for `limit` is 100% sufficient ('Max tissues to return (1-100). Default 50.'), so the tool description adds no additional parameter guidance, which is acceptable.

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

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

States a clear verb+resource+ranking: 'List primary tissues ranked by mutation burden.' Distinguishes from sibling tools by explicitly excluding cell lines and directing to `search_cell_lines`.

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 for tissue-level questions; for cell lines use `search_cell_lines`,' which provides both when-to-use and an explicit 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?

No annotations are provided, so the description carries the full burden. It discloses the return format ({results: [{id, title, url}]}), the stable id convention, and the expectation to pass the id to 'fetch'. It does not cover pagination, errors, or authentication, but for a read-only search tool this is reasonably transparent.

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 core purpose and immediately followed by the return format and usage guidance. Every sentence contributes meaningful information 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?

The tool has one parameter, no output schema, and no annotations. The description covers the primary context: what it searches, what it returns, how to use the returned ids, and how it relates to sibling tools. It does not mention result limits or sorting, but these are not essential for a search tool description.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra parameter semantics beyond the schema; it merely restates that query is a free-text search string. It does not explain matching nuances like case sensitivity or wildcards.

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

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

The description clearly states the tool searches CAN-IMMUNE for genes and cell lines, a specific verb-resource combination. It also differentiates from siblings by noting it is the generic combined search endpoint versus the more specific search_genes and search_cell_lines 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 explicitly states when to use this tool ('generic search endpoint ChatGPT expects') and when to prefer alternatives ('MCP-native clients can also use the more specific search_genes / search_cell_lines tools'). This provides clear usage guidance and 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?

With no annotations provided, the description fully bears the transparency burden. It discloses return fields (tissue, cancer type, total mutations, etc.), ordering (by mutation count), scope limitation, and that it returns multiple matching entries. This gives the agent a complete behavioral model without needing to infer.

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 action, then returns and usage guidance. Every sentence adds value—no filler, no 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?

The tool has no output schema, so the description must convey what is returned. It enumerates all result fields, data sources, ordering, and scope, making it self-sufficient for correct invocation and interpretation of results. The usage guidance also positions it within the sibling tool family.

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 descriptions already cover 100% of parameters, including query matching rules and limit bounds. The description adds 'ranked by mutation burden' as context for the query but does not add new semantics beyond schema; it reinforces the ordering concept without introducing new parameter details.

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 starts with a specific verb 'Find' targeting 'cancer cell lines by name, ranked by mutation burden', clearly distinguishing it from sibling tools like search_genes (genes) and get_cell_line (specific entity).

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

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

Explicitly states 'Use before `get_cell_line` or `top_genes_in_cell_line`', providing clear context on when to use it relative to alternatives. Also clarifies scope ('only cell-line models, kept separate from primary tissue samples') and ordering, which implicitly guides when not to 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 discloses key behaviors: matching is partial and case-insensitive, results contain four specific fields, and ordering is by mutation count. It doesn't cover edge cases like empty results or authentication, but it provides a solid behavioral contract for a search tool.

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 well-organized sentences: purpose, matching/return details, and usage guidance. It is front-loaded and every clause adds value, without redundancy beyond reinforcing the schema.

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

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

For a simple 2-parameter search tool with no output schema, the description sufficiently explains return values and ordering. It also provides usage context and distinguishes from related tools, making it 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?

The input schema already provides 100% coverage for `query` and `limit`. The description adds context about result ranking and return fields, which helps interpret the query parameter, but doesn't introduce new parameter syntax. This earns a slight uplift from the baseline.

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 ('Find genes by symbol or full name') and adds the ranking criterion ('ranked by how mutated they are'). It also distinguishes itself from the sibling `get_gene` by positioning itself as a precursor ('before calling get_gene').

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

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

Explicitly states two use cases: locating a gene before `get_gene` and ranking genes by mutation burden. This gives clear guidance for when to choose this tool over the sibling tool. It names the alternative tool explicitly, which satisfies the 'alternatives' criterion.

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 behavioral burden. It discloses output ordering ('highest first'), the data source ('precomputed per-cell-line stats'), and performance ('fast'), which is meaningful. It does not mention error handling or exact return structure, but for a read-only query tool this is acceptable. The behavior is transparent enough 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 compact and front-loaded with the primary action. The first sentence states the core operation, the second gives example queries, and the third provides an alternative. Every sentence earns its place without 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?

For a simple tool with 2 well-documented parameters and no output schema, the description provides sufficient context: it clarifies what is returned (genes with mutation counts), the ordering, and the data source. It also points to the relevant sibling tool for broader needs. It could mention error cases, but overall it is complete enough for correct selection and 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%, so the baseline is 3. The description does not add additional parameter detail beyond what the schema already provides (e.g., exact name example and limit range are in the schema). It mentions 'cell line' generically but doesn't clarify the parameters further. Since the schema is thorough, this is adequate.

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+resource: 'Rank the most-mutated genes within one specific cell line.' It clearly states the function and provides example questions ('what is the top mutated gene in <cell line>') that anchor its purpose. It also distinguishes from sibling tool `get_cell_line` by noting it returns only top genes, not the whole profile.

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 explicit usage context: it answers specific question types and notes results come from 'precomputed per-cell-line stats (fast)' implying quick lookups. It also provides an explicit alternative: 'For the whole profile of the line use `get_cell_line` instead.' This is a clear when-to-use and when-not-to-use directive.

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