BioCosm

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

No annotations are provided, so the description carries full burden. It states the tool 'lists' items (implying read-only), but does not disclose pagination behavior, sorting, or whether results include full node details. The output schema covers return format, but behavioral traits like rate limits or data freshness are absent.

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 a single sentence with no wasted words. It efficiently conveys the core purpose. However, it is extremely minimal and could include additional context without becoming verbose.

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 rich input schema (100% coverage, 3 parameters) and presence of an output schema, the description is adequate. However, it lacks usage guidelines and behavioral transparency, which reduces completeness for an AI agent selecting 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?

Schema description coverage is 100%, so the baseline is 3. The description adds no meaning beyond the schema: 'at a specific clinical phase' echoes the phase parameter description. No extra context is provided for 'limit' or 'node_type'.

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 'List' and the resource 'drugs/diagnostics' with a specific filtering criterion ('at a specific clinical phase'). It distinguishes from sibling tools like 'find_by_target' or 'list_by_therapeutic_area' by specifying the phase focus.

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 filtering by clinical phase, but provides no explicit guidance on when to use this tool versus alternatives (e.g., 'find_by_target'), nor does it state when not to use it. No exclusions or prerequisites are mentioned.

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 does not disclose whether the operation is read-only, any rate limits, pagination behavior, or the maximum number of results (though the input schema indicates a limit parameter). This lack of transparency could lead to incorrect usage.

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 a single, concise sentence that front-loads the purpose. Every word is necessary, and there is no fluff 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?

The description covers the core purpose but lacks details on limits, sorting, or result format. While the output schema exists, the description could provide more context for effective use, especially given the number of sibling tools.

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

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

Schema description coverage is 100% (both parameters have descriptions). The tool description adds no new information beyond the schema. Per rule, baseline is 3 when 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 verb 'Find', the resource 'drugs', and the criterion 'target a specific gene/protein'. It is concise and distinct from sibling tools like 'find_by_phase' which filters by clinical phase.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it or suggest any alternatives, despite the presence of 13 sibling tools with overlapping functionality.

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 but only states that relationships are 'derived on-the-fly' and lists the types; it lacks details on side effects, error handling, rate limits, or performance implications.

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 a compact paragraph with a clear first sentence and well-organized bullet points for the three relationship types, with 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 the presence of an output schema and 100% parameter coverage, the description covers the core functionality and relationship semantics, though it omits behavioral details like pagination or error scenarios.

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

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

While schema coverage is 100%, the description adds value by explaining the meaning of each link_type value (e.g., 'drug_target: for a drug, the targets it hits'), going beyond the schema's terse 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 finds nodes connected to a given node and enumerates three specific relationship types, making its purpose distinct from sibling tools like find_by_phase or find_by_target.

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

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

The description implicitly guides usage by listing the three relationship types, but does not explicitly state when to avoid this tool or mention alternatives such as get_company_portfolio or search_nodes.

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 must disclose behavioral traits. It only states 'Get a company's full drug/diagnostic portfolio' but does not mention whether the operation is read-only, what data is returned (e.g., pipeline includes preclinical? approved?), or if any side effects occur. The lack of detail limits 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 a single, efficient sentence that gets straight to the point. However, it is so brief that it omits potentially useful context, which would not harm length. It earns a high score for lack of redundancy but could be slightly more informative without losing conciseness.

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

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

Given the tool's simplicity (one parameter, output schema exists), the description is minimally adequate. The output schema likely provides structure, but the description does not clarify the scope of 'full portfolio' (e.g., including diagnostics? all phases?). This ambiguity slightly lowers 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 description coverage is 100% (one parameter with a clear example). The tool description adds no extra meaning beyond the schema's own description of 'company_name.' Per the scoring rule, a baseline of 3 is appropriate when coverage is high and description doesn't enhance it.

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

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

The description clearly states the verb and resource: 'Get a company's full drug/diagnostic portfolio.' It is specific and distinct from sibling tools like 'find_by_phase' or 'find_by_target' which focus on more granular queries. The name also reinforces the purpose.

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

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

No guidance on when to use this tool vs alternatives (e.g., when to use 'search_nodes' or 'get_coverage'). The description lacks any context about prerequisites, exclusions, or typical use cases, leaving the agent to infer solely from the command name.

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 carry the behavioral transparency burden. It adds the caveat that BioCosm is AI-generated and may contain errors, but does not elaborate on the tool's behavior beyond reporting coverage, such as whether it is read-only or the scope of coverage.

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 extremely concise with two sentences. The first sentence delivers the purpose and benefit, and the second adds a necessary caveat. Every word earns its place, with no wasted 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?

