MCP tools

Updated

Hone's MCP server exposes 24 read-only tools. In practice you ask your agent a question in plain language and it picks the tools. This page is for when you want to know what is available or why an answer looks the way it does.

None of the tools change telemetry or application data. The only thing a call writes is credential-usage metadata, such as the credential's last-used time.

How results are measured

Durations are in milliseconds. Nightwatch records durations in microseconds; Hone converts them in the aggregates.
Most tools read daily aggregates, not raw events. Aggregates are built by the hourly rollup. Every aggregate-backed answer includes an aggregate_freshness block, so you can tell "nothing is slow" apart from "the rollup has not run recently".
p95 and p99 are the worst daily value in the window, not a true percentile over the whole window, because percentiles cannot be averaged across days.
Things are grouped by a normalized key. For a request it is the method and route (GET /health); for a query, the SQL shape without bindings; for an exception, its class, file and line; for an outgoing request, the host and URL; for cache events, store:type such as redis:miss.
app is an app id. For apps Scalpels attached, that is the Cloud environment id or forgesite-{id}. Call list-apps-tool to see the ids.
tools/list is paginated. The first page returns 15 tools and a cursor. If your client shows only 15, it stopped at the first page.

Discovery

These read raw events, so they cover the last 72 hours by default. Each takes an optional hours lookback from 1 to 720.

Tool	What it answers	Other arguments
`list-apps-tool`	Which apps are reporting, with each one's latest event time.	None.
`record-types-tool`	Which kinds of record have arrived, with counts.	`app` (optional).
`deploys-tool`	Recent deploy ids with the first and last event seen for each.	`app` (optional).
`ingest-freshness-tool`	Each app's latest event and ingest time, records the client dropped or failed to deliver (by app and deploy), aggregate freshness, and overall maintenance health.	None.

ingest-freshness-tool is the tool to use when you want to know whether an app is connected and whether Hone itself is keeping up.

Slow things

slow_requests, slow_queries, slow_jobs and slow_outgoing_requests return the worst offenders for requests, database queries, queued jobs and outgoing HTTP calls. Each offender has a normalized_key, a count, and avg, max, p95 and p99.

All four take the same optional arguments:

Argument	Default	Meaning
`app`	all apps	Limit to one app.
`deploy`	all deploys	Limit to one deploy id.
`days`	7	Trailing window in days.
`metric`	`p95`	Sort by `count`, `avg`, `max`, `p95` or `p99`.
`limit`	10	Maximum offenders returned.

Analysis

Tool	What it answers	Arguments
`query_metric`	One metric for any record type, optionally for one key. Use it when no specific tool fits.	`record_type` and `metric` (required); `normalized_key`, `app`, `deploy`, `days` (optional).
`regression_check`	How one metric for one key changed across recent deploys.	`record_type`, `normalized_key` and `metric` (required); `app`, `deploys_limit` (default 5).
`exceptions`	Exceptions by volume, with the most recent day each was seen.	`app`, `days` (default 7), `limit` (default 10).
`top_users`	Activity counted by user id. Names, usernames and emails are never used.	`app`, `days`, `limit`.

metric is one of count, avg, max, p95 or p99. record_type is a Nightwatch record type such as request, query, queued-job or outgoing-request; record-types-tool lists the ones you have. regression_check only has something to compare when your apps set NIGHTWATCH_DEPLOY; see Connecting your apps.

Volume and health

These take app and days (default 7). The ones that return a list also take limit (default 10).

Tool	What it answers
`cache_stats`	Cache events by store and type, such as `redis:hit` and `redis:miss`.
`queue_throughput`	Total queued jobs, with the busiest jobs by count.
`mail_volume`	Total mail sent in the window.
`notification_volume`	Total notifications sent in the window.
`scheduled_task_health`	Scheduled task counts and durations by task name.
`command_stats`	Artisan command counts and durations by command name.
`log_volume_by_level`	Log records counted by level. Log messages are never returned.

Activity and traffic

These five work on per-minute activity buckets rather than daily aggregates. Each needs an app, and all except edge_profile need a from and to: minute-aligned RFC 3339 timestamps such as 2026-10-01T00:00:00Z, at most 31 days apart. Both ends are included.

A request counts as human when it has an authenticated user and guest when it does not. Background activity is scheduled tasks and queued jobs.

Tool	What it answers
`awake_segments`	The stretches of time your compute and your database would be awake, given the idle timeouts you pass in `compute_idle_minutes` and `db_idle_minutes` (both required). Each segment is broken down into human, guest and background minutes. Use it to see what is keeping a scale-to-zero environment or a serverless database awake.
`background_db_activity`	Scheduled tasks and jobs that touched the database, with how often each ran per minute.
`guest_db_routes`	Routes that served guests and ran database queries, with hit counts and the response's cookie, `Cache-Control` and `Vary` headers as observed.
`guest_traffic_clusters`	Guest traffic grouped by path, user agent and network (ASN), with request volume and the compute awake time it caused.
`edge_profile`	Whether the app's domain uses Cloudflare nameservers, checked by DNS lookup, and, for each route, the caching headers its responses carried.

The response-header facts come from a middleware the client registers automatically, so they appear once an app runs hone-client. The network (ASN) in guest_traffic_clusters needs an IP-to-ASN dataset on the Hone server; without one it is reported as empty. See Configuration.

Example questions

"Using Hone, what should we improve this week?"
"What got slower after the last deploy?"
"Which queries have the worst p99 over the last 30 days?"
"Which exceptions are thrown most often, and when was each last seen?"
"What is keeping our database awake overnight?"