VirtualFlyBrain

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

With no annotations provided, the description carries the burden of disclosing behavior. It states that 'Descendants are returned as a nested tree for both relationship types' and 'Ancestors are returned as a nested chain, filtered to nervous system terms for part_of.' It also implies the default direction and depth behavior via 'Start with max_depth=1' and 'offer to go deeper.' These details go beyond the schema and help the agent anticipate the 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 concise and well-structured. It opens with the core action, then gives relationship guidance, describes return formats, and ends with a practical usage tip. Each sentence earns its place, and there is no filler. It is appropriately sized for the tool's 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?

Despite having no output schema, the description covers all key aspects: what the tool does, when to use each relationship, the shape of the returned data (tree vs. chain), and a recommendation for default depth. Combined with the detailed parameter descriptions in the schema, the agent has enough information to select and invoke the tool 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?

The schema already provides 100% coverage with descriptions for all 4 parameters, so the baseline is 3. The description adds meaningful context: it explains how 'relationship' maps to use cases (part_of for regions, subclass_of for cells), gives example IDs in the schema, and clarifies that direction and max_depth control the output structure. This enriches the parameter definitions 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's function: 'Build a hierarchy tree for a VFB term, showing ancestors (parents) and/or descendants (children).' It uses a specific verb ('Build') and resource ('hierarchy tree for a VFB term'), and it distinguishes itself from sibling tools by focusing on hierarchy exploration. It also includes concrete examples like 'what are the parts of the mushroom body?' which 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?

The description gives explicit guidance on when to use each relationship: '"part_of" for brain region structure' and '"subclass_of" for cell type hierarchies', with examples for each. It also advises starting with 'max_depth=1 for direct parents/children' and offering to go deeper. While it doesn't explicitly state when not to use this tool or name alternatives, the usage context is clear and actionable.

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

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

With no annotations provided, the description takes on full responsibility for behavioral disclosure. It explains that results come from ontology classification rather than per-instance predictions, explicitly states there is no confidence value, describes the exact output row shape, and covers the empty-result behavior. This is comprehensive transparency for a simple lookup 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 dense with useful information but not verbose; every sentence serves a purpose. It is front-loaded with the tool's core purpose, then proceeds logically to usage, output format, edge-case behavior, and constraints. There is 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?

Even without an output schema or annotations, the description fully explains what the tool returns, the shape of each row, the meaning of the neurotransmitter id space, and what happens in the empty case. Combined with the parameter documentation, it gives an agent everything needed to call the tool correctly and interpret its response.

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

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

The schema coverage is 100%, so the schema already documents the single parameter well, including examples and meaning of subclasses. The description adds extra value by clarifying that only neuron class terms are accepted and by recommending use of search_terms with specific filter_types for canonicalization. This goes beyond the schema's literal parameter definition.

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

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

The description clearly states a specific verb and resource: getting curated/known neurotransmitters for a Drosophila neuron class and its subclasses. It explicitly distinguishes itself from per-instance predictions and from the sibling get_predicted_neurotransmitters. An agent can immediately understand what this tool does and how it differs from similar 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 gives explicit when-to-use guidance: use it for curated/established answers to 'what neurotransmitter is <cell type> known to use?' It even tells the agent what to do when the result is empty, directing it to get_predicted_neurotransmitters. It also provides concrete constraints and canonicalization advice via search_terms, leaving no ambiguity about the intended workflow.

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 fully discloses the output format (flat per-class rows with counts, percent, mean_confidence; per-neuron rows if aggregate=false), the ability to split by dataset, the GO secretion term id space, and the effect of exclude_dbs. This is exemplary transparency for a query tool with no side 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 long but efficiently structured: purpose first, then when-to-use, then output variants, then constraints and recommendations. Every sentence adds distinct value with no fluff. The use of section markers (CONSTRAINTS, RECOMMENDED) improves scannability for an agent.

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 5 parameters, no output schema, and no annotations, the description provides all necessary information: output formats, parameter effects, id-space alignment with a sibling tool, constraints, and recommended defaults. An agent can confidently invoke it correctly without additional lookups.

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?