The description is fairly complete given the tool's simplicity and the existence of an output schema. It explains the critical interpretation of coverage data, though it could be slightly more explicit about what the coverage report contains (e.g., per field or per node).

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

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

The tool has no parameters, and schema coverage is 100% (trivially). According to the rubric, the baseline for 0 parameters is 4, and the description adds no further parameter information since none are needed.

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: 'Report BioCosm's actual data coverage'. It uses a specific verb and resource, and distinguishes itself from sibling tools like get_node or get_stats by focusing on coverage rather than node content or statistics.

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 when to use the tool implicitly: 'so you never mistake missing data for a real-world zero'. This provides clear context on the tool's utility, but it does not explicitly state when not to use it or mention alternatives among siblings.

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 fully carries behavioral disclosure. It details all returned fields, notes sparsity of revenue data, explains that empty fields mean not in coverage rather than zero, and mentions source links and writeup availability. No destructive side effects implied.

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

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

The description is well-structured with a clear overview followed by a detailed list and a usage note. While slightly long, every sentence adds value and there is 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 the simple input (one parameter) and presence of an output schema, the description is complete. It explains what the tool returns in detail, leaving no obvious gaps for an agent to understand its functionality.

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 only parameter (node_id) is fully described in the schema with 100% coverage. The description adds context that the node is a 'single BioCosm node' but no extra syntax or semantics beyond the schema, warranting baseline 3.

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 full details for a single BioCosm node, listing specific data fields like aliases, classifications, revenue history, etc. It distinguishes from sibling tools by being comprehensive and node-specific.

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

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

The description implies usage for retrieving all details of a specific node, but does not explicitly state when to use versus alternatives like search_nodes or get_pos_score. The note about empty fields provides some guidance but lacks explicit when-to/not-to-use instructions.

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 must disclose behavioral traits. It lists output fields but does not mention read/write safety, authentication needs, rate limits, or behavior on invalid input (e.g., missing node). The output schema exists but the description adds no 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?

Single sentence, front-loaded with key purpose and output details. Every word is relevant and there is no wasted 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?

For a simple 1-param tool with output schema, the description is mostly adequate but lacks usage guidelines and behavioral transparency. Could be improved by specifying when to use this vs siblings and any side effects.

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 of 3. The description does not add additional meaning beyond what the schema provides; the schema already describes node_id with example 'pembrolizumab'. No enrichment.

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 action ('Get freshness details for a single node') and lists the specific fields returned (writeup age, enrichment hash match, staleness score, validation score). This distinguishes it from siblings like 'get_node' (node info) and 'get_staleness_report' (broader report).

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

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

No explicit guidance on when to use this tool versus alternatives. Usage is implied by the description, but there is no mention of exclusions or when to prefer it over similar tools like 'get_node' or 'get_coverage'.

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?

Without annotations, the description fully discloses the return value details (components of PoS) and the None case. It provides transparency about what the tool does beyond a simple read 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?

Two sentences, no redundant information. Every part adds value: first sentence states purpose and output contents, second covers the edge case.

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 single required parameter and existing output schema, the description covers the tool's behavior sufficiently. It could mention the expected node type, but it's adequate for 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% for node_id, and the description adds no additional semantic information about the parameter. The baseline of 3 is appropriate as the schema already describes the parameter.

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

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

The description clearly states the tool retrieves the Probability of Success estimate for a node, listing specific components (base rate, adjustment factors, etc.) and mentioning when it returns None. This distinguishes it from sibling tools like 'get_node' or 'get_writeup'.

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 notes that nodes without a PoS score return None, typically for early-stage drugs, implying when the tool is not useful. No explicit alternatives are given, 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 carries the full burden of behavioral disclosure. It mentions the output includes overall stats, top stale nodes, and data source freshness, but does not specify side effects, idempotency, or access requirements. The presence of an output schema partially compensates, making this minimal but 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 a single compact sentence with no redundancy. It efficiently conveys the tool's function and main outputs, earning its place without 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?

Given the low complexity (1 optional parameter, output schema exists), the description adequately covers the tool's purpose and output categories. However, it lacks any usage context relative to sibling tools, which slightly reduces 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?

