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, PRs, messaging (Slack/Teams), issues (Jira/Linear/GitHub), customer support tickets (Zendesk), code (semantic search + file reads), code history, incidents, public web, internal URLs. Composes semantic search, code search, file reads, PR/issue queries, messaging search, and incident lookups.
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 broad or cross-system investigations — highly recommended during planning tasks, where wider coverage reduces the risk of missing prior work, rejected approaches, or related constraints. | |
| 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 |