last9-mcp-server AGENTS.md

last9-mcp-server — agent instructions

Canonical agent guidance for this repo. CLAUDE.md is a compatibility shim that includes this file — edit here, not there.

Adding or changing an MCP tool

Tool descriptions: one style, no exceptions

All tool description text lives as markdown in internal/prompts/descriptions/, embedded via go:embed in internal/prompts/prompts.go. Never define description text as Go string constants in handler packages.

For a new tool get_foo:

1. Write internal/prompts/descriptions/get_foo.md — the complete tool description.

2. Add to internal/prompts/prompts.go:

   //go:embed descriptions/get_foo.md
   var GetFooDescription string
   

3. Register in tools.go with reg(registerIfAllowed(server, cfg.AllowedTools, &mcp.Tool{Name: "get_foo", Description: prompts.GetFooDescription}, foo.NewGetFooHandler(client, cfg))), and add get_foo to its domain in internal/toolsets/toolsets.go.

   Never call last9mcp.RegisterInstrumentedTool directly from tools.go. registerIfAllowed is what enforces --toolsets filtering, surfaces registration errors instead of discarding them, and recovers the SDK's panic on an invalid tool schema. A tool registered directly leaks into every toolset — verify with go run . dump-tools --toolsets=<other-domain> that the new tool is absent.

Progressive disclosure (whales): get_logs, get_traces, get_service_logs, and prometheus_range_query serve a short description (*_base.md) with firing blurb + critical rules + a last9://reference/... pointer. Full manuals live in internal/prompts/references/ (logjson.md, tracejson.md, service_logs.md, metrics.md), embedded and registered as MCP resources in resources.go. Do not concatenate long manuals back into tools/list. Do not inject org attribute catalogs into descriptions — point at discovery tools.

The *_base.md suffix means progressive disclosure and nothing else — a description with no manual of its own must not carry it. Grandfathered: get_exceptions uses an Instructions-suffixed var as its plain description. Prefer a single description file for new tools unless progressive disclosure is required.