Although schema coverage is 100%, the description adds meaning beyond the schema: it explains why aggregate=false returns per-neuron rows, why split_by_dataset=true reveals cross-connectome agreement, how min_confidence filters predictions, and the rationale for the default exclude_dbs. This contextualizes each parameter's purpose, exceeding the schema's bare 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 states a specific verb ('Get'), a precise resource ('PREDICTED neurotransmitter(s) for a Drosophila neuron class — itself or any subclass'), and the data source ('per-instance connectome predictions'). It explicitly differentiates from its sibling get_known_neurotransmitters by contrasting data-driven predictions with ontology-curated classifications.

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 context: 'Use this for "what neurotransmitter does <cell type> use?" when you want the data-driven prediction and its confidence.' It also names the alternative (get_known_neurotransmitters) and explains the distinction. Constraints (neuron class terms only, canonicalization via search_terms) and a recommended default (exclude_dbs) further guide 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?

With no annotations, the description carries the full burden. It discloses the response structure (SuperTypes, Tags, Queries, RelatedTools, Images, Publications, Synonyms), batch behavior (results keyed by ID), and even URL construction for the 3D viewer. It doesn't explicitly state read-only semantics or error behavior, but the 'get' verb and the detailed output description provide a strong behavioral picture.

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

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

The description is lengthy but every sentence earns its place: it covers the core purpose, the critical workflow (ALWAYS call first), batch behavior, return fields, related tools, and URL template. It is front-loaded with the purpose and the most actionable guidance, and the details are structured clearly.

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 central role in a multi-tool workflow and the absence of an output schema, the description is remarkably complete. It explains what the Queries field is for, how to use RelatedTools, how to interpret Images for building URLs, and that batch results are keyed by ID. It provides all necessary context for correct selection and invocation, even without an output schema.

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, but the description adds value beyond the schema by explaining the batch mode in detail (array of IDs returns a JSON object keyed by ID) and providing examples of ID formats. It also clarifies that the Queries field is what run_query accepts, which helps understand the tool's role. The force_refresh parameter is already well-explained in the schema, and the description reinforces it without redundancy.

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 and resource ('Get term info for a VFB or anatomy ontology entity') and immediately clarifies its role as 'THE QUERY DISCOVERY TOOL', which distinguishes it from siblings like run_query and get_hierarchy. It also mentions the ID patterns (VFB_*, FBbt_*) and the returned Queries array, leaving no ambiguity about what the tool does.

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 usage guidance is provided: 'ALWAYS call get_term_info before run_query unless you already obtained the query_type from a previous get_term_info call in this conversation.' It also explains the batch usage (pass an array of IDs) and when to use the force_refresh parameter (via schema, but the description reinforces the workflow). This clearly states when to use this tool and how it relates to run_query.

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. The 'list' verb correctly implies a read-only operation, and the description adds context about what the output contains (labels and symbols) and how it relates to exclude_dbs. It could have disclosed more about the response structure, but for a parameterless list tool this is adequate.

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

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

The description is three sentences, front-loaded with the purpose, followed by usage guidance and an example of common datasets. Every sentence adds value with no repetition 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 zero-parameter listing tool with no output schema, the description is complete. It states what the tool does, what it returns, how to use the results, and when to call it. The mention of common dataset symbols adds useful 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 zero parameters, so the baseline is 4. The description doesn't need to explain parameters, but it does mention that symbols are used in exclude_dbs arguments, which adds semantic context about the use of the tool's output.

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 available connectome datasets with their labels and symbols', which is a specific verb (list) and resource (connectome datasets). This distinguishes it from sibling tools like query_connectivity, resolve_entity, and search_terms, which perform different operations.

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

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

The description provides explicit guidance: 'Use the returned symbols when constructing exclude_dbs arguments for query_connectivity' and 'Call this tool if unsure which dataset symbols are valid.' This tells the agent exactly when and how to use the tool relative to its sibling query_connectivity.

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?

Even with no annotations, the description discloses key behavior: the list is dynamic ('change as data is added'), derived from the index's own annotations, and includes counts that indicate breadth (e.g., 'entity covers everything, a single lineage covers a handful'). It also clarifies that contains matching is case- and separator-insensitive, reinforcing the schema's explanation.

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-load the purpose, then provide contextual guidance and parameter examples. No wasted words; each sentence contributes meaningfully.

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 one-optional-param list tool, the description covers what it returns (type names with counts), the dynamic nature, and how to narrow results. While it doesn't specify an exact output schema, the description is sufficient for effective use, though it could mention whether results are sorted or paginated.

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 already covers the 'contains' parameter with a clear description and matching rule. The description adds concrete usage examples (e.g., contains='lineage' for ~120 lineage clones, contains='connectivity' for connectome facets) and explains how counts relate to the breadth of the name, enriching 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 opening sentence clearly states the function: 'List the type names search_terms can filter, exclude, boost or demote by, with the number of terms carrying each one.' This identifies both the action and the resource, distinguishing it from sibling tools like get_term_info or run_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?

