Catalogueoflife

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

Discloses that it routes to subtools, fills arguments, and returns stable citation URIs, adding context beyond annotations (readOnlyHint, openWorldHint). Does not mention failure modes or ambiguity handling, but overall provides useful 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?

Well-structured with a strong opening directive, followed by domain list, mechanism, and concrete examples. Every sentence adds value without redundancy. Front-loaded with crucial guidance.

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 parameter, annotations, and no output schema, the description covers purpose, usage, and output format. Lacks details on error behavior or output interpretation, but is sufficient for the tool's expected use case.

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?

Only one parameter 'question' described in schema as 'Your question or request in natural language'. Description reinforces this but does not add significant new semantics beyond schema. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

Explicitly states it routes natural language questions to 1,423+ tools across 392+ sources, returning structured answers with citations. Clearly distinguishes itself from web search and lists specific domains. Provides examples of when to 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?

Explicitly says 'PREFER OVER WEB SEARCH' and gives detailed usage instructions: use for factual questions about real-world entities, events, numbers, etc., with example phrasings. Contrasts with alternatives and provides concrete use cases.

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

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

Annotations already indicate read-only, open-world, and non-destructive behavior. The description adds that the tool returns direct children, but does not disclose pagination or result format beyond the schema. No contradiction with annotations.

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

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

Extremely concise at three words, but the brevity sacrifices necessary detail. It is front-loaded but under-specified for a tool with three parameters.

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?

No output schema, so description should explain return values. The description does not cover expected results, pagination, or error behavior. Incomplete for a query tool with multiple parameters.

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 low (33%); only 'limit' has a description. The tool description adds no meaning for 'id' or 'dataset', which remain undocumented. Parameter semantics are insufficient for an agent to understand usage.

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

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

Description clearly states the tool returns direct child taxa, which is a specific verb+resource. However, it does not explicitly distinguish from siblings like 'classification' or 'taxon', but the phrase 'direct child taxa' implies a hierarchy query.

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 versus alternatives such as 'classification' or 'taxon'. The description lacks any context about prerequisites or situations where this tool is appropriate.

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

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

Annotations already mark the tool as read-only and non-destructive. The description adds that the output is a chain from kingdom to species, which is useful context beyond annotations. However, it does not disclose behavior for missing IDs, error handling, or any restrictions (e.g., dataset parameter effects).

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 fronts the core purpose. While it lacks structure (e.g., bullet points), it is efficient and avoids fluff. Minor improvement could be adding a brief note on the dataset parameter.

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

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

Given the tool has two parameters and no output schema, the description partially explains the return format (a chain). However, it does not specify the representation (array, object, etc.), error behavior, or optional dataset usage. This leaves gaps for an agent to correctly interpret the output.

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

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

With 0% schema description coverage, the description should clarify parameters. It only mentions 'taxon id' for the required 'id' parameter, but ignores the optional 'dataset' parameter entirely. No additional meaning is provided beyond the schema field names, leaving the agent uninformed about the dataset parameter's role.

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: 'Taxonomic classification chain (kingdom → species) for a taxon id.' It uses a specific verb ('classification chain') and resource ('taxon id'), and the output hierarchy is explicit, distinguishing it from siblings like 'taxon' (single entity details) and 'children' (immediate descendants).

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 the tool is for retrieving the full lineage for a given taxon id, but it does not explicitly state when to use this over siblings like 'taxon' or 'children'. No exclusions or alternatives are mentioned, leaving the agent to infer usage context from the tool name and description.

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

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

Annotations already indicate read-only, open-world, non-destructive. The description adds valuable behavioral context: it returns paired data and citation URIs, and replaces 8-15 sequential calls. It does not mention limitations or prerequisites, but the annotations cover safety.

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 long but every sentence adds value. It is front-loaded with the main purpose. A minor improvement would be to shorten the list of examples, but it's still concise for the complexity.

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

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

Given the tool's complexity (two modes, multiple data sources) and the absence of an output schema, the description comprehensively explains what is returned for each type and includes output format details. It also mentions the efficiency gain, making it complete for agent decision-making.

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 with descriptions, but the tool description adds significant meaning: for 'type', it specifies what data is pulled (revenue, net income, etc. for company; adverse events, approvals, trials for drug). For 'values', it provides examples and clarifies min/max items. This substantially 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 the tool compares 2-5 companies or drugs side by side, with specific examples of user phrases that trigger it. It distinguishes itself from siblings by focusing on comparison and listing two distinct entity types.

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 (user says 'compare X and Y', 'X vs Y', etc., or wants tables/rankings). It also provides context for each type (financials for companies, adverse events for drugs). It does not explicitly mention when not to use, but the guidance is clear enough.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it 'Returns the top-N most relevant tools with names + descriptions,' which is transparent about the output. No contradictions; the description appropriately amplifies the safe read-only nature.

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

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

