mssql_manage_query

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

With no annotations, the description carries the behavioral disclosure burden. It does state what each operation does, including that reset_stats clears statistics, which hints at mutating behavior. But it does not warn that reset_stats is destructive, that explain with analyze=true executes the query, or that some operations may require elevated permissions.

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 a single dense sentence that front-loads the tool's purpose and then lists all four operations with their purposes. It wastes no words, though the long dash-separated enumeration could benefit from a more structured format for readability.

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?

The description gives a sufficient high-level operation map for a 15-parameter dispatcher tool, and the rich schema fills in most invocation details. It lacks guidance on output shape, side effects, connection requirements, and when to choose this tool over database-level analysis tools, so it is complete enough only in combination with the schema.

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 input schema already documents every parameter, including enums, defaults, and operation-specific applicability. The tool description adds no parameter-level detail, which is acceptable given the strong schema coverage.

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 maps the tool to SQL Server query analysis and performance and enumerates four concrete operations: explain, get_slow_queries, get_stats, and reset_stats. It is much more specific than a mere restatement of the tool name, though it does not explicitly differentiate it from overlapping siblings like mssql_analyze_database or mssql_monitor_database.

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?

Each operation has an implied use case ('operation="explain" for execution plans', 'operation="get_slow_queries" for slow query analysis'), which gives reasonable context. However, there is no explicit guidance about when to use this tool instead of related siblings, nor any when-not-to-use or exclusion notes.

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