getsentry · dcramer · Jun 11, 2026 · Jun 11, 2026 · Jun 11, 2026 · Jun 11, 2026
diff --git a/.agents/skills/qa/SKILL.md b/.agents/skills/qa/SKILL.md
@@ -66,6 +66,13 @@ behavior. For catalog tools, expect `search_sentry_tools` followed by
 `execute_sentry_tool(name: <changed_tool>)`. For direct tools, expect the tool name in
 the transcript. `--list-tools` alone is not QA.
 
+For output-format changes, also inspect the raw MCP tool result when possible,
+not only the LLM's final answer. The final answer can add model-specific text
+that is not part of the tool response. Review raw tool output against
+`docs/contributing/tool-responses.md`: it should be user-facing, structured,
+and free of raw API JSON, internal implementation IDs, empty placeholders, and
+unrelated instructions.
+
 If your changes involve agent mode or experimental tools:
 
 ```bash

diff --git a/AGENTS.md b/AGENTS.md
@@ -4,7 +4,7 @@ Sentry MCP is a Model Context Protocol server that exposes Sentry's error tracki
 ## Principles
 
 - **Type Safety**: Prefer strict types over `any` - they catch bugs and improve tooling. Use `unknown` for truly unknown types.
-- **Security**: Never log secrets. Validate external input. See docs/security.md.
+- **Security**: Never log secrets. Validate external input. See docs/operations/security.md.
 - **Simplicity**: Follow existing patterns. Check neighboring files before inventing new approaches.
 
 ## Constraints
@@ -31,26 +31,60 @@ sentry-mcp/
 └── docs/                    # All documentation
 ```
 
-## Essential Documentation
-
-**Read before making changes:**
-- docs/adding-tools.md — Tool implementation guide
-- docs/testing.md — Testing requirements
-- docs/common-patterns.md — Error handling, Zod schemas, response formatting
-- docs/error-handling.md — Error types and propagation
-
-**Reference:**
-- docs/architecture.md — System design
-- docs/api-patterns.md — Sentry API client usage
-- docs/quality-checks.md — Pre-commit checklist
-- docs/pr-management.md — Commit/PR guidelines
-- docs/security.md — Authentication patterns
-- docs/stdio-auth.md — Device code flow, token caching, client ID architecture
-- docs/oauth-signout-playbook.md — Remote OAuth failure modes, telemetry, diagnostic runbook
-- docs/embedded-agents.md — LLM provider configuration for AI-powered tools
+## Documentation Map
+
+- docs/README.md — Full documentation index
+
+**Read before tool changes:**
+- docs/contributing/adding-tools.md — Tool implementation guide
+- docs/contributing/tool-responses.md — Tool output policy and QA review checklist
+- docs/testing/overview.md — Testing requirements and snapshot policy
+- docs/contributing/common-patterns.md — Error handling, Zod schemas, shared formatting patterns
+- docs/contributing/error-handling.md — Error types and propagation
+
+**Contributing:**
+- docs/contributing/api-patterns.md — Sentry API client usage
+- docs/contributing/coding-guidelines.md — TypeScript and code style guidance
+- docs/contributing/documentation-style-guide.md — Documentation style guide
+- docs/contributing/pr-management.md — Commit and PR guidelines
+- docs/contributing/quality-checks.md — Pre-commit checklist
+- docs/contributing/search-events-api-patterns.md — Search Events API patterns
+
+**Testing:**
+- docs/testing/overview.md — Unit, snapshot, eval, and agent CLI testing
+- docs/testing/stdio.md — Stdio transport testing
+- docs/testing/remote.md — Remote server and OAuth testing
+
+**Architecture and Operations:**
+- docs/architecture/overview.md — System design
+- docs/operations/security.md — Authentication and security patterns
+- docs/operations/stdio-auth.md — Device code flow, token caching, client ID architecture
+- docs/operations/oauth-signout-playbook.md — Remote OAuth diagnostic runbook
+- docs/operations/embedded-agents.md — LLM provider configuration for AI-powered tools
+- docs/operations/github-actions.md — GitHub Actions guidance
+- docs/operations/logging.md — Logging guidance
+- docs/operations/monitoring.md — Monitoring guidance
+- docs/operations/token-cost-tracking.md — Tool definition token cost tracking
+
+**Cloudflare:**
+- docs/cloudflare/overview.md — Cloudflare package overview
+- docs/cloudflare/architecture.md — Cloudflare architecture
+- docs/cloudflare/oauth-architecture.md — Cloudflare OAuth architecture
+
+**Integrations:**
+- docs/integrations/claude-code-plugin.md — Plugin structure and agent prompts
+- docs/integrations/flue-hooks.md — Flue hook notes
+- docs/integrations/ide-instructions-refactor.md — IDE instruction refactor notes
+
+**Specs:**
+- docs/specs/README.md — Specs index
+- docs/specs/embedded-agent-openai-routing.md — Embedded agent OpenAI routing spec
+- docs/specs/search-events.md — Search Events spec
+- docs/specs/subpath-constraints.md — Subpath constraints spec
+
+**Releases:**
 - docs/releases/stdio.md — npm package release
 - docs/releases/cloudflare.md — Cloudflare deployment
