Skip to main content
Glama

VirtualFlyBrain

by org.virtualflybrain

run_query

Run a pre-computed query on a VFB entity. REQUIRED WORKFLOW: (1) call get_term_info on the ID first; (2) read the response's "Queries" array; (3) pass one of those values as query_type. Calling run_query with a guessed query_type will return an error. If a query returns empty rows or an error, the entity does not support that query_type or has no data for it — try a different query_type from the Queries array, or try a related entity (e.g. its parent class via get_hierarchy). Empty results do NOT mean the answer is unknown — only that this call did not return it. NEVER fabricate results from training data when a query is empty; tell the user clearly what was tried. NEVER pass tool names like "get_term_info" or "search_terms" as query_type — those are separate tools. Common query_types by entity kind: PaintedDomains, AllAlignedImages, AlignedDatasets, AllDatasets (templates); SimilarMorphologyTo, NeuronInputsTo, NeuronNeuronConnectivityQuery, NeuronRegionConnectivityQuery (individual neurons); ListAllAvailableImages, SubclassesOf, PartsOf, NeuronsPartHere, NeuronsSynaptic, ExpressionOverlapsHere, DownstreamClassConnectivity, UpstreamClassConnectivity (classes). Supports batch — pass an array of IDs (same query_type) or a "queries" array of {id, query_type} pairs; batch results are keyed by "ID::query_type". Results are PAGED: the first 25 rows by default (change with limit/offset) plus the true total as "count". ALWAYS read "count_status" before quoting "count": "exact" means count is the true total; "unavailable" means the query FAILED upstream and count is -1, which is NOT zero and must never be reported as "no results" — read "_note" and tell the user the query could not be run. Image/thumbnail columns are excluded by default to save space - pass include_images=true to include them. FlyBase integration is via query_types too: FindStocks (fly stocks for a FlyBase feature ID - FBgn/FBal/FBti/FBtp/FBco/FBst) and FindComboPublications (publications for an FBco split-GAL4 combination). Get those IDs from resolve_entity / resolve_combination first, then run_query with the ID and the query_type. Include FlyBase links in output: https://flybase.org/reports/{ID}.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idNoOne or more VFB IDs to query
limitNoMax rows returned per call (default 25). The true total is always returned as "count"; broad queries (e.g. ListAllAvailableImages, or NeuronsSynaptic on a whole region) can have thousands to hundreds of thousands of rows. Use 0 for all rows (still capped server-side ~25000 - avoid for broad queries).
offsetNoRow offset for paging (default 0). To get the next page, re-run with offset increased by limit; "count" gives the total.
queriesNoArray of {id, query_type} pairs for mixed batch queries. When provided, id and query_type params are ignored.
query_typeNoA valid query type from the Queries array returned by get_term_info. Used for single id or array of ids.
force_refreshNoBypass the response cache and recompute this result. Expensive — leave it unset on a first call. Set it ONLY to re-try a call that, earlier in this same conversation, returned a result that was clearly wrong, stale, or reported as failed. Never set it on more than one retry of the same call. A failed query (count -1) is already retried once automatically, so you do not need this for that case.
include_imagesNoInclude the image/thumbnail column in result rows. Default false: the thumbnail is a long markdown image string that is rarely useful to reason over and greatly inflates every row, so it is stripped and the response says so in _note. Set true to include it (e.g. to build image URLs).

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed1 schema field changed
    • addedInput schema / properties / force_refresh
      Added value: +{
+  "description": "Bypass the response cache and recompute this result. Expensive — leave it unset on a first call. Set it ONLY to re-try a call that, earlier in this same conversation, returned a result that was clearly wrong, stale, or reported as failed. Never set it on more than one retry of the same call. A failed query (count -1) is already retried once automatically, so you do not need this for that case.",
+  "type": "boolean"
+}
  2. Changed3 schema fields changed
    • addedInput schema / properties / include_images
      Added value: +{
+  "description": "Include the image/thumbnail column in result rows. Default false: the thumbnail is a long markdown image string that is rarely useful to reason over and greatly inflates every row, so it is stripped and the response says so in _note. Set true to include it (e.g. to build image URLs).",
+  "type": "boolean"
+}
    • addedInput schema / properties / limit
      Added value: +{
+  "description": "Max rows returned per call (default 25). The true total is always returned as \"count\"; broad queries (e.g. ListAllAvailableImages, or NeuronsSynaptic on a whole region) can have thousands to hundreds of thousands of rows. Use 0 for all rows (still capped server-side ~25000 - avoid for broad queries).",
+  "type": "number"
+}
    • addedInput schema / properties / offset
      Added value: +{
+  "description": "Row offset for paging (default 0). To get the next page, re-run with offset increased by limit; \"count\" gives the total.",
+  "type": "number"
+}
  3. Changed6 schema fields changed
    • changedInput schema / properties / id / description
      Previous value: -"VFB ID (e.g., VFB_00101567)"New value: +"One or more VFB IDs to query"
    • addedInput schema / properties / id / oneOf
      Added value: +[
+  {
+    "description": "A single VFB ID (e.g., VFB_00101567)",
+    "type": "string"
+  },
+  {
+    "description": "An array of VFB IDs — all will use the same query_type",
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  }
+]
    • removedInput schema / properties / id / type
      Removed value: -"string"
    • addedInput schema / properties / queries
      Added value: +{
+  "description": "Array of {id, query_type} pairs for mixed batch queries. When provided, id and query_type params are ignored.",
+  "items": {
+    "properties": {
+      "id": {
+        "description": "VFB ID",
+        "type": "string"
+      },
+      "query_type": {
+        "description": "Query type for this ID",
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "query_type"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • changedInput schema / properties / query_type / description
      Previous value: -"A valid query type from the Queries array returned by get_term_info (e.g., PaintedDomains, AllAlignedImages, SubclassesOf). Do NOT use tool names here. Always check get_term_info first for available query types."New value: +"A valid query type from the Queries array returned by get_term_info. Used for single id or array of ids."
    • removedInput schema / required
      Removed value: -[
-  "id",
-  "query_type"
-]
  4. Changed1 schema field changed
    • changedInput schema / properties / query_type / description
      Previous value: -"A valid query type from the Queries array returned by get_term_info (e.g., PaintedDomains, AllAlignedImages, SubclassesOf). Do NOT use tool names here."New value: +"A valid query type from the Queries array returned by get_term_info (e.g., PaintedDomains, AllAlignedImages, SubclassesOf). Do NOT use tool names here. Always check get_term_info first for available query types."
  5. Changed1 schema field changed
    • changedInput schema / properties / query_type / description
      Previous value: -"Query type (e.g., PaintedDomains)"New value: +"A valid query type from the Queries array returned by get_term_info (e.g., PaintedDomains, AllAlignedImages, SubclassesOf). Do NOT use tool names here."
  6. First observed

TDQS

A4.9/5.0
Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

All VirtualFlyBrain toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.7/5.0
Disambiguation5/5

Each tool targets a distinct operation: searching vs. metadata retrieval vs. pre-computed queries vs. live connectivity vs. ID resolution vs. listing datasets/facets. The descriptions explicitly clarify differences between similar tools like query_connectivity and run_query, and resolve_entity vs. resolve_combination.

Naming Consistency5/5

All tool names follow a consistent snake_case verb_noun pattern (get_hierarchy, list_connectome_datasets, query_connectivity, resolve_entity, run_query, search_terms). No mixing of styles or vague verbs.

Tool Count5/5

9 tools is well-scoped for a specialized domain server. Each tool covers a necessary capability without redundancy or bloat, fitting comfortably within the ideal 3-15 range.

Completeness5/5

The tool set comprehensively covers the VFB domain: search, metadata, hierarchy, pre-computed queries, live cross-dataset connectivity, ID resolution, and listing of datasets and facets. Obvious gaps like direct image retrieval are handled via get_term_info, and publication queries are available through run_query.

Resources