The description is front-loaded with the core purpose and includes a helpful list of example domains. It is not overly verbose at 97 words, though the list could be slightly trimmed. Still, it remains clear and actionable.

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

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

Given no output schema, the description covers the return value sufficiently by stating it returns top-N tools with names and descriptions. The context of many sibling tools and the meta-search purpose is well-addressed. Some agents might want more detail on output structure, but it's adequate.

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 both parameters (query, limit) are well-described in the schema. The description provides example queries but adds no structural or format details beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states that discover_tools finds tools based on a natural language query about data or tasks. It lists many example domains and explicitly contrasts with direct tool use, distinguishing it from sibling tools like search or entity_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 when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and advises to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly differentiates from direct tool invocation.

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

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

Adds context beyond annotations: lists returned data types (SEC filings, fundamentals, patents, news, LEI) and citation format. Annotations already declare safe read and open world; description enriches with specific behavioral details.

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 compact paragraphs: purpose/usage, then return list and input details. Every sentence adds value with no redundancy.

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

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

Given no output schema, description fully explains return content. Covers when to use, what to pass, and what to expect. No gaps for a complex aggregation 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%, but description adds examples ('AAPL'), clarification ('zero-padded CIK'), and limitation ('names not supported'). Provides practical guidance not in 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?

Starts with 'Get everything about a company in one call,' clearly stating verb and resource. Distinguishes from siblings by emphasizing aggregation of multiple data types.

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

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

Provides explicit use cases ('tell me about X', 'give me a profile') and alternatives ('10+ pack tools'). Directs to 'resolve_entity' when only name is available, guiding correct invocation.

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

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

Annotations already mark destructiveHint=true. Description adds context about clearing sensitive data, which goes beyond annotations.

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

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

Three sentences, each valuable. Front-loaded with action. No superfluous 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?

For a simple delete tool with one param and annotations, the description covers purpose, usage, and security context. No output schema needed.

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?

Only one parameter 'key' with full schema description. Description adds no extra info beyond schema.

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

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

Clearly states 'Delete a previously stored memory by key' – specific verb and resource, and distinguishes from siblings like 'remember' and 'recall'.

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 when to use: when context is stale, task done, or clearing sensitive data. Also mentions pairing with 'remember' and 'recall'.

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

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

Annotations indicate readOnly, openWorld, and non-destructive. The description adds that it returns 0 or 1 hit plus alternatives, which provides useful behavioral context beyond the annotations.

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

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

The description is very short (6 words) and front-loaded with purpose, but it is overly terse. While no words are wasted, it omits important details that could be included without harming conciseness.

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

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

For a simple exact-match tool with no output schema, the description mostly suffices. However, it lacks parameter elaboration, which affects completeness given the low schema coverage.

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 3 parameters with only 33% description coverage (only authorship described). The tool description does not explain the other parameters (e.g., format of scientific_name, dataset), failing to compensate for the low schema coverage.

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

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

The description clearly states the tool does an exact match of a scientific name, returning at most one hit plus alternatives. This distinguishes it from broader sibling tools like 'search' or 'resolve_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?

The description implies usage for exact name matching but does not explicitly state when to avoid it or mention alternatives. The context of sibling tools helps, but direct guidance is missing.

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 behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and that the team reads digests daily. The annotations (readOnlyHint: false, etc.) are not contradicted; the description adds useful context about how feedback is processed and its impact on the roadmap.

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 paragraph but efficiently packs information: purpose, usage guidelines, behavioral notes, and constraints. It front-loads the core action and then provides details. While slightly lengthy, every sentence serves a purpose. A slightly more structured breakdown could improve clarity, but it remains concise for the amount of information conveyed.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description is fully complete. It covers the purpose, when to use each type, what to include in the message, and behavioral limits. An agent has all necessary information to invoke the tool correctly without additional context.

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

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

The input schema has 100% description coverage, so the description adds value by explaining the enum values in context (e.g., 'bug = something broke or returned wrong data') and reinforcing the message constraint (1-2 sentences, 2000 chars max). It also clarifies the optional context object fields. This justifies a score above the baseline 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 the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists specific categories (bug, feature, data_gap, praise) that map to the 'type' enum, making the intent unambiguous. The tool is distinct from its siblings, which are for querying, searching, or managing data, not for providing feedback.

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

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

The description provides explicit guidance on when to use each feedback type: bug for wrong/stale data, feature/data_gap for missing tools or data, praise for positive notes. It also tells the agent what to include (describe in terms of Pipeworx tools/packs) and what to avoid (don't paste the end-user's prompt). The rate limit and quota exemption are clearly stated.

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

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