-- docs/claude-code-plugin.md — Plugin structure and agent prompts
 
 ## Commands
 
@@ -89,8 +123,8 @@ Use `/dex` skill to coordinate complex work. Create tasks with full context, bre
 1. Check neighboring files for existing patterns before writing new code.
 2. When adding or modifying Sentry API endpoint usage, ALWAYS validate the endpoint behavior against the Sentry source code in `~/src/sentry` instead of assuming docs or client parameters are authoritative.
 3. Update relevant docs when changing functionality.
-4. Follow docs/error-handling.md for error types.
-5. Follow docs/pr-management.md for commits and PRs.
+4. Follow docs/contributing/error-handling.md for error types.
+5. Follow docs/contributing/pr-management.md for commits and PRs.
 
 ## Commit Attribution
 

diff --git a/README.md b/README.md
@@ -85,7 +85,7 @@ SENTRY_HOST=                 # For self-hosted deployments
 MCP_DISABLE_SKILLS=          # Disable specific skills (comma-separated, e.g. 'seer')
 ```
 
-**Important:** Always set `EMBEDDED_AGENT_PROVIDER` to explicitly specify your LLM provider. Auto-detection based on API keys alone is deprecated and will be removed in a future release. See [docs/embedded-agents.md](docs/embedded-agents.md) for detailed configuration options.
+**Important:** Always set `EMBEDDED_AGENT_PROVIDER` to explicitly specify your LLM provider. Auto-detection based on API keys alone is deprecated and will be removed in a future release. See [docs/operations/embedded-agents.md](docs/operations/embedded-agents.md) for detailed configuration options.
 
 #### Example MCP Configuration
 
@@ -228,8 +228,8 @@ pnpm -w run cli --access-token=TOKEN "query"
 Note: The CLI defaults to `http://localhost:5173`. Override with `--mcp-host` or set `MCP_URL` environment variable.
 
 **Comprehensive testing playbooks:**
-- **Stdio testing:** See `docs/testing-stdio.md` for complete guide on building, running, and testing the stdio implementation (IDEs, MCP Inspector)
-- **Remote testing:** See `docs/testing-remote.md` for complete guide on testing the remote server (OAuth, web UI, CLI client)
+- **Stdio testing:** See `docs/testing/stdio.md` for complete guide on building, running, and testing the stdio implementation (IDEs, MCP Inspector)
+- **Remote testing:** See `docs/testing/remote.md` for complete guide on testing the remote server (OAuth, web UI, CLI client)
 
 ## Development Notes
 

diff --git a/TELEMETRY.md b/TELEMETRY.md
@@ -267,16 +267,16 @@ Attributes: `gen_ai.provider.name`, `gen_ai.request.model`,
   full request bodies, or other high-cardinality or sensitive values.
 - Do not log secrets. Authorization headers and access tokens must remain
   scrubbed.
-- Update this document, `docs/monitoring.md`, and the relevant semantic lookup
+- Update this document, `docs/operations/monitoring.md`, and the relevant semantic lookup
   data file under `packages/mcp-core/src/internal/agents/tools/data/` when
   adding or renaming telemetry fields. Do not add unit tests solely to assert
   telemetry attribute spelling.
 
 ## References
 
