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, 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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that queries are NOT pre-cached and can take minutes, that broad queries can return over 50,000 connections, that results are ranked and paged, and that unrecognized dataset symbols are silently ignored. It also explains the summary's contents and advises on paging. This gives the agent critical expectations not derivable from the schema.

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

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

Though long, the description is densely informative and well-structured. It front-loads the purpose, then uses clear CONSTRAINTS, RECOMMENDED DEFAULTS, RESULT SIZE, and WORKFLOW sections. Every sentence adds unique value (e.g., result size caveat, paging behavior, relaxation sequence) and there is no redundant filler. The length is justified by the tool's complexity and the absence of annotations.

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 7-parameter query tool with no output schema, this description is exceptionally complete. It covers purpose, exclusions, parameter interplay, result expectations, paging semantics, dataset symbol validation, and relaxation troubleshooting. It even explains what the summary contains and advises 'Answer from the summary and quote a handful of rows.' No significant contextual gaps remain for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema: 'Set both upstream_type AND downstream_type to filter connections between two specific neuron classes,' 'At least one of upstream_type or downstream_type is required,' recommended defaults (weight=5, exclude_dbs=["hb","fafb"]), and guidance to use weight≥50 for both-ends queries to avoid timeouts. It also clarifies the practical effect of group_by_class, enriching the agent's parameter understanding.

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+scope: 'Query synaptic connectivity between Drosophila neuron classes across ALL connectome datasets simultaneously.' It clearly differentiates from sibling tools by explicitly stating it is NOT for single-neuron connections (use run_query) and NOT for muscle/sense organ connections. This makes the tool's purpose unambiguous and distinct.

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 when-to-use and when-not-to-use guidance, naming alternatives: 'use run_query with NeuronNeuronConnectivityQuery instead' for individual neurons, and 'use search_terms... to validate/canonicalize neuron type labels.' It also gives a full workflow (confirm with user, validate terms, relaxation steps) and specific recommendations for broad queries. This far exceeds the minimum and gives an agent clear decision rules.

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.