tracer-cloud--opensre/docs/tool-placement-policy.md

Tool placement policy (T-20)

Where a piece of agent-callable capability lives is decided by how many vendor integrations its domain logic touches, not by convenience or file size. This is the decision rule referenced from ARCHITECTURE.md.

Decision rule

Ask: does this tool's purpose depend on a specific external vendor or SaaS backend (an integrations/<vendor>/ package)?

1. Single vendor → integrations/<vendor>/tools/. The tool only makes sense in terms of one vendor's domain (a Datadog query, a GitHub mutation, a Sentry issue lookup). This is the default, most common case — see "Adding a Tool" in AGENTS.md.
2. No vendor at all → tools/system/. The tool's domain purpose has nothing to do with an external vendor — local process introspection, sandboxed code execution, RAG-style guidance retrieval. An incidental import of a vendor client for a side concern (e.g. resolving one of several possible credential sources, or picking a notification channel for delivery) does not make a tool vendor-specific; the test is the tool's reason to exist, not every import in the file.
3. Genuinely spans 2+ vendor integrations → tools/cross_vendor/. The tool's logic itself correlates or orchestrates across multiple integrations/<vendor>/ packages — e.g. fix_sentry_issue reads from integrations.sentry and hands the fix to integrations.pi. This is the narrow bucket; don't reach for it just because a tool happens to format its output for a second vendor (e.g. "Slack-ready" report text is still single-vendor logic, not cross-vendor).
4. True surface-level (CLI + REPL) duplication, not tool logic at all → surfaces/shared/ (see T-21). This is a different axis entirely — it's about presentation code two surfaces both need, not about where an agent-callable tool's business logic lives.

tools/ also holds framework subsystems that aren't individual tools — tools/investigation (the investigation pipeline), tools/interactive_shell (REPL action tools), tools/registry.py (the tool registry itself). These stay at the top level of tools/; the system / cross_vendor split only applies to individual tool packages.

Current state (as of T-19)

Applied to the pre-existing top-level tools/ packages:

Package	Placement	Why
tools/system/fleet_monitoring/	system	Local AI-agent fleet monitoring; no vendor.
tools/system/python_execution_tool/	system	Generic sandboxed Python execution; the GitHub token import is one of several optional credential sources, not the tool's purpose.
tools/system/sre_guidance_tool/	system	Local knowledge-base retrieval; no vendor.
tools/system/watch_dog/	system	CLI/REPL process monitoring; Telegram is only the alarm-delivery channel, not the tool's domain.
tools/cross_vendor/fix_sentry_issue/	cross_vendor	Reads a Sentry issue and hands the fix to the Pi coding agent — two integrations/ packages in one tool's logic.

Left as-is, not yet migrated (single-vendor tools that predate the vendor-first tool layout and belong under integrations/<vendor>/tools/, not tools/system/ or tools/cross_vendor/):

• tools/community_followup_tool/, tools/git_deploy_timeline_tool/, tools/work_status_report_tool/ — GitHub-only.
• tools/slack_send_message_tool/ — Slack-only.
• tools/pi_coding_tool/ — Pi-only.

Migrating these to integrations/<vendor>/tools/ is in scope for T-18 (full vendor-first completion), not this policy change — moving them into tools/system/ or tools/cross_vendor/ now would misclassify them.

Registry mechanics

tools/system/ and tools/cross_vendor/ are ordinary packages discovered by tools/registry.py's top-level walk of tools/. Each declares a TOOL_MODULES tuple in its __init__.py (the same manifest mechanism tools/slack_send_message_tool/__init__.py already uses for its own tool submodule) listing the tool packages nested one level inside it. Adding a new system or cross-vendor tool means adding its package name to the relevant TOOL_MODULES tuple — no registry code changes required.