-- `docs/monitoring.md`
-- `docs/oauth-signout-playbook.md`
-- `docs/error-handling.md`
+- `docs/operations/monitoring.md`
+- `docs/operations/oauth-signout-playbook.md`
+- `docs/contributing/error-handling.md`
 - `packages/mcp-cloudflare/src/server/metrics.ts`
 - `packages/mcp-cloudflare/src/server/oauth/helpers.ts`
 - `packages/mcp-core/src/internal/agents/tools/data/mcp.json`

diff --git a/docs/README.md b/docs/README.md
@@ -1,26 +1,75 @@
 # Contributor Docs
 
-This directory contains contributor documentation used by humans and LLMs. To avoid duplication, the canonical documentation map and contributor workflow live in `CLAUDE.md` (also available as `AGENTS.md`).
+This directory contains contributor documentation used by humans and LLMs. The
+canonical workflow and required docs live in [../AGENTS.md](../AGENTS.md)
+(`CLAUDE.md` is a symlink to the same file).
 
-## Purpose
+## Start Here
 
-- Central home for all contributor-focused docs (.md files)
-- Consumed by tools (e.g., Cursor) via direct file references
+- Tool implementation: [contributing/adding-tools.md](contributing/adding-tools.md)
+- Tool output policy: [contributing/tool-responses.md](contributing/tool-responses.md)
+- Testing: [testing/overview.md](testing/overview.md)
+- Shared implementation patterns: [contributing/common-patterns.md](contributing/common-patterns.md)
 
-## Start Here
+## Topic Map
+
+### Contributing
+
+- [contributing/adding-tools.md](contributing/adding-tools.md) - Tool structure, visibility, implementation, and registration
+- [contributing/api-patterns.md](contributing/api-patterns.md) - Sentry API client and MSW patterns
+- [contributing/coding-guidelines.md](contributing/coding-guidelines.md) - TypeScript and code style guidance
+- [contributing/common-patterns.md](contributing/common-patterns.md) - Shared Zod, validation, and formatting patterns
+- [contributing/documentation-style-guide.md](contributing/documentation-style-guide.md) - Documentation style guide
+- [contributing/error-handling.md](contributing/error-handling.md) - Error hierarchy and propagation
+- [contributing/pr-management.md](contributing/pr-management.md) - Commit and PR guidelines
+- [contributing/quality-checks.md](contributing/quality-checks.md) - Quality gates and pre-commit checks
+- [contributing/search-events-api-patterns.md](contributing/search-events-api-patterns.md) - Search Events API guidance
+- [contributing/tool-responses.md](contributing/tool-responses.md) - User-facing tool output policy, snapshot review, and QA expectations
+
+### Testing
+
+- [testing/overview.md](testing/overview.md) - Unit, snapshot, eval, and agent CLI testing
+- [testing/stdio.md](testing/stdio.md) - Stdio transport testing
+- [testing/remote.md](testing/remote.md) - Remote server and OAuth testing
+
+### Architecture And Operations
+
+- [architecture/overview.md](architecture/overview.md) - System design
+- [operations/embedded-agents.md](operations/embedded-agents.md) - Embedded LLM provider configuration
+- [operations/github-actions.md](operations/github-actions.md) - GitHub Actions guidance
+- [operations/logging.md](operations/logging.md) - Logging guidance
+- [operations/monitoring.md](operations/monitoring.md) - Monitoring guidance
+- [operations/oauth-signout-playbook.md](operations/oauth-signout-playbook.md) - Remote OAuth diagnostic runbook
+- [operations/security.md](operations/security.md) - Authentication and security patterns
+- [operations/stdio-auth.md](operations/stdio-auth.md) - Device code auth and token caching
+- [operations/token-cost-tracking.md](operations/token-cost-tracking.md) - Tool definition token cost tracking
+
+### Cloudflare
+
+- [cloudflare/overview.md](cloudflare/overview.md) - Cloudflare package overview
+- [cloudflare/architecture.md](cloudflare/architecture.md) - Cloudflare architecture
+- [cloudflare/oauth-architecture.md](cloudflare/oauth-architecture.md) - Cloudflare OAuth architecture
+
+### Integrations
 