Annotations already declare readOnlyHint=true. Description adds scoping and listing-all behavior. No contradictions.

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

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

Three concise sentences, front-loaded with action, 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?

For a simple retrieval tool with no output schema, description covers return behavior, scoping, and relationship to siblings. Complete enough for agent use.

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

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

Schema covers the 'key' parameter description. Description adds behavior of omitting key to list all, exceeding schema info.

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?

Clearly states it retrieves a value saved via remember or lists all keys if key is omitted. Differentiates from remember and forget siblings.

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 when to use (look up context stored earlier) and mentions scoping. Lacks explicit when-not-to-use but adequately guides usage.

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

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

Annotations provide readOnlyHint, openWorldHint, and destructiveHint. The description adds value by explaining the parallel fan-out to three sources and the output structure (structured changes, total_changes count, citation URIs). This goes beyond the annotations, though the description repeats some schema details.

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 at 4 sentences, front-loaded with purpose, then usage examples, then technical details. Every sentence adds value without redundancy. Perfectly structured for quick comprehension.

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

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

Given the tool's complexity (multiple sources, no output schema), the description covers purpose, input parameters, and output structure. It lacks details on pagination or rate limits, but for most use cases it is sufficiently complete.

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

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

Schema description coverage is 100%, so the schema already documents all parameters well. The description adds minimal new semantic information beyond examples for the 'since' parameter (e.g., '30d' or '1m'). 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's purpose: retrieving recent changes about a company. It provides specific example queries ('what's happening with X?', 'any updates on Y?') and lists the data sources (SEC EDGAR, GDELT, USPTO). This effectively differentiates it from sibling tools like 'entity_profile' or '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?

The description explicitly tells when to use the tool with concrete user intents and example queries. However, it does not specify when not to use it or compare directly with sibling tools, which would strengthen 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?

Beyond annotations, description discloses key-value scoping by identifier and persistence differences (authenticated vs anonymous with 24-hour retention), which annotations don't cover.

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

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

Multi-sentence but efficient, each sentence adds unique value; slight wordiness could be trimmed but still 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?

Covers purpose, usage, and behavior well; lacks mention of return value or confirmation for write operations, but sufficient for the tool's simplicity.

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?

Adds semantic context to both key (examples like 'subject_property') and value ('findings, addresses, preferences') beyond schema, which already has 100% 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?

Clear verb-resource pair ('save data') with specific examples (ticker, address, preference) and explicit linking to siblings recall/forget, distinguishing 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?

Explicitly states 'when you discover something worth carrying forward' and pairs with recall/forget for complementary operations, providing clear usage context.

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

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

Annotations already indicate read-only, non-destructive, open-world. Description adds that returns IDs plus pipeworx:// citation URIs, providing useful return format information beyond annotations.

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

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

Multiple sentences but each sentence serves a purpose: purpose, examples, usage guidance, replacement note. Front-loaded with core action, structured logically without redundancy.

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

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

For a tool with two parameters and no output schema, description covers expected return format (IDs + citation URIs) and typical use cases sufficiently. No missing critical information.

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

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

Input schema already has detailed descriptions for both parameters (e.g., value can be ticker/CIK/name). Description adds concrete examples ('Apple'→AAPL/CIK, 'Ozempic'→RxCUI) that clarify mapping and ID systems, adding value beyond schema.

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

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

Clearly states lookup of canonical IDs for companies and drugs. Distinguished from sibling tools by positioning as prerequisite and mentioning replacement of multiple lookup calls.

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 tells when to use: 'Use this BEFORE calling other tools that need official identifiers.' Also implies alternatives by noting it replaces 2-3 lookup calls, guiding agents away from redundant calls.

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

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

Annotations already indicate read-only, open-world behavior. The description adds no further behavioral context, such as pagination, rate limits, or what happens on empty results, providing minimal added value.

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

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

Extremely concise at two words, but this sacrifices informative content. It is not appropriately sized for a tool with six parameters and multiple siblings.

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

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

For a tool with six parameters and no output schema, the description is incomplete. It fails to explain return values, default behaviors, or how to effectively use filters, leaving the agent underinformed.

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

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

With 83% schema coverage, the input schema already describes parameters well. The description adds no additional meaning, so baseline score 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 'Name-usage search' is vague and does not clearly specify what the tool searches (names, usages, or both). It fails to distinguish from siblings like 'name_match' or 'resolve_entity', providing no unique identifier.

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 is provided on when to use this tool versus alternatives, nor does it offer context, prerequisites, or exclusion criteria. The agent is left without strategic direction.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. Description adds no behavioral details (e.g., return format, pagination). No contradiction with annotations.

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

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