The single parameter 'limit' is fully documented in the input schema with description and default. The description adds no additional semantics beyond that, so baseline 3 is appropriate given 100% schema coverage.

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

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

The description explicitly states the tool retrieves a writeup staleness report with overall stats, top stale nodes, and data source freshness. The verb 'Get' and resource 'writeup staleness report' are clear, and the scope is well-defined, distinguishing it from sibling tools like find_by_phase or get_node_freshness.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, conditions, or contrast with related tools such as get_stats, get_node_freshness, or find_related, leaving the agent to infer usage context.

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

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

While the description lists output contents, it lacks details on authorization, caching, or data freshness. Without annotations, more behavioral disclosure is expected.

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?

A single, information-dense sentence with no redundancy. The structure is efficient and front-loaded.

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

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

With zero parameters and an output schema present, the description adequately covers the tool's function and return data, leaving 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 exist, so the description does not need to add parameter meaning. Baseline 4 is appropriate.

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

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

The description clearly states it retrieves a 'high-level overview' listing specific data elements (total nodes, writeups, companies, etc.), distinguishing it from sibling tools that handle individual entities.

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

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

The description implies usage for aggregate overviews but does not explicitly state when to avoid this tool in favor of siblings like get_node or search_nodes.

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 carry behavioral disclosure. It does not mention any side effects, authentication needs, rate limits, or whether the operation is read-only. The read nature is implied but not explicit.

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 a single, well-structured sentence with no redundancy. Every word adds value, making it highly 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 the presence of an output schema and high schema coverage, the description is fairly complete. It explains what the tool returns but could mention prerequisites (e.g., existence of node) or error handling. Still very good.

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

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

Schema coverage is 100%, and the parameter 'node_id' is described in the schema. The tool description does not add additional meaning or usage tips beyond the schema, so it meets 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 clearly specifies the action ('Get') and the resource ('full writeup'), and details what is included (sections, citations, structured data, validation score). It effectively distinguishes from siblings like 'get_node' and 'get_pos_score' by focusing on the full writeup.

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 does not explicitly state when to use this tool versus alternatives like 'get_node' or 'search_nodes'. While it implies usage for obtaining the full writeup, it lacks explicit exclusions or comparative guidance.

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

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

The description implies a read operation ('list') but does not disclose any behavioral traits such as authentication requirements, rate limits, or pagination behavior. Since no annotations are provided, the description should carry this burden but falls short.

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 a single, clear sentence that front-loads the purpose. While concise, it could include more detail without being verbose, but it is not wasteful.

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 and the presence of an output schema, the description is minimally adequate. However, it lacks context about what 'nodes' are or how they relate to therapeutic areas, which could help an agent better understand the tool's role among many siblings.

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?

Input schema covers both parameters (area and limit) with descriptions and an example for area. Schema description coverage is 100%, so the description adds no value beyond the schema, yielding a baseline score of 3.

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 'List all nodes in a given therapeutic area', using a specific verb and resource, and distinguishes from sibling tools like find_by_phase and search_nodes.

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

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

No explicit guidance on when to use this tool versus alternatives. The description only mentions a therapeutic area parameter without indicating when not to use it or providing context for selection among siblings.

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 effectively discloses the ranking algorithm (exact matches first, then partial, with node-type priors) and confirms the presence of a 'name' field. It stops short of mentioning rate limits or authentication, but covers the most critical behavioral aspects.

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 clear paragraphs: the first states purpose, the second details ranking. Every sentence adds value, and there is no redundant or filler content.

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 presence of an output schema, the description covers all essential aspects: search scope, ranking behavior, and the existence of a 'name' field for disambiguation. No important gaps remain for a search tool of this 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?

Schema coverage is 100%, so the baseline is 3. The description adds concrete examples for the query parameter (e.g., 'breast cancer', 'pembrolizumab', 'Merck') and explains the fields searched, providing meaningful context beyond the schema's generic 'Search term'.

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 BioCosm nodes by multiple fields (name, gene symbol, target, therapeutic area, or company), matching a specific verb+resource pattern. It distinguishes itself from siblings like find_by_target by offering a broad, combined search.

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

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

No explicit guidance is provided about when to use this tool versus its siblings (find_by_target, find_by_phase, etc.). The description implies it's a general search but fails to state alternatives or when not to use it.

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