-- Doc map and workflow: see `CLAUDE.md` / `AGENTS.md`
-- Per-topic guides live in this folder (e.g., `adding-tools.md`)
+- [integrations/claude-code-plugin.md](integrations/claude-code-plugin.md) - Plugin structure and agent prompts
+- [integrations/flue-hooks.md](integrations/flue-hooks.md) - Flue hook notes
+- [integrations/ide-instructions-refactor.md](integrations/ide-instructions-refactor.md) - IDE instruction refactor notes
 
-## Integration with Tools
+### Specs
 
-- Cursor IDE: this folder is referenced directly as contextual rules
-- Other AI tools: reference specific `.md` files as needed
+- [specs/README.md](specs/README.md) - Specs index
+- [specs/embedded-agent-openai-routing.md](specs/embedded-agent-openai-routing.md) - Embedded agent OpenAI routing spec
+- [specs/search-events.md](specs/search-events.md) - Search Events spec
+- [specs/subpath-constraints.md](specs/subpath-constraints.md) - Subpath constraints spec
 
-## LLM-Specific
+### Releases
 
-- Meta-docs live under `llms/` (e.g., `llms/document-scopes.md`)
+- [releases/stdio.md](releases/stdio.md) - npm package release
+- [releases/cloudflare.md](releases/cloudflare.md) - Cloudflare deployment
 
 ## Maintenance
 
-Update docs when patterns change, new tools are added, or common issues arise. Keep the index in `CLAUDE.md` authoritative; avoid mirroring it here.
+Update docs when patterns change, new tools are added, or common issues arise.
+Prefer cross-links over duplicated guidance: topic docs should link to the
+canonical policy or pattern that owns the detail.
diff --git a/docs/architecture.md → docs/architecture/overview.md b/docs/architecture.md → docs/architecture/overview.md
@@ -74,7 +74,7 @@ A separate web chat application that uses the MCP server.
 
 **Note**: This is NOT part of the MCP server itself - it's a demonstration of how to build a chat interface that consumes MCP.
 
-See "Overview" in @docs/cloudflare/overview.md for details.
+See "Overview" in [Cloudflare Overview](../cloudflare/overview.md) for details.
 
 ### packages/mcp-server-evals
 

diff --git a/docs/cloudflare/architecture.md b/docs/cloudflare/architecture.md
@@ -183,7 +183,7 @@ SENTRY_CLIENT_SECRET = "..." # OAuth app secret
 
 ## Related Documentation
 
-- See "OAuth Architecture" in @docs/cloudflare/oauth-architecture.md
-- See "Chat Interface" in @docs/cloudflare/architecture.md
-- See "Deployment" in @docs/cloudflare/deployment.md
-- See "Architecture" in @docs/architecture.md
+- See "OAuth Architecture" in [OAuth Architecture](oauth-architecture.md)
+- See "Chat Interface" in this document
+- See "Deployment" in [Cloudflare Release](../releases/cloudflare.md)
+- See "Architecture" in [Architecture Overview](../architecture/overview.md)
diff --git a/docs/cloudflare/overview.md b/docs/cloudflare/overview.md
@@ -35,13 +35,13 @@ Think of it as:
 
 ## Documentation Structure
 
-- Architecture: @docs/cloudflare/architecture.md — Technical architecture of the web application
-- OAuth Architecture: @docs/cloudflare/oauth-architecture.md — OAuth flow and token management
-- Chat Interface: @docs/cloudflare/architecture.md — See "Chat Interface" section
-- Deployment: @docs/cloudflare/deployment.md — Deploying to Cloudflare Workers
+- Architecture: [Cloudflare Architecture](architecture.md) - Technical architecture of the web application
+- OAuth Architecture: [OAuth Architecture](oauth-architecture.md) - OAuth flow and token management
+- Chat Interface: [Cloudflare Architecture](architecture.md) - See "Chat Interface" section
+- Deployment: [Cloudflare Release](../releases/cloudflare.md) - Deploying to Cloudflare Workers
 
 ## Quick Links
 
 - Live deployment: https://mcp.sentry.dev
 - Package location: `packages/mcp-cloudflare`