Extremely short phrase, but could be more informative without sacrificing brevity. Not verbose, but underspecified.

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 is simple but description omits information about the optional 'dataset' parameter and return structure. Incomplete for an agent to use effectively.

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 0% and description provides no explanation for parameters 'id' or 'dataset'. The agent gets no help understanding what values are expected.

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 mentions resource ('synonyms') and target ('a taxon') but is a noun phrase rather than a verb statement. It distinguishes from siblings like 'taxon' and 'classification' at a basic level.

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 such as 'taxon' or 'classification'. Missing context about input prerequisites or typical use cases.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, destructiveHint=false, covering the safety profile. The description adds no additional behavioral context (e.g., response structure, pagination, or permissions). With annotations present, a score of 3 is appropriate as the description does not contradict and provides minimal extra value.

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

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

The description is extremely concise with one sentence. While this is efficient, it lacks structure and could benefit from additional context. It is not overly verbose, but the minimalism borders on under-specification.

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

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

Given the tool has two parameters and no output schema, the description should provide more context about usage and return values. It does not explain what the output contains (e.g., full taxon details, hierarchy). Sibling tools exist but no comparison is made. The description is incomplete for effective agent selection.

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 0%, placing the burden on the description to explain parameters. The description only mentions 'by id' but does not detail the 'id' parameter's format or the purpose of the 'dataset' parameter. No added meaning beyond the schema itself.

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 'Taxon by id.' clearly indicates the tool retrieves a taxon resource using an ID. However, it is minimal and does not elaborate on what a taxon is or how this differs from sibling tools like 'children' or 'classification'. It is adequate but lacks specificity.

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 is provided on when to use this tool versus alternatives. For example, there is no mention that this is for exact ID lookup while 'name_match' is for fuzzy matching. The agent is left without context on selection criteria.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description does not need to restate that. However, it adds no additional behavioral details (e.g., authentication requirements, rate limits, or idempotency). The description is neutral and does not contradict annotations.

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

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

The description is very short (4 words), which is concise but at the cost of clarity. It is front-loaded with the key action, but more information could be added 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 there is no output schema, the description should indicate what the tool returns (e.g., a single object, a list, or specific fields). It fails to specify expected output or how it fits into the broader context of sibling tools. The description feels incomplete.

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 0%, meaning the description must compensate. It only mentions 'id' implicitly but does not explain the 'dataset' parameter. No details are provided about parameter formats, semantic meanings, or relationships, leaving the agent with minimal 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 'Single name-usage by id.' identifies the tool as retrieving a name usage by ID, but it is vague and does not clarify what a name-usage is or how it differs from sibling tools like 'entity_profile' or 'classification'. A more specific verb and resource context would improve clarity.

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?

There is no guidance on when to use this tool versus alternatives like 'search' or 'taxon'. The description does not provide any usage context, such as typical use cases or prerequisites.

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

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

Beyond annotations (readOnly, openWorld, non-destructive), the description discloses return types (verdict, structured form, actual value with citation, percent delta) and limitations (v1 supports only company-financial claims). This adds significant behavioral context.

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

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

The description is substantive but not overly verbose; each sentence contributes to understanding purpose, usage, scope, and output. Minor redundancy could be trimmed.

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

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

Given the single required parameter and no output schema, the description adequately covers verdict types, scope, and efficiency. It could mention if non-financial claims are handled or what 'approximately_correct' means.

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

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

With 100% schema description coverage, the schema already documents the 'claim' parameter. The description adds concrete examples of natural-language claims, enhancing clarity.

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 fact-checks natural-language claims against authoritative sources, with a specific focus on company-financial claims. It does not explicitly differentiate from sibling tools but mentions it replaces 4-6 sequential calls, which provides context.

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 cues, such as when an agent needs to verify a user's claim, and includes example prompts. However, it lacks when-not-to-use guidance or alternatives.

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

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

Annotations already declare readOnlyHint=true, indicating a safe read operation. Description adds minimal behavioral context beyond that; does not mention return format, pagination, or error cases. No contradiction with annotations.

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

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

Description is a single short sentence, but it is under-specified rather than efficiently complete. It could be expanded with useful details 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 tool has two parameters, no output schema, and no parameter descriptions, the description is insufficient. It does not clarify expected input values or what the output represents (list of names, objects, etc.).

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 0%. Description does not explain the meaning or expected format of 'id' (likely a taxon identifier) or 'dataset' (possibly a names source). Fails to compensate for the lack of schema documentation.

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 states resource ('vernacular names') and target ('for a taxon'), but lacks a verb (e.g., 'get', 'retrieve'), making action unclear. It does not differentiate from sibling tools like 'synonyms' or 'taxon' that also return name-related data.

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 versus alternatives (e.g., 'synonyms', 'classification'). No exclusions or context provided.

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