pg_outliers

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the tool helps 'identify opportunities for performance optimization' and 'track query statistics over time', which implies read-only analysis, but doesn't explicitly state whether it's safe (non-destructive) or has side effects. It doesn't disclose that the 'reset' parameter can modify database statistics (a behavioral trait), nor does it cover permissions, rate limits, or output format. For a tool with parameters that can reset data, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded: it starts with the core purpose ('Identify resource-intensive database operations'), then lists four specific use cases in a bullet-like format, and ends with a summary sentence. Every sentence adds value by clarifying when and why to use the tool. There's no redundant or vague language, though it could be slightly more structured (e.g., separating purpose from guidelines more clearly).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (performance analysis with potential side effects via 'reset'), lack of annotations, and no output schema, the description is moderately complete. It covers the 'why' and high-level 'when' but misses critical behavioral details (e.g., that 'reset' modifies data, what the output looks like). For a tool with 5 parameters and no structured safety hints, it should do more to explain risks and results, leaving gaps in contextual understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all five parameters thoroughly (e.g., 'app' for Heroku app name, 'reset' for resetting statistics). The description doesn't add any parameter-specific information beyond what's in the schema—it focuses on high-level use cases instead. With high schema coverage, the baseline is 3, as the description doesn't compensate with extra semantic context but doesn't detract either.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Identify resource-intensive database operations' and lists specific use cases (find slow queries, analyze performance patterns, optimize workload, track statistics). It distinguishes itself from sibling tools by focusing on database performance analysis rather than app management, deployment, or other pg_* operations like backups or maintenance. However, it doesn't explicitly differentiate from all pg_* tools (e.g., pg_locks, pg_ps) in the same domain.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides implied usage guidelines by listing four scenarios when to use the tool (e.g., 'Find slow or expensive queries', 'Optimize database workload'). However, it doesn't explicitly state when NOT to use it or name alternatives among the many sibling tools (e.g., pg_locks for lock analysis, pg_ps for process listing, or get_app_logs for broader app monitoring). The guidance is helpful but lacks exclusion criteria or direct sibling comparisons.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.