The description advises 'Call this instead of guessing,' explaining that there are over 200 names, they are index annotations rather than a curated list, and they change as data is added. This sets clear expectations for when to invoke the tool—before using search_terms with filters—though it doesn't name alternative tools.

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?

There are no annotations, so the description carries the full behavioral burden, and it does so thoroughly. It discloses live-query latency, enormous result sizes, strongest-first ranking and paging, summary semantics, silent ignoring of unrecognized exclude_dbs symbols, and the non-additive behavior of group_by_class. This gives an agent accurate expectations before invoking.

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 long but densely informative and organized with clear labels (CONSTRAINTS, RECOMMENDED DEFAULTS, RESULT SIZE, WORKFLOW). It repeats a few points already present in the schema, such as recommended defaults and anatomical-region restrictions, but given the tool's complexity and failure modes, the length is mostly justified and critical warnings are 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?

Despite having no output schema, the description covers return shape, summary fields, ranking, paging discipline, group_by_class semantics, user-confirmation workflow, validation, and result-relaxation strategies. It also clarifies how an agent should answer from the summary rather than blindly paging. For a 7-parameter live-query tool with no annotations, nothing essential is missing.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema: recommended defaults, OWL ID/label requirements, the need to validate labels via search_terms, exact dataset symbols and the silent-ignore pitfall, limit behavior with 0, and step-by-step relaxation guidance. These additions materially improve parameter selection.

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 states a precise verb, resource, and scope: 'Query synaptic connectivity between Drosophila neuron classes across ALL connectome datasets simultaneously.' It also differentiates this tool from siblings by warning 'This is NOT pre-cached' and explicitly pointing to run_query for individual neuron-neuron connections, so an agent can select it correctly without guessing.

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?

