context_research
Retrieve institutional context that code search cannot provide — WHY, WHO, WHEN behind the code. Primary Unblocked research tool; reach for it first for synthesis across sources.
One call searches every indexed source: documentation (Notion), code and code history (GitHub), PRs.
When to call
Call proactively at the start of any non-trivial task, and whenever you hit an unknown. Do not wait for the user to ask.
Planning, investigation, refactor, migration, or feature work. Fire in the same tool block as your first Explore/Grep/Read calls — complementary, zero latency cost.
"Why does this exist" or "why is it done this way" questions. Code reading cannot answer these.
Behavior doesn't match the code. Check history before assuming the code is wrong.
Unfamiliar class, service, endpoint, flag, config key, or error string while reading or editing.
Before writing new code. Check whether the pattern, bug, fix, helper, or abstraction already exists.
Incident, alert, or outage. Connect affected systems to recent changes and prior fix patterns.
Filtered activity lookups. "PRs merged last week in auth service", "open incidents tagged ingestion", "Jira epics in PROJ from Q1".
Ambiguous user requests. Find the team's prior framing before guessing.
Before recommending a solution. Verify the approach hasn't been tried, rejected, or superseded.
When NOT to call
Known URL in hand. Use
context_get_urls— faster, deterministic, returns full hydrated content. Fall back here only if the URL pattern is unsupported.
If unsure, call. Missed context is expensive; recall misses are cheap.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What to search for — the topic, entities, urls, and any hard filters (date range, author, status) that constrain which documents match. Write a complete phrase rather than bare keywords — "How does the authentication service handle token refresh?" not "auth token refresh". | |
| effort | No | Search effort: low, medium, or high. Use "low" by default — it's the fastest and cheapest, and sufficient for targeted lookups that point at a specific entity, URL, file, or question. Use "medium" for simple research tasks, or when the query does not translate cleanly to a single entity or URL and some exploration is needed. Use "high" for planning tasks and broad or cross-system investigations, where wider coverage reduces the risk of missing prior work, rejected approaches, or related constraints. Do not use "high" for a simple lookup of one entity, URL, file, ticket, or error: it runs several times as many searches as "medium" and is noticeably slower. | |
| instruction | No | How to evaluate the matches — relevance criteria, domain priorities, or selection guidance that shapes which results surface and in what order, without changing what is searched. E.g., "Prefer architecture decision records over API reference docs". |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes |