feedback

When to use

ONLY when a ToolCairn response was wrong, broken, low-quality, or missed something obvious — never for positive feedback or routine confirmation. Every other tool’s response includes a feedback_channel hint reminding you of this; the schema enforces it (severity is negative-only by enum, and the server deduplicates identical reports within 24h).

Input schema

tool_name················································································"classify_prompt" | "search_tools" | "search_tools_respond" | "get_stack" | "check_compatibility" | "compare_tools" | "refine_requirement" | "check_issue" | "verify_suggestion" | "report_outcome" | "suggest_graph_update" | "toolcairn_init" | "read_project_config" | "update_project_config" | "toolcairn_auth"required

Which ToolCairn tool the feedback is about. Forces the agent to localize the issue. Excludes `feedback` itself — no recursive feedback.

severity················································································"broken" | "wrong_result" | "low_quality" | "missing_capability" | "confusing"required

Negative-only enum. There is no syntactic way to file a positive report — that is intentional. `broken` = the tool errored or returned malformed output. `wrong_result` = the answer was clearly incorrect. `low_quality` = answer was relevant but unhelpful. `missing_capability` = ToolCairn lacks a feature you needed. `confusing` = the response was hard to interpret.

message················································································string (20–2000 chars)required

What went wrong, specific enough that an admin can act on it. The 20-character minimum blocks "fine" / "ok" / "bad" loops.

query_id················································································string (UUID)optional

The `query_id` of the offending call. Every recommendation tool surfaces a `query_id` in its response — pass it through so admin can replay the failing input/output.

expected················································································string (≤1000 chars)optional

What the agent expected the response to contain.

actual················································································string (≤1000 chars)optional

What the response actually contained, paraphrased.

Examples

Wrong result

{
  "tool_name": "search_tools",
  "severity": "wrong_result",
  "message": "Query asked for Go HTTP clients; results were entirely Python and Node libraries with no Go alternatives.",
  "query_id": "5b3f8a90-2c9d-4f0e-b1a4-9e6e6d7c5a30",
  "expected": "Top 5 results to be Go HTTP libraries (resty, fasthttp, etc.)",
  "actual": "Top 5 were requests, axios, fetch, urllib3, httpx"
}

{
  "tool_name": "get_stack",
  "severity": "missing_capability",
  "message": "No way to constrain a stack layer to a specific license family. Need a 'license_allowlist' option for compliance use cases."
}

{
  "tool_name": "check_compatibility",
  "severity": "broken",
  "message": "Returned 500 internal server error for tool_a='vite' tool_b='vue@3.4'. Same pair worked yesterday."
}

Response format

Fire-and-forget — the response is just an ack. Status code is 202 Accepted.

{
  "ok": true,
  "data": {
    "recorded": true
  }
}

{
  "ok": true,
  "data": {
    "recorded": true,
    "deduped": true
  }
}

Status codes

400················································································Bad Requestoptional

Validation failed. Most common causes: severity not in the negative-only enum, message under 20 characters, tool_name not in the recognized list.

202················································································Acceptedoptional

Standard success — the report was recorded (or silently coalesced into a duplicate from the past 24h).

Related tools

• report_outcome — Use this for outcomes of libraries ToolCairn recommended. feedback is for ToolCairn itself.
• suggest_graph_update — For proposing missing tools / edges to the graph.
• Feedback Loop — How user-side outcomes shape the graph (different system from this tool).