-- **For MCP Server docs**: See "Architecture" in @docs/architecture.md
+- **For MCP Server docs**: See "Architecture" in [Architecture Overview](../architecture/overview.md)
diff --git a/docs/adding-tools.md → docs/contributing/adding-tools.md b/docs/adding-tools.md → docs/contributing/adding-tools.md
@@ -178,14 +178,22 @@ async handler(params, context: ServerContext) {
 
 ### Response Formatting
 
-See [common-patterns.md](common-patterns.md#response-formatting) for:
-- Markdown structure
-- ID/URL formatting
-- Response notes guidance
+Tool responses must follow [tool-responses.md](tool-responses.md). In
+particular:
+
+- Format output as user-facing markdown, not raw upstream API payloads.
+- Include actionable IDs and URLs when they support navigation or follow-up tool
+  calls.
+- Omit internal implementation details, empty placeholder values, and raw JSON
+  unless the tool explicitly exists to return raw data.
+- Keep response notes scoped to this result.
+
+See [common-patterns.md](common-patterns.md#response-formatting) for shared
+formatting patterns and examples.
 
 ## Step 3: Add Tests
 
-Follow comprehensive testing patterns from `testing.md` for unit, integration, and evaluation tests.
+Follow comprehensive testing patterns from [../testing/overview.md](../testing/overview.md) for unit, integration, and evaluation tests.
 
 Create `packages/mcp-core/src/tools/catalog/your-tool-name.test.ts`:
 
@@ -214,12 +222,14 @@ describe("your_tool_name", () => {
 ```
 
 **Testing Requirements:**
-- Input validation (see [testing.md](testing.md#testing-error-cases))
+- Input validation (see [../testing/overview.md](../testing/overview.md#testing-error-cases))
 - Error handling (use patterns from [error-handling.md](error-handling.md))
 - Output formatting with snapshots
 - At least one happy-path test must snapshot the full formatted handler
   response with `toMatchInlineSnapshot()`; partial `toContain()` assertions are
   supplemental only
+- Review snapshots against [tool-responses.md](tool-responses.md), including
+  checks for internal IDs, raw JSON, empty placeholders, and user-facing labels
 - API integration with MSW mocks
 
 **After changing output, update snapshots:**
@@ -470,8 +480,9 @@ This pattern works with both Cloudflare-hosted and stdio transports.
 
 - Error handling: [error-handling.md](error-handling.md)
 - API usage: `api-patterns.md`
-- Testing: `testing.md`
-- Response formatting: [common-patterns.md](common-patterns.md#response-formatting)
+- Testing: [../testing/overview.md](../testing/overview.md)
+- Response policy: [tool-responses.md](tool-responses.md)
+- Formatting patterns: [common-patterns.md](common-patterns.md#response-formatting)
 
 ## References
 

diff --git a/docs/api-patterns.md → docs/contributing/api-patterns.md b/docs/api-patterns.md → docs/contributing/api-patterns.md
@@ -19,7 +19,9 @@ const api = new SentryApiService({
 });
 ```
 
-See: `packages/mcp-server/src/api-utils.ts` and `adding-tools.md#step-2-implement-the-handler` for usage in tools.
+See `packages/mcp-server/src/api-utils.ts` and
+[adding-tools.md](adding-tools.md#step-2-implement-the-handler) for usage in
+tools.
 
 ### Common Operations
 
@@ -79,11 +81,11 @@ const FlexibleSchema = BaseSchema
 z.union([DateSchema, z.null()])
 ```
 
-See Zod patterns: `common-patterns.md#zod-schema-patterns`
+See Zod patterns in [common-patterns.md](common-patterns.md#zod-schema-patterns).
 
 ### Type Safety
 
-For testing API patterns, see `testing.md#mock-server-setup`
+For testing API patterns, see [../testing/overview.md](../testing/overview.md#mock-server-setup).
 
 ```typescript
 // Derive types from schemas
@@ -202,7 +204,7 @@ try {
 }
 ```
 
-See error patterns: `common-patterns.md#error-handling`
+See error patterns in [common-patterns.md](common-patterns.md#error-handling).
 
 ## Best Practices
 
@@ -217,4 +219,4 @@ See error patterns: `common-patterns.md#error-handling`
 - API Client: `packages/mcp-server/src/api-client/`
 - Mock handlers: `packages/mcp-server-mocks/src/handlers/`
 - Fixtures: `packages/mcp-server-mocks/src/fixtures/`
-- API Utils: `packages/mcp-server/src/api-utils.ts`
+- API Utils: `packages/mcp-server/src/api-utils.ts`