Skip to main content
Glama

Investigate

refix_investigate
Idempotent

Start a new Refix investigation, or answer a pending clarification with response_to_input_id, or dig into a finding from refix_list_findings with finding_id. Send at most one of session_id, response_to_input_id or finding_id. Counts toward the workspace's Refix usage. For a follow-up about an earlier Refix answer in this chat, pass that answer's session_id so Refix keeps the context. If the question names a tool that is not in usable_sources from refix_get_context, tell the user it is not connected and ask whether to check the connected sources before starting. Give the user report_url at once: it opens this conversation in Refix. Then call refix_get_investigation for the result; do not start another investigation to check progress.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "question": "<question>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "refix_investigate"
  }
}

Input Schema

NameRequiredDescriptionDefault
questionYesThe user's question. With response_to_input_id, the user's answer to Refix's pending question instead.
finding_idNoAsk about one update: finding_id from refix_list_findings.
session_idNoContinue a finished conversation: session_id from an earlier investigation.
idempotency_keyYesA new random value, such as a UUID, for each new request. Reuse it only to retry the exact same request.
response_to_input_idNoAnswer Refix's pending question: pending_input.input_id from refix_get_investigation.

Output Schema

NameRequiredDescriptionDefault
stateYes
report_urlYes
session_idYes
investigation_idYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedOutput schema / properties / report_url
      Added value: +{
      +  "type": "string"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "investigation_id",
      -  "session_id",
      -  "state"
      -]New value: +[
      +  "investigation_id",
      +  "session_id",
      +  "state",
      +  "report_url"
      +]
  2. First observed

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses that the call consumes the workspace's Refix usage quota, that the operation is asynchronous with a report_url that should be surfaced immediately, and that results are retrieved separately. It does not say what happens if the mutual-exclusion rule is violated or whether a duplicate idempotency_key returns the original investigation, so a small behavioral gap remains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Information is front-loaded: the three modes come first, then the exclusivity constraint, then cost, then the workflow for surfacing report_url and retrieving results. Every sentence carries a distinct operational instruction with no restatement of the schema or annotations.

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 five-parameter, multi-modal, asynchronous tool this is complete: all modes, the exclusivity rule, the quota cost, the unavailable-source policy tied to usable_sources from refix_get_context, and the retrieval path are all covered. An output schema exists, so the description rightly omits return-value details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning: the three ID parameters are mutually exclusive modes rather than combinable filters, and session_id specifically preserves context from an earlier answer in the same chat. That mutual-exclusivity constraint is not expressed anywhere in the schema.

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 and resource ("Start a new Refix investigation") and then enumerates its two other operating modes — answering a pending clarification and drilling into a specific finding. An agent can distinguish this from refix_get_investigation and refix_list_findings purely from the text, since those siblings are named as the source of the IDs used here.

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?

Explicit when-to-use routing is given for every parameter: refix_list_findings for finding_id, refix_get_investigation for pending_input.input_id, and an earlier answer's session_id for follow-ups. It also names the alternative action explicitly ("do not start another investigation to check progress; call refix_get_investigation") and states an exclusion rule ("Send at most one of session_id, response_to_input_id or finding_id").

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources