List tool suggestions

Tools the agent went without, waiting on somebody to build them. The agent files one mid-conversation when a customer needs something it has no way to do, and the reviewer files one after a thread resolves. Each row carries prompt: the whole brief as markdown, written for a coding agent that has never seen Median. Hand it over as it stands.

GET/tool-suggestions

Authorization

AuthorizationBearer token · headerrequired

`MEDIAN_KEY` from Settings under API, or an MCP OAuth access token. A key acts as the organization; a token acts as the person who approved it.

Responses

200The queue, newest first.

suggestionsToolSuggestion[]

Show properties

Array of ToolSuggestion

idstring

conversationIdstring

conversationSubjectstring

titlestring

Sentence case, a few words: "Issue a refund". Never a function name.

summarystring

reasonstring

What the customer needed that the agent could not do.

behaviorstring

What the tool should do when called.

whenstring

When the agent should reach for it.

inputsToolSuggestionInput[]

Show properties

Array of ToolSuggestionInput

namestring

typestring

Allowed:stringnumberbooleanenum

descriptionstring

requiredboolean

optionsstring[]

Enum inputs only.

riskstring

Allowed:lowmediumreviewedhigh

suggestedAtinteger

promptstring

The whole brief as markdown: the spec, a median.config.ts snippet, and the wiring notes.

401The bearer token is missing, revoked, or expired.

errorobject

Show properties

codestring

messagestring

429Too many requests. Wait the seconds in `Retry-After`. Limits depend on the plan. See [rate limits](/api/errors-and-limits#rate-limits).

errorobject

Show properties

codestring

messagestring

Request

curl -X GET "https://api.median.sh/v1/tool-suggestions" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://api.median.sh/v1/tool-suggestions", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

Response

{
  "suggestions": [
    {
      "id": "string",
      "conversationId": "string",
      "conversationSubject": "string",
      "title": "string",
      "summary": "string",
      "reason": "string",
      "behavior": "string",
      "when": "string",
      "inputs": [
        {
          "name": "string",
          "type": "string",
          "description": "string",
          "required": true,
          "options": [
            "string"
          ]
        }
      ],
      "risk": "low",
      "suggestedAt": 0,
      "prompt": "string"
    }
  ]
}