Result classifier
from fastmcp_feedback.instrumentation import DEFAULT_RESULT_CLASSIFIER, soft_error_classifierContract
Section titled “Contract”A result classifier is (tool: str, result: Any) -> str | None.
- It runs only for calls that did not raise.
resultis the payload the record stores: the tool’s structured content when present, otherwise its content items (texts, or{"type": ...}for other kinds).- When the tool marked its result as an MCP error (
isError) without raising,resultarrives as a dict with"isError": True, alongside the payload’s own keys or with the payload under"content". Nonemeans ok. A string marks a soft error:outcome="soft_error",ok=False,error_type="SoftError", and the string, redacted and cut tomax_error_chars, becomeserror_message.- If it raises, the error is logged and the call is recorded as
ok. - It never changes what the client receives.
soft_error_classifier
Section titled “soft_error_classifier”soft_error_classifier(*, statuses=("error", "failed", "failure"), status_keys=("status", "state"), flag_keys=("ok", "success"), extra_statuses=(), error_keys=("error",), message_keys=("error", "message", "detail", "reason"), ) -> ResultClassifier| Parameter | Description |
|---|---|
statuses | Values that mean failure at a status key, compared case-insensitively. |
status_keys | Keys holding a status. |
flag_keys | Keys holding a success boolean. |
extra_statuses | Added to statuses. |
error_keys | Keys whose non-empty string value marks a failure on its own. () turns the check off. Dotted paths allowed. |
message_keys | Where <detail> comes from, first non-empty wins. Dotted paths allowed. |
Non-dict results are always ok. For a dict, checks run in this order and the first that applies decides:
| Order | Condition | Result | Message |
|---|---|---|---|
| 1 | a status key holds a failing status | soft error | status=failed: <detail> |
| 2 | a flag key is exactly False | soft error | ok=False: <detail> |
| 3 | isError or is_error is True | soft error | isError: <detail or content text> |
| 4 | a flag key is exactly True | ok | |
| 5 | an error key holds a non-blank string | soft error | error: <string> |
| 6 | none of the above | ok |
<detail> is the first non-empty value at message_keys (error,
message, detail and reason by default); a dict there is searched one
level down for the same keys. Lists are skipped. A label without a detail is
used alone, such as status=failed. For an error-key hit the label is the key
as written, path included (result.error: <string>).
Dotted paths
Section titled “Dotted paths”message_keys and error_keys entries can be paths into nested dicts:
"snapshot.error" reads result["snapshot"]["error"]. The rules:
- A key that literally contains a dot is tried first, so a result with a
"snapshot.error"key of its own uses that. - Otherwise the path is split on every dot and walked. A missing step, or a step that is not a dict (None, a string, a list), means the key is not there. A lookup never raises.
status_keysandflag_keysare plain keys.
DEFAULT_RESULT_CLASSIFIER is soft_error_classifier() with these defaults.
classify = soft_error_classifier(extra_statuses=("unknown_target",))assert classify("render", {"status": "unknown_target", "error": "no such object"}) == "status=unknown_target: no such object"assert classify("render", {"status": "failed", "error": {"code": 7, "message": "disk full"}}) == "status=failed: disk full"assert classify("render", {"error": {"code": 1}}) is Noneassert DEFAULT_RESULT_CLASSIFIER("t", {"isError": True, "content": ["boom"]}) == "isError: boom"
nested = soft_error_classifier(error_keys=("result.error",), message_keys=("detail", "error"))assert nested("t", {"result": {"error": "broke"}}) == "result.error: broke"assert nested("t", {"result": "not a dict"}) is Noneassert nested("t", {"status": "failed", "error": "e", "detail": "d"}) == "status=failed: d"History
Section titled “History”| Release | Change |
|---|---|
| 2026.09.27.4 | Classification added; outcome column. |
| 2026.10.01 | error_keys check, on by default. |
| 2026.10.01.1 | An explicit True flag wins over an error string. |
| 2026.10.04 | message_keys; dotted paths in message_keys and error_keys. |