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; for an FBco split combination only the best tier is returned, labelled in a "match" column: Exact combination, else per hemidriver Hemidriver alone, else Hemidriver in other combination) 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
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | One or more VFB IDs to query | |
| limit | No | 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). | |
| offset | No | Row offset for paging (default 0). To get the next page, re-run with offset increased by limit; "count" gives the total. | |
| queries | No | Array of {id, query_type} pairs for mixed batch queries. When provided, id and query_type params are ignored. | |
| query_type | No | A valid query type from the Queries array returned by get_term_info. Used for single id or array of ids. | |
| force_refresh | No | 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. | |
| include_images | No | 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). |