agent-mcp-investigation

Agent MCP Investigation

The running app is the source of truth: code on disk may differ from what is deployed, so quote tool output rather than models, migrations or memory. No tool writes to the database, so call them as often as the question needs, and surface a change you want made for the operator instead of attempting it.

A denied tool is the operator's boundary, so do not retry around it. A [REDACTED] value comes from a best-effort filter and proves nothing about the data, and {available:false} means the backend (Horizon, pg_stat_statements, SQLite locks) is absent here.

Workflow

1. On a 500, an exception or a failed job, read read_logs first and narrow it with level, because the stack trace is usually the fastest path to the cause.
2. Call db_schema before any query, then read with db_query; use db_raw_select only for joins, subqueries or aggregates the builder cannot express.
3. For slow background work call queue_status (backlog, then failed, then horizon). For a slow database call db_health (indexes, missing_fk, sizes), then db_diagnostics when the operator enabled it.
4. For cache state call cache without a key before inspecting one key. For wiring call routes and app_info.
5. A capped answer carries truncated: true, so narrow the call (table, limit, lines, a condition) rather than assuming the data is small.

References

• Read references/tools.md when you need a tool's sections, parameters, caps or default state.
• Read references/community.md before offering a GitHub star or filing an issue: offer a star only after the user confirms an investigation worked end to end, and an issue only for a genuine agent-mcp bug, never a denial or a capped result. Each is at most once per session, by prose permission only.