Tako

Find what data Tako holds on an entity or a metric, and the canonical name it holds it under. Best for: coverage questions themselves, or a metric's canonical name before a priced search. Put a company, person, or place in `q` to list the metrics tracked on it; put a metric in `q` to list the entities it covers. Add `metric` when you know the measure — you get the resolved pair and a ready-to-run `next_call`. Search on the canonical names it returns, not your own phrasing — `tako_search` matches the graph's names, not yours. A name here means the graph tracks it, not that a card exists. If the follow-up search comes back empty, say Tako has no card for it rather than rephrasing the query. Hand a node id to `tako_graph_related` to see what else connects to it.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 2,
      "description": "The entity or metric to look up by name — \"Carnival\", \"United States\", \"Nvidia\". Put the measure in `metric`, not here."
    },
    "metric": {
      "description": "The measure, when you already know it — \"gross margin\", \"capex\". Supplying it resolves the entity+metric pair directly; omit it to browse everything the entity has.",
      "type": "string",
      "minLength": 2
    },
    "types": {
      "description": "Narrow resolution to one kind, an entity or a metric. Omit to resolve both.",
      "type": "string",
      "enum": [
        "entity",
        "metric"
      ]
    },
    "label": {
      "description": "NER label to prefer for `q` — a boost, not a filter. Set it when you can categorize the term: company → ORG, place → GPE, person → PERSON. It never applies to `metric`.",
      "type": "string",
      "enum": [
        "PERSON",
        "ORG",
        "GPE",
        "LOC",
        "PRODUCT",
        "EVENT",
        "LANGUAGE",
        "MONEY",
        "METRIC",
        "STOCK_TICKER",
        "WEBSITE"
      ]
    },
    "limit": {
      "description": "How many candidates to resolve for each of `q` and `metric`. Raising it widens what the tool considers, not just what it shows: a deeper metric can become the one `next_call` names.",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    }
  },
  "required": [
    "q"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean",
      "description": "Whether Tako holds matching data; `verified` says on what evidence."
    },
    "verified": {
      "description": "What was checked. `pair`: the metric is on the entity's own list. `coverage`: a list was drilled. `unlinked`: the list was checked, the metric is absent. `resolution`: names resolved only.",
      "type": "string",
      "enum": [
        "coverage",
        "pair",
        "unlinked",
        "resolution"
      ]
    },
    "guidance": {
      "description": "The verdict, and the one next action.",
      "type": "string"
    },
    "matches": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "description": "Canonical graph name — search on this."
          },
          "type": {
            "type": "string",
            "description": "entity or metric; also what `coverage` counts."
          },
          "kind": {
            "type": "string"
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "unavailable": {
            "type": "boolean"
          },
          "filter": {
            "description": "The `metric` phrase that narrowed this list. When set, `total` counts only matching entries.",
            "type": "string"
          },
          "coverage": {
            "type": "object",
            "properties": {
              "total": {
                "type": "number",
                "description": "Entries in all, not entries listed."
              },
              "total_capped": {
                "type": "boolean",
                "description": "`total` is a floor."
              },
              "truncated": {
                "description": "More entries exist than are listed.",
                "type": "boolean"
              },
              "items": {
                "description": "Headline-first.",
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "Canonical graph name."
                    },
                    "id": {
                      "type": "string",
                      "description": "Graph node id."
                    }
                  },
                  "required": [
                    "name",
                    "id"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "required": [
              "total",
              "total_capped"
            ],
            "additionalProperties": {}
          }
        },
        "required": [
          "id",
          "name",
          "type",
          "coverage"
        ],
        "additionalProperties": {}
      },
      "description": "The nodes whose coverage was drilled, best first."
    },
    "candidates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "description": "Canonical graph name — search on this."
          },
          "type": {
            "type": "string",
            "description": "entity or metric; also what `coverage` counts."
          },
          "kind": {
            "type": "string"
          },
          "coverage": {
            "type": "object",
            "properties": {
              "total": {
                "type": "number"
              },
              "total_capped": {
                "type": "boolean",
                "description": "`total` is a floor."
              }
            },
            "required": [
              "total",
              "total_capped"
            ],
            "additionalProperties": {}
          }
        },
        "required": [
          "id",
          "name",
          "type"
        ],
        "additionalProperties": {}
      },
      "description": "The other nodes `q` resolved to, best first."
    },
    "next_call": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "tool": {
              "type": "string"
            },
            "query": {
              "type": "string"
            }
          },
          "required": [
            "tool",
            "query"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "A follow-up search in canonical names. Null when no target is unambiguous."
    },
    "entity": {
      "description": "Lookup path: the resolved entity.",
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "name"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "metric": {
      "description": "Lookup path: the resolved metric.",
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "name"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "entity_candidates": {
      "description": "Runners-up.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name"
        ],
        "additionalProperties": false
      }
    },
    "metric_candidates": {
      "description": "Runners-up.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "found",
    "matches",
    "candidates",
    "next_call"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Fetch the full content behind a url: a web page's text, or an exportable Tako card's data rows. Batch up to 10 urls in one call — each one is billed and fails on its own. Fetch only cards that `tako_search` marked `exportable: true`. Rows bill per 1,000 delivered, so set `max_rows` when the recent rows are enough. If a page is long, such as a filing or an annual report, set `query` to get back only the passages that match. Best for: reading one source in full — a page you need to quote, or the rows behind a card you need to compute over.

{
  "type": "object",
  "properties": {
    "urls": {
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "The urls to fetch: a Tako card url or a web result url. One call for 8 urls costs the same as 8 separate calls and saves 7 round trips."
    },
    "max_rows": {
      "description": "Tako cards only: how many rows to return. Omit it for the whole card, up to 2,000 rows. Every row delivered is billed, so lower it when the recent rows are enough.",
      "type": "integer",
      "minimum": 1,
      "maximum": 2000
    },
    "max_chars": {
      "description": "Web pages only: character cap on the extracted text. Inline fetches default to 100,000 per url, less across a batch. Raise it for a long document; `truncated` reports a cut.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000000
    },
    "query": {
      "description": "Web pages only: return the passages around matches of this phrase instead of the whole page. The full page is always scanned, so no match means the phrase isn't there.",
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "urls"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "The url this entry is for."
          },
          "note": {
            "description": "What the `query` match found.",
            "type": "string"
          },
          "rows": {
            "description": "Tako cards only: the card's data.",
            "type": "object",
            "properties": {
              "columns": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Column names, in row order; the unit is in the name."
              },
              "rows": {
                "type": "array",
                "items": {
                  "type": "array",
                  "items": {}
                },
                "description": "Positional cells; a missing cell is null."
              },
              "total_rows": {
                "description": "Rows behind the card, before `max_rows`.",
                "type": "number"
              }
            },
            "required": [
              "columns",
              "rows"
            ],
            "additionalProperties": false
          },
          "text": {
            "description": "Web pages only: the page text.",
            "type": "string"
          },
          "error": {
            "description": "Why this url alone failed; the others are unaffected.",
            "type": "string"
          },
          "truncated": {
            "description": "Part of this payload was cut.",
            "type": "boolean"
          },
          "source_url": {
            "description": "Where a redirect landed.",
            "type": "string"
          },
          "cost": {
            "type": "number",
            "description": "USD billed for this url."
          }
        },
        "required": [
          "url",
          "cost"
        ],
        "additionalProperties": {}
      },
      "description": "One per requested url, in order."
    },
    "usage": {
      "type": "object",
      "properties": {
        "total_cost_usd": {
          "type": "number"
        }
      },
      "required": [
        "total_cost_usd"
      ],
      "additionalProperties": {},
      "description": "What this request cost."
    }
  },
  "required": [
    "results",
    "usage"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Explore what a graph node connects to — its metrics, the entities a metric covers, competitors, industry, index membership, and sources. Two modes. Pass `node_id` alone for the map: every relation group with its key, label, total, and its first 3 names. Pass `relation` to page one group, where each item comes back with the id that explores it. Read a key off the map rather than guessing — an unknown key returns an empty group, not an error. Best for: expanding a node you already resolved. Resolve a name to a node id with `tako_available_data` first. A metric listed here means the graph tracks it, not that a card exists — `tako_search` is the final check.

{
  "type": "object",
  "properties": {
    "node_id": {
      "type": "string",
      "minLength": 1,
      "description": "Public id of the node to explore, as returned by `tako_available_data` or on a `tako_search` card."
    },
    "relation": {
      "description": "Relation key to page, taken from the map: metrics, entities, siblings, part_of, members, or a named edge like rel:competes_with. Omit for the map.",
      "type": "string",
      "minLength": 1
    },
    "q": {
      "description": "Case-insensitive substring filter on names and aliases, one string per call: \"revenue\" matches `Total Revenue` and misses `Sales`. Call once per name variant.",
      "type": "string",
      "minLength": 1
    },
    "label": {
      "description": "NER label to prefer among the related nodes — a boost, not a filter.",
      "type": "string",
      "enum": [
        "PERSON",
        "ORG",
        "GPE",
        "LOC",
        "PRODUCT",
        "EVENT",
        "LANGUAGE",
        "MONEY",
        "METRIC",
        "STOCK_TICKER",
        "WEBSITE"
      ]
    },
    "infer_label": {
      "description": "Detect labels from `q`. Omit it and the server infers them whenever `q` is set.",
      "type": "boolean"
    },
    "cursor": {
      "description": "Page handle from a previous drilled relation. Omit it for the first page.",
      "type": "string",
      "minLength": 1
    },
    "limit": {
      "description": "Page size for a drilled relation. Omit it and the server serves 50. Ignored on the map, where every group returns its first 3 names whatever you pass.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "node_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "node": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "description": "entity or metric."
        },
        "name": {
          "type": "string",
          "description": "Canonical graph name — search on this."
        },
        "kind": {
          "type": "string"
        },
        "aliases": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "description": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "type",
        "name"
      ],
      "additionalProperties": {}
    },
    "relations": {
      "description": "Every group, previewed. The map.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "Pass back as `relation` to page it."
          },
          "label": {
            "type": "string"
          },
          "total": {
            "type": "number"
          },
          "total_capped": {
            "type": "boolean",
            "description": "`total` is a floor."
          },
          "next_cursor": {
            "description": "Pass back as `cursor`.",
            "type": "string"
          },
          "preview": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The group's first 3 names."
          }
        },
        "required": [
          "key",
          "label",
          "total",
          "total_capped",
          "preview"
        ],
        "additionalProperties": {}
      }
    },
    "relation": {
      "description": "The one group you drilled.",
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "key": {
              "type": "string",
              "description": "Pass back as `relation` to page it."
            },
            "label": {
              "type": "string"
            },
            "total": {
              "type": "number"
            },
            "total_capped": {
              "type": "boolean",
              "description": "`total` is a floor."
            },
            "next_cursor": {
              "description": "Pass back as `cursor`.",
              "type": "string"
            },
            "items": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "name"
                ],
                "additionalProperties": {}
              },
              "description": "This page of the group."
            }
          },
          "required": [
            "key",
            "label",
            "total",
            "total_capped",
            "items"
          ],
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "node"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Search Tako's data graph and the live web in one call: many results at once, as structured cards plus web results, with the top card rendered inline as a chart. It finds data; `tako_contents` fetches it. Each card carries a headline value, node ids, and a url — pass the url to `tako_contents` for rows (`exportable: true` cards) or a web result's full page text. When `exportable` is false the rows are locked — read the headline value from the card's `description`. Best for: breadth — fan out several narrow queries in parallel. Each query resolves one metric — for one entity, or a comparison set ("Apple revenue", "Nvidia vs AMD gross margin"); several metrics or topics in one query retrieve poorly. To learn what Tako covers, or a metric's canonical name, run `tako_available_data` first, then search on the canonical name it returns.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Natural-language search query (e.g. \"US GDP growth\", \"Intel vs Nvidia revenue\"). Double-quote a multi-word name to keep it one entity (\"tesla motors\" club revenue); an unpaired quote disables quoting. Website-traffic data is keyed by domain — query \"openai.com monthly visits\", not \"OpenAI website visits\"."
    },
    "sources": {
      "default": [
        "data",
        "web"
      ],
      "description": "Which corpora to search; default is both. Narrow to [\"data\"] once `tako_available_data` confirms coverage; narrow to [\"web\"] only for news or page text — website traffic is in the data graph.",
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "data",
          "web"
        ]
      }
    },
    "country_code": {
      "description": "ISO 3166-1 alpha-2 country code for localized results. Omit it and the server uses US. Set it to localize for the user.",
      "type": "string"
    },
    "locale": {
      "description": "BCP-47 locale tag for language and formatting. Omit it and the server uses en-US. Set it to localize for the user.",
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "cards": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "description": {
            "description": "Headline value and range — often the answer itself.",
            "type": "string"
          },
          "exportable": {
            "type": "boolean",
            "description": "true → tako_contents on `url` returns the rows; false → rows are locked, read the headline from `description`."
          },
          "url": {
            "description": "The card page — the tako_contents handle.",
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "coverage_end": {
            "description": "Where the DATA ends — use this, not `last_updated`, to judge whether a figure is current. Reduced ISO precision at the series' own granularity (\"2026\", \"2026-06\", \"2026-06-30\"), and it can be in the future on a card with projections.",
            "type": "string"
          },
          "last_updated": {
            "description": "Date Tako last refreshed this card — NOT where its data ends.",
            "type": "string"
          },
          "total_rows": {
            "description": "Rows behind `url` (exportable cards only).",
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "relevance": {
            "description": "Either a 1.0-5.0 score as a string (\"4.5\", 5.0 = exact match) on entitled accounts, or a coarse word (\"High\"). Higher is more relevant in both forms.",
            "type": "string"
          },
          "nodes": {
            "description": "Graph handles — pass ids to tako_graph_related.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name",
                "type"
              ],
              "additionalProperties": {}
            }
          }
        },
        "required": [
          "exportable"
        ],
        "additionalProperties": {}
      },
      "description": "The data cards. Fetch an exportable card's rows with tako_contents on its url."
    },
    "web_results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "snippet": {
            "description": "Passages selected against the query. A ' … ' marks a discontinuity — joined passages or the page's own ellipsis — so never quote across it as one sentence. null → no relevant passage, url still fetchable.",
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "source": {
            "type": "string"
          },
          "published": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "content": {
            "description": "Page text — only when the request asked for it.",
            "type": "object",
            "properties": {},
            "additionalProperties": {}
          }
        },
        "required": [
          "url"
        ],
        "additionalProperties": {}
      },
      "description": "Web results."
    },
    "usage": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "total_cost_usd": {
              "type": "number"
            }
          },
          "required": [
            "total_cost_usd"
          ],
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ],
      "description": "Cost-plus usage for this request (null when not metered)."
    },
    "guidance": {
      "description": "Zero-card responses only: what this response is evidence about, and the one next action.",
      "type": "string"
    },
    "metric_definitions": {
      "description": "What each metric means (unit, basis, caveats), keyed by metric name, deduped across cards.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "source_notes": {
      "description": "What each source is and how it builds its data, keyed by source name.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    }
  },
  "required": [
    "cards",
    "web_results",
    "usage"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}