Usage is explicitly specified: at least one of upstream_type/downstream_type is required, both should be set for a directed pair query, anatomical regions are invalid, and individual-neuron queries should go to run_query. It also gives a concrete workflow: confirm parameters, canonicalize labels with search_terms, apply recommended defaults, and follow a relaxation sequence when zero results appear.

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 to rely on, the description fully discloses the tiered resolution process (exact name → synonym → broad pattern match), the confirmation requirement for synonym matches, disambiguation for multiple matches, and the return fields. This is rich behavioral detail beyond simple function naming.

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 logically structured from purpose to input rules to behavior to edge cases, and is appropriately detailed. The quoted confirmation prompt is illustrative but not excessive, making it a solid, well-organized description.

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 enumerates all returned fields (FBco ID, combination name, matched synonym, component allele IDs/names) and explicitly handles the two key edge cases (synonym confirmation and multiple matches). For a tool with a single parameter, this is comprehensively sufficient.

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 already describes the 'name' parameter with 100% coverage, including the exact instructions to pass raw text and avoid FBco IDs. The description merely repeats these instructions without adding new semantic nuance, so the baseline score 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 clearly states the tool resolves split-GAL4 combination names or synonyms into FBco IDs and hemidrivers, with a specific verb and resource. It distinguishes from general resolver tools like resolve_entity by focusing on the split-GAL4 domain and explicitly excluding FBco IDs as input.

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 when-to-use guidance (unresolved combination text) and a clear exclusion: do not pass an FBco ID, use the downstream tool directly instead. While no alternative sibling tool is named, the directive is unambiguous.

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 tiered resolution process (exact name → synonym → broad pattern match), return fields, and confirmation requirements for SYNONYM/BROAD matches, including disambiguation steps. While not covering rate limits or error cases, it does provide substantial behavioral context beyond the schema (which has no 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?

Every sentence adds value: it covers purpose, usage rules, examples, resolution logic, confirmation steps, and sibling differentiation without redundancy. The structure flows logically from what to pass, to how resolution works, to what to do with results.

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 no output schema and no annotations, the description is comprehensive: it explains the input format, resolution behavior, potential match types, user confirmation rules, and the difference from sibling tools. An agent would know exactly when and how to use it, and what to expect.

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 description enriches the parameter definition with multiple concrete examples and explicit negative constraints (do not pass resolved IDs). It also explains how the parameter value affects resolution behavior (tiered matching), adding meaning 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 a specific verb and resource: 'Resolve an unresolved FlyBase-related query string into VFB/FlyBase IDs and metadata.' It distinguishes from siblings by explicitly directing VFB ontology lookups to search_terms instead.

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 gives explicit when-to-use guidance: pass raw text exactly as written, do NOT pass resolved IDs, and use downstream tools if an ID is already available. It also names the alternative tool (search_terms) for different query types.

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 of behavioral disclosure, and it excels: it explains paging (first 25 rows, limit/offset, total count), the meaning of count_status ('exact' vs 'unavailable'), that empty results do NOT mean unknown, the cache-bypass semantics of force_refresh, and that images are stripped by default. It also warns against fabricating answers when queries are empty. This is far beyond baseline 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 long, but every sentence earns its place given the tool's complexity. It is front-loaded with the required workflow and then covers edge cases. However, it is presented as a single dense paragraph; structuring it with sections or bullet lists would improve scannability. Minor structural inefficiency, hence 4.

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 complex tool with 7 parameters, no output schema, and no annotations, the description is remarkably complete. It covers batching, paging, error semantics, caching, image handling, FlyBase integration, and links to related workflow steps (get_term_info, resolve_entity). An agent has everything it needs to select and invoke this tool correctly in varied situations.

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?

Although the schema covers all parameters (100% coverage), the description adds substantial meaning: it explains how id can be a single ID or array, how queries works for mixed batches, how limit and offset interact with paging, when force_refresh should be used, and why include_images defaults to false. It also provides real query_type examples by entity kind. This goes well beyond the schema's 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 opens with a specific verb+resource: 'Run a pre-computed query on a VFB entity.' It clearly distinguishes itself from sibling tools by warning not to pass tool names like get_term_info or search_terms as query_type, and by describing batch and FlyBase-specific usages. This leaves no ambiguity about what the tool does.

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 an explicit REQUIRED WORKFLOW: call get_term_info first, read the Queries array, then pass one of those values. It also provides alternatives ('try a related entity via get_hierarchy'), exclusion criteria ('NEVER pass tool names'), and context for when to use batches or FlyBase query types. This is exemplary when-to-use guidance.

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

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

With no annotations provided, the description carries the full burden and delivers richly: it discloses that deprecated terms are pre-excluded, that filter_types are ANDed while exclude_types are ORed, that boost/demote re-order without excluding, and that unique=false repeats IDs per matching synonym. It also explains exact-match behavior for auto_fetch_term_info and error handling for unknown type names. This is exemplary 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 long but impeccably structured and front-loaded. It opens with the core purpose, then moves through defaults, recipes, constraints, and flags, with each sentence adding unique value. No redundancy or fluff exists; the density is justified by the tool's 10-parameter complexity and domain-specific semantics.

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, absence of annotations, and lack of output schema, this description is exceptionally complete. It covers usage defaults, parameter interactions, edge cases (deprecated, unknown types, no matches), and even contextualizes the tool within the larger VFB ecosystem. The only minor gap is lack of example invocations, but the explicit recipes and flag explanations render this unnecessary.

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?

Although the schema covers 100% of parameters, the description adds substantial semantic depth: it explains the AND/OR logic for filter/exclude types, when to disable unique, the trade-offs of minimize_results, and provides concrete recipes for boost_types/demote_types. It even clarifies that adding exclude_types:['deprecated'] is harmless but pointless. This far exceeds baseline 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 opens with a clear verb+resource ('Search VFB terms') and immediately distinguishes the tool from siblings by stating it uses the same Solr query and ranking as the VFB site itself. It contrasts with list_search_facets (vocabulary listing) and get_term_info (exact-match info fetch), making the tool's unique role explicit.

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, actionable guidance: 'USE filter_types BY DEFAULT', common filter recipes, instructions to call list_search_facets rather than guessing type names, stage-filtering rules, and a clear fallback strategy (try alternatives, not training-data). This goes well beyond typical tool descriptions and directly supports correct agent selection and invocation.

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