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

Annotations declare readOnlyHint=true and idempotentHint=true, but the description says 'Only its fingerprint and optional artifact reference are persisted,' indicating a durable write. This directly contradicts the read-only annotation.

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?

Two short sentences deliver the core action and persistence behavior with minimal verbosity.

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 tool has six parameters and an output schema, but the description's brevity plus the contradiction leaves usage ambiguity. The persistence note is useful, yet the read-only annotation undermines trust in the description's completeness.

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?

The schema covers 67% of parameters with descriptions, including strategy enum and artifact_ref requirements. The tool description itself adds no parameter-level detail for database_name or idempotency_key; the fingerprint persistence note is tangential.

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?

States a specific action ('Add one concrete rewrite or index experiment') targeting an existing tuning session, clearly distinct from session creation or benchmarking. The 'fingerprint' note emphasizes a lightweight candidate record.

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?

No explicit when-to-use or alternatives listed. Context implies use within an active tuning session, but there is no direct comparison to benchmarking or session tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the 'operational' qualifier and the performance-triage exclusion, but these are more about scope than behavioral traits like return format or edge cases. It doesn't contradict annotations, but the added value beyond annotations is modest.

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 two sentences, front-loaded with the primary purpose and immediately redirecting to a sibling tool. Every sentence earns its place with no redundant or vague wording.

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 output schema exists and annotations are strong, the description is sufficient for a health-analysis tool. It doesn't explicitly enumerate health dimensions, but the input schema's health_type parameter covers that. The main gap is the absence of broad usage context, but it's not critical given the available structured information.

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?

The schema description coverage is 67%, with health_type and database_name having descriptions. The description itself does not add parameter details, leaving decision_id undocumented beyond its default null. Since the schema covers most parameters adequately and the missing one is optional, the description adds marginal value but doesn't fully compensate for the gap.

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 as analyzing operational Azure SQL database health, which is a specific verb+resource pair. It also distinguishes itself from collect_performance_evidence by explicitly noting that query-performance triage belongs to that alternative tool, ensuring the agent can differentiate between them.

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 an explicit exclusion: 'Query-performance triage belongs to collect_performance_evidence', which tells the agent when not to use this tool and names the correct alternative. However, it doesn't offer broader guidance on when to use this tool versus other health-related siblings, so it's not fully comprehensive.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description simply repeats the read-only nature with 'Analyze' but adds no further behavioral context, such as outputs or side effects. No contradiction exists.

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?

One sentence with no filler. It immediately states the purpose and front-loads the key verb and resource.

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 tool is simple and well-annotated, with an output schema present. The description is sufficient for basic understanding but could provide more context on what recommendations entail or how to interpret results, especially given the large set of sibling tools.

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?

The schema provides a full description for the single optional parameter database_name, including its default value. The tool description adds no additional parameter semantics, but the baseline of 3 applies due to high 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 states 'Analyze missing-index and automatic tuning recommendations,' which uses a specific verb ('Analyze') and identifies the exact resource type (missing-index and auto-tuning recommendations). This distinguishes it from sibling tools that analyze query or workload indexes.

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 no guidance on when to use this tool versus alternatives. An agent cannot determine from the description alone whether to choose this over analyze_query_indexes or optimize_indexes. No prerequisites, exclusions, or recommended contexts are given.

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

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

The description adds significant behavioral nuance beyond the annotations: it explains the meaning of a zero missing_index_count, the possibility of empty filtered recommendations due to existing covered indexes, and explicitly warns that neither condition proves no index could improve the query. This is valuable interpretive guidance.

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?

Two sentences, front-loaded with the main purpose, and each sentence earns its place. The second sentence provides a critical interpretation caveat without unnecessary verbosity.

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 output schema exists and annotations cover safety, the description sufficiently explains scope, expected results, and a key edge case. It is complete for its complexity and does not need to duplicate structured fields.

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?

Input schema coverage is 100%, so the baseline is 3. The description does not add any parameter-specific semantics beyond the schema (e.g., it doesn't explain database_name or auto_bind_params), and the 'up to 10 queries' limit is already present in the schema's maxItems constraint.

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 states a specific verb+resource ('Extract SQL Server missing-index hints from estimated plans') and clearly scopes it to up to 10 queries. The per-query focus distinguishes it from workload-level sibling tools such as analyze_workload_indexes.

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?

Clear context is provided: it handles up to 10 queries individually and uses estimated plans. However, it does not explicitly name alternatives or state when not to use this tool, leaving exclusions implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by explaining that the tool identifies resource-intensive queries and recommends indexes, which gives a clearer idea of what the analysis produces beyond what annotations state.

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, front-loaded sentence that clearly communicates the tool's purpose without unnecessary words. It is concise and well-structured.

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?

With a complete parameter schema, annotations for read-only safety, and an output schema present, the description is adequately complete for a read-only analysis tool. It could be slightly more explicit about how it differs from similar index-related siblings, but the overall context is sufficient.

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% for all three parameters (top_n, database_name, window_minutes), each with its own description. The tool description does not add parameter-specific meaning beyond what the schema already provides, so the baseline of 3 applies.

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 function: analyze the database workload, identify resource-intensive queries, and recommend optimal indexes. It uses a specific verb and resource, and distinguishes from siblings like analyze_query_indexes by focusing on workload-level analysis.

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 implies usage for workload-level index analysis (e.g., when you need to analyze the overall database workload), but it does not explicitly state when to use this tool versus alternatives like analyze_index_recommendations or optimize_indexes. No exclusions or alternative guidance is provided.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds that cleanup is automatic and cleanup failures are durable, which is valuable behavioral context. It doesn't contradict the annotations.

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?

Two sentences, each providing distinct value: purpose and cleanup behavior. No redundancy or fluff.

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?

With 17 parameters, an output schema, and multiple phases, the description is high-level but leaves out significant invocation details such as the phase parameter, idempotency key usage, and filter definition. However, the schema and output schema compensate somewhat.

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?

Description provides no parameter-level detail; schema covers about 65% of parameters with descriptions, leaving several (online, is_unique, decision_id, database_name, lease_minutes, include_columns) unexplained. The description does not compensate for this gap.

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 specifies 'Benchmark a leased disposable index in a policy-allowlisted sandbox,' clearly identifying the verb (benchmark), resource (index candidate), and sandbox context. This distinguishes it from sibling tools like benchmark_tuning_candidate or benchmark_query_rewrite by focusing on a leased disposable index.

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 conveys that this is for benchmarking a temporary index in a safe sandbox, implying a testing use case, but it lacks explicit guidance on when to use versus alternatives like benchmark_tuning_candidate or what prerequisites exist. It also doesn't mention the screening/finalist phases from the schema.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description need not restate safety. It adds meaningful behavioral context by explaining the methodology: executing both queries on the same typed read-only path, interleaving actual-plan samples, and verifying complete bounded snapshot equivalence. This goes beyond annotations by disclosing the comparison approach and the nature of the benchmark, though it stops short of detailing every execution side-effect.

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, well-structured sentence that front-loads the primary action ('Benchmark') and packs essential details efficiently without redundancy. Every clause adds value, making it appropriately concise.

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 complexity (10 parameters) and the presence of a detailed schema with 100% coverage, the description is fairly complete. It communicates the core purpose and high-level behavior, but could be more robust by explicitly positioning the tool within the workflow (e.g., when to use versus benchmarking tuning/index candidates). Overall, it provides enough context for an agent to infer when and how to invoke it, especially with the schema's supplementary details.

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 baseline is 3. The description does not add significant parameter-specific meaning; it refers overall to the benchmarking process rather than individual parameters. The schema already has rich descriptions for all 10 parameters (e.g., 'runs' explains medians, 'analyze' captures plans), so the description's contribution is marginal.

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 verb and resource: 'Benchmark a baseline query against a proposed rewrite'. It distinguishes from siblings like 'benchmark_tuning_candidate' and 'benchmark_index_candidate' by focusing on query rewrites, and includes specific methodological details (typed read-only path, interleaved plan samples, snapshot equivalence) that define its scope.

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 use case is implied: benchmark a rewrite against a baseline. However, there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The description implies usage for query rewrites but does not state 'use this when...' or mention alternatives. The parameter descriptions in the schema provide some conditional guidance (e.g., 'compare_order'), but the main description lacks explicit usage context.

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

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

Annotations already indicate read-only and non-destructive, so the bar is lower. The description adds behavioral context by disclosing interleaved exactly-once sampling and snapshot-consistent duplicate-aware result comparison, which explains how execution occurs without contradicting the annotations.

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 core action and then specifies the key methodological details. No filler words.

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?

For a tool with 12 parameters and an output schema, the description provides a high-level summary of purpose and method. It doesn't mention required session/candidate identifiers, but those are evident from the schema. The presence of an output schema reduces the need to describe return values. Some context on the benchmarking process is omitted, but the description is adequate.

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 67%, with most parameters individually described in the schema. The tool description itself does not explain any parameters, but the schema's descriptions for parameters like runs, phase, and prove_equivalence carry that burden. Thus, the description adds no extra parameter semantics but doesn't need to.

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 uses a specific verb 'Benchmark' and identifies the resource as 'one rewrite candidate', distinguishing it from sibling tools like benchmark_index_candidate. It also specifies the methodology (interleaved, exactly-once samples, snapshot-consistent comparison), making the purpose unambiguous.

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 clearly indicates this tool is for benchmarking a single rewrite candidate, which provides context vs. siblings like benchmark_query_rewrite. However, it does not explicitly state when to use this vs alternatives or mention exclusions, so it stops short of full usage guidelines.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds 'point-in-time' but doesn't explain whether the snapshot is stored, returned, or purely transient. It doesn't contradict annotations, but also doesn't add significant behavioral detail beyond them.

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, well-constructed sentence with no redundancy or irrelevant information. It front-loads the action and resource effectively.

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 rich annotations and full parameter documentation, the description is adequate but minimal. It leaves open the exact nature of the snapshot (return vs. persistence) and doesn't tie into its workflow context relative to sibling tools like compare_schemas. The presence of an output schema likely covers return details, but the description alone is sparse.

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%, with both parameters (database_name and schema_filter) already documented. The description adds no extra parameter context, so it neither enhances nor detracts from the schema's clarity.

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 uses a specific verb ('Capture') and a clear resource ('schema snapshot for a database'), with the qualifier 'point-in-time' adding precision. This distinguishes it from sibling tools like list_schemas or compare_schemas, making the tool's purpose immediately clear.

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 no guidance on when to use this tool versus alternatives. There is no mention of alternatives, prerequisites, or typical scenarios, leaving the agent to infer usage context from the name and sibling list.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description only adds 'probe' and 'permission-sensitive features,' which aligns with the read-only nature but does not disclose additional behavioral details like exact checks performed or permission requirements, providing minimal value beyond the annotations.

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, front-loaded sentence with no redundant or filler content. Every word contributes to conveying the tool's core purpose, making it highly concise and well-structured.

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?

For a simple read-only tool with one optional parameter, strong safety-related annotations, and an output schema, the description is minimally adequate. However, it does not explain what specific capabilities or permission-sensitive features will be probed, leaving some ambiguity about the tool's exact coverage. This represents a clear but tolerable gap.

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?

The schema contains a single parameter (database_name) with a complete description and default value, achieving 100% schema description coverage. The tool description does not add meaning to the parameter, but since the schema already documents it fully, a baseline score of 3 is appropriate.

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 with a specific verb ('Probe') and resource ('Azure SQL capabilities and permission-sensitive features') tied to a database. This distinguishes it from sibling diagnostic tools, which focus on performance, indexes, or schemas.

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 implies usage when you need to inspect database capabilities or permission-sensitive features, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. Since context is clear but no alternatives are mentioned, it falls at the baseline for implied guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds value by disclosing that it does not return raw definitions, only analysis, and notes recursive view resolution, which are behavioral traits beyond the annotations.

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, short sentence that conveys purpose, scope, and key behavioral constraint without unnecessary words. It is front-loaded and efficient.

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?

With an output schema present, the description does not need to explain return values. It covers purpose and key behavior. However, it omits any guidance on the optional database_name parameter and does not mention when to use this over alternatives, leaving minor gaps for a tool with two parameters.

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 coverage is 50% (sql described, database_name not). The description mentions 'direct SQL' and 'recursively resolved view definitions', which partly aligns with the sql parameter, but it does not clarify the role of database_name or provide any additional meaning for that parameter. The description largely repeats the schema's sql description.

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 uses specific verb 'Analyze' with clear objects 'direct SQL and recursively resolved view definitions' and states the goal 'semantic-equivalence proof risks'. It clearly distinguishes from sibling tools that compare results or plans, and the phrase 'without returning raw definitions' adds specificity.

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 term 'preflight' implies use before an equivalence proof or transformation, but the description does not explicitly state when to use this tool versus alternatives like 'compare_query_results' or 'explain_query'. It provides clear context but no exclusions or alternative tools.

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

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

Annotations already declare read-only and idempotent behavior. The description adds valuable context that the tool is 'DB-free', meaning it does not rely on a database connection, and mentions contract fingerprints, which imply a stable and predictable output structure. This goes beyond the annotations.

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?

A single, well-structured sentence that front-loads the action ('Return') and lists the three output categories. Every word earns its place, with no filler or repetition.

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?

For a zero-argument status tool with a strong annotation set and an output schema (indicated by has_output_schema=true), the description provides all necessary context: what is returned and that it is server-process-scoped. No additional details are needed.

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?

The tool has zero parameters, so the schema description covers 100% trivially. There is no parameter complexity to explain. The baseline of 4 applies here as the description correctly focuses on the return payload rather than parameters.

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 returns specific items: runtime identity, registered-tool capabilities, and contract fingerprints. The verb 'Return' is specific, and the scope 'for this MCP server process' distinguishes it from sibling tools like check_capabilities, which likely only covers capabilities.

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?

No guidance is provided on when to use this tool versus alternatives such as check_capabilities or other status-related tools. The description implies general runtime status checking but does not state explicit use cases, prerequisites, or exclusions.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the description only needs to add behavioral context. It specifies the health criteria (stale, high modification, low sample rates) and the flagging outcome, which is useful but doesn't go beyond what annotations and schema already cover. No contradiction.

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 sentence that packs the purpose, criteria, and outcome efficiently. No redundant words, front-loaded with the action.

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 tool is well-covered by annotations (read-only) and an output schema. The description adds the core logic of the health check. It could mention that it doesn't modify anything, but annotations already handle that. It's complete for a diagnostic tool.

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 coverage is 100%, with descriptions for all three parameters. The tool description mentions 'stale stats' and 'high modification counts' which map to stale_days and mod_pct_threshold, but doesn't add extra meaning beyond the schema. The 'low sample rates' check is not parameterized but is a behavioral detail, not a param semantic.

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 identifies the tool's purpose as checking statistics health by examining stale stats, high modification counts, and low sample rates, and it flags stats needing update. This is specific enough to distinguish from generic stats retrieval, though it doesn't explicitly contrast with sibling tools.

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 clear context for when to use this tool (when you need to assess statistics health before updating), but it does not explicitly state alternatives or exclusions. The presence of siblings like get_table_stats and analyze_db_health implies alternatives, but the description doesn't reference them.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows the tool is safe and read-only. The description adds no behavioral details beyond listing evidence types; it does not disclose potential execution of the query when execute_query=true or require special policies. With annotations covering the safety profile, the description provides minimal additional value, so a score of 3 is appropriate.

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, front-loaded sentence: 'Collect Azure SQL resource, Query Store, wait, blocking, statistics, parameter-sensitivity, and regression evidence for a performance case.' It is concise, contains no fluff, and efficiently conveys a large amount of scope information. Every word earns its place, making it highly scannable.

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 tool has 9 parameters, an output schema, and a clear relationship to a performance-case workflow. The description gives the high-level purpose but omits contextual details such as the connection to start_performance_case, the general output structure, or how the evidence categories relate. The output schema and annotations reduce the burden, but for a tool of this complexity, the description leaves notable gaps, earning a 3.

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 56%, meaning several parameters (decision_id, database_name, window_minutes, idempotency_key) have no description in either the schema or the main description. The description itself does not explain any parameter semantics and fails to compensate for the uncovered parameters. Even for covered parameters, the description adds no contextual meaning beyond what the schema already provides.

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 uses a specific verb 'Collect' and names a specific resource ('evidence') with an enumerated list of evidence categories: Azure SQL resource, Query Store, wait, blocking, statistics, parameter-sensitivity, and regression. It explicitly ties the action to 'for a performance case', which distinguishes it from sibling tools that target individual diagnostics (e.g., get_wait_stats, detect_parameter_sniffing). This makes the tool's purpose and scope immediately clear.

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 clearly indicates the tool is for gathering comprehensive evidence in the context of a performance case, implying it is the umbrella collection tool. However, it does not explicitly state when to prefer this over the more specialized sibling tools, nor does it mention exclusions. The context is clear but lacks explicit alternative guidance, so it earns a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds minimal behavioral context beyond naming the inputs (e.g., 'redacted' suggests the summaries are sanitized), but it does not disclose output details, performance implications, or potential side effects. Since annotations cover the key traits, a mid-range score is appropriate.

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, front-loaded sentence that efficiently conveys the core action and inputs. There is no fluff, redundant information, or repeated schema content. It earns a top score for clarity and brevity.

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?

While an output schema exists to document return values, the description does not explain the comparison's purpose or use cases, nor does it clarify when to choose this tool over similar siblings. It also leaves database_name's meaning ambiguous. Given the tool's moderate complexity and the availability of an output schema, the description is minimally adequate but lacks useful context.

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 67%, with baseline_summary and candidate_summary having brief descriptions ('Baseline plan summary.'), but database_name lacks any description. The tool description adds context about what the summaries contain ('execution-plan summaries and sourced metrics'), helping agents understand the input objects' purpose, but it does not clarify the role of database_name. This partial compensation over the schema's sparse parameter info earns a 3.

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 uses a specific verb ('Compare') and clearly identifies the target resources ('arbitrary redacted execution-plan summaries and sourced metrics'). This distinguishes it from sibling tools like compare_query_plans, which focus on raw query plans, and compare_schemas, which focus on schema objects.

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 no guidance on when to use this tool versus alternatives such as compare_query_plans or compare_query_results. It does not state prerequisites, exclusions, or typical use cases, leaving the agent to infer appropriate usage from the name and description alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to repeat safety. It adds valuable behavioral context by specifying the default comparison logic (best vs worst plan by duration) and listing the exact metrics included in the comparison. This enriches the annotation coverage without contradicting it.

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 only two sentences and gets straight to the point. The first sentence states the main action and outputs; the second adds the important default behavior. No filler or redundant information.

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 moderate complexity, the description covers the core purpose, default behavior, and comparison metrics. The output schema exists, so return values are handled separately. It could mention that both plans must belong to the same query_id or how to use one plan ID, but these are implied by the schema and not major gaps.

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 baseline is 3. The description goes beyond the schema by clarifying that the 'best' and 'worst' plan defaults are determined specifically by duration, which is not stated in the parameter descriptions. This adds meaningful context for how plan_id_a and plan_id_b behave when omitted.

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 uses a specific verb ('Compare') and resource ('two query plans side-by-side') and lists concrete comparison dimensions (operators, duration, CPU, I/O). It clearly distinguishes from sibling tools like compare_query_results (which compares result sets) and compare_plan_summaries (which likely summarizes plans). The additional note about defaulting to best vs worst plan by duration further clarifies purpose.

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 clear context: you use this when you need a side-by-side comparison of two query plans with specific metrics. It also explains the default behavior when plan IDs are omitted. However, it does not explicitly mention when not to use it or name alternatives like compare_plan_summaries, so it stops short of a full 5.

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

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

The description adds behavioral context beyond the annotations (readOnlyHint=true, destructiveHint=false) by specifying that results are proven only when complete bounded results, duplicates, shape, and required order match. This clarifies the strictness of comparison, which is valuable and does not contradict annotations.

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 two sentences long, front-loaded with the primary action, and every word contributes meaningful information. There is no redundant or irrelevant text.

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 presence of an output schema and annotations, the description sufficiently conveys the tool's purpose and success criteria. Minor gaps remain (e.g., what 'bounded results' means), but overall it is adequate for a tool with this complexity.

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?

The description does not mention any parameters or their semantics. Schema coverage is 60%, with some parameter descriptions present, but the tool description adds no value for understanding parameters beyond what the schema already provides.

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 compares two read-only query results in one snapshot. It specifies the exact criteria for proof (complete bounded results, duplicates, shape, and required order), which distinguishes it from sibling tools like compare_query_plans and compare_schemas.

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 conveys clear context: use for comparing read-only query results, and the strict matching criteria imply when results are considered equivalent. It does not explicitly name alternatives or exclusions, but the specificity of 'query results' adequately separates it from schema or plan comparisons.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that it returns all differences, but does not disclose what types of differences are included (e.g., tables, views, permissions) or any performance implications. Minimal additional behavioral context beyond annotations.

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 sentence with no wasted words, clearly stating the action and expected output. It is efficiently structured and easy to parse.

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 simplicity, full schema documentation, read-only annotations, and presence of an output schema, the description is adequate. It could be slightly more detailed about the scope of differences, but the schema_filter parameter already covers which schemas are compared, so there is no major gap.

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 coverage is 100% with clear descriptions for source_database, target_database, and schema_filter. The description does not mention parameters or add any insight beyond the schema, so the baseline of 3 applies.

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 uses the specific verb 'compare' with a clear resource ('schemas between two databases') and an explicit outcome ('return all differences'). This clearly distinguishes it from sibling tools like capture_schema_snapshot or generate_migration_script.

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?

No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, exclusions, or typical use cases, and there is no reference to sibling tools that could serve similar purposes.

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

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

Annotations already cover readOnly=false, destructive=false, and idempotent=true. The description adds 'durable' and 'redacted' as behavioral traits, which is useful context beyond the annotations, but it does not detail side effects, error behavior, or return value characteristics.

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, front-loaded sentence with no filler. Every word contributes to the core meaning, and the key verb 'Create' appears immediately.

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?

For a tool with 11 parameters, 7 required, and nested objects, a one-sentence description is insufficient. While an output schema exists, the description does not clarify the role of a handoff in the broader workflow or how this tool relates to sibling tools like resolve_handoff and get_handoff.

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?

The description adds no parameter-level meaning beyond what the schema provides. With only 64% schema description coverage, parameters like idempotency_key, session_id, and database_name remain under-explained, and the description does not compensate for these gaps.

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 action ('Create') and the resource ('cross-skill learning handoff'), and adds distinguishing attributes ('durable, redacted'). It differentiates from sibling tools like get_handoff and resolve_handoff, though the exact nature of a 'handoff' is not elaborated.

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?

No guidance is provided on when to use this tool versus alternatives such as resolve_handoff or get_handoff, nor any workflow context. The description only restates the tool's basic action without explaining prerequisites or when not to use it.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the description's lack of such details is acceptable. The description adds the detection algorithm (ratio threshold) but does not disclose dependencies (e.g., Query Store availability) or return format. This is adequate but not especially rich beyond the annotation baseline.

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, focused sentence that front-loads the core concept and detection logic. It avoids filler and is highly efficient for an agent scanning tool descriptions.

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?

With a clear algorithm, full schema coverage, and strong annotations, the description is nearly complete for a read-only diagnostic tool. It could note prerequisites like 'requires Query Store' but otherwise the agent has enough context to select and invoke the tool correctly.

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?

All four parameters are described in the schema (100% coverage), so the description adds little beyond what is already available. The mention of 'default 10x' mirrors the schema's 'variance_threshold' description, providing no new semantic insight. Baseline 3 is appropriate.

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: to detect parameter sniffing by identifying queries with multiple plans where the ratio of MAX to MIN average duration exceeds a threshold. This specific metric distinguishes it from sibling tools like 'detect_regressed_queries' or 'get_query_parameter_buckets', which focus on different aspects.

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 implies use when parameter sniffing is suspected, but it does not explicitly state when to prefer this tool over alternatives, nor does it mention any exclusions or prerequisites. The usage context is only weakly implied by the tool's name and description.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering safety. The description adds value by naming the specific DMV (sys.dm_db_tuning_recommendations) and the nature of the output (plan forcing scripts), giving the agent a clearer picture of behavior beyond the annotations.

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, front-loaded sentence that is under 20 words and directly states the action and resource. No filler or redundant information.

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?

With an output schema present and read-only annotations, the description covers the essential behavioral context: it surfaces recommendations from a specific DMV and provides scripts. It is complete enough for a simple diagnostic tool, though it could mention prerequisites like automatic tuning being enabled.

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 coverage is 100% (both database_name and window_minutes have descriptions). The tool description adds no further parameter-specific context; it merely provides the overall purpose, so it meets the baseline but doesn't exceed it.

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 uses the specific verb 'Surface' and clearly identifies the resource: automatic tuning regression recommendations from sys.dm_db_tuning_recommendations, including plan forcing scripts. This distinguishes it from siblings like get_top_queries or tune_query, though it doesn't explicitly contrast with them.

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?

No guidance is provided about when to use this tool versus alternatives such as get_top_queries, plan_health_review, or detect_parameter_sniffing. The description states what it does but not the intended scenario or exclusions.

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

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

Description states 'record an audit entry,' implying a non-idempotent side effect, directly contradicting the annotation idempotentHint=true. This creates an inconsistency between the described behavior and the structured metadata, so a score of 1 is warranted.

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?

One sentence, front-loaded with the primary action, and every clause adds meaningful info (preview, reversibility, audit entry, non-execution). No redundancy or padding.

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?

Output schema exists, so return values are covered. However, the description lacks explicit when-to-use guidance and does not resolve the idempotency contradiction. For a dry-run tool among many related siblings, this is adequate but with clear gaps.

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%, with each parameter already described in the schema. The description adds no additional meaning to parameters (e.g., what 'force' or 'unforce' values do in the preview context), so the baseline of 3 is appropriate.

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 uses a specific verb ('Preview') and clearly names the resource and action ('Query Store force/unforce action'), and differentiates from siblings by stating 'without executing it.' It also notes the audit entry recording, which separates it from other preview or analysis tools.

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 implies usage as a non-executing preview, but does not explicitly state when to use it over alternatives like prepare_plan_action or execute_sql. No exclusions or alternative tool references are provided, so guidance remains implicit.

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

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

Beyond annotations (which already indicate read-only and non-destructive), the description adds significant behavioral details: statically validated, row-capped, allowed DECLARE/SET prefixes, exactly one SELECT, and rejection of non-read-only constructs. This enriches the agent's understanding of invocation behavior.

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 concise—two sentences—and front-loaded with the primary action, followed by critical constraints. Every sentence contributes valuable information without redundancy, achieving an optimal length.

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 (SQL execution with validation and constraints), the description is complete for an agent to understand its capabilities and limitations. It covers allowed SQL forms, rejected operations, and row capping. Since an output schema exists, return values do not need elaboration.

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?

While the schema already describes both parameters (sql and database_name), the description adds semantic nuance about the sql parameter by specifying the accepted query structure (optional DECLARE/SET followed by exactly one SELECT). This goes beyond the schema's 'Read-only SQL to execute' and aids correct usage.

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 'Execute statically validated, row-capped read-only SQL', specifying the verb 'execute' and the resource 'SQL' with explicit constraints. It distinguishes itself from sibling tools by emphasizing read-only, row-capped execution, which is unique among the listed tools.

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 clear context that this tool is for read-only SQL execution and explicitly lists what is rejected (DML, DDL, dynamic SQL, stored procedures). However, it does not name alternative tools or offer explicit 'when to use vs. alternatives' guidance, though the exclusions imply when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the 'estimated or actual' execution plan mode, which is useful, but it does not mention that analyze=true will actually execute the query or any other side effects beyond safety. This is a minor addition over what annotations and the schema already convey.

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, focused sentence without redundant words. It front-loads the verb and resource and is appropriately sized for the tool's simplicity at a high level.

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 rich schema (100% coverage), clear annotations, and presence of an output schema, the description suffices to orient an agent toward the tool's core purpose. It does not summarize advanced parameters like parameter binding or raw XML, but these are fully documented in the schema, so the description does not need to carry that burden.

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%—every parameter has a detailed description. The main description does not add parameter-specific meaning beyond the 'read-only' qualifier, so the baseline of 3 applies.

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 uses a specific verb ('Generate') and resource ('execution plan') with a clear scope ('for a read-only SQL query'). It distinguishes the tool from siblings like execute_sql (which executes queries) and plan cache tools that retrieve existing plans.

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 implies use for read-only queries and plan analysis, but it does not explicitly state when to use this tool vs alternatives such as execute_sql or get_plan_cache_analysis. There are no exclusions or alternative tool references, only the 'read-only' qualifier as a soft usage signal.

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

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

Annotation contradiction: the description says 'Finalize a tuning session,' implying a state-changing write operation, while annotations declare readOnlyHint=true and idempotentHint=true. This is a direct contradiction. The description also fails to disclose any side effects, such as marking the session as complete.

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, front-loaded sentence with no filler. Every phrase adds meaningful content about the finalization process.

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?

Despite having an output schema and annotations, the description is incomplete due to the annotation contradiction and the lack of explanation for several parameters. The tool uses decision_id and idempotency_key, but the description does not clarify when they are required or how they affect the finalization.

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 coverage is only 43%, with 4 of 7 parameters lacking descriptions. The description hints at 'winning candidate' and 'stopping reason' but does not clarify decision_id, database_name, idempotency_key, or the meaning of 'complete leaderboard.' The idempotency_key parameter is never mentioned despite the idempotentHint annotation.

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 with the specific verb 'Finalize' and identifies the resource as a tuning session. It lists key elements (winning candidate, leaderboard, rejected experiments, stopping reason), which distinguishes it from sibling tools like start_tuning_session or add_tuning_candidate.

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 implies this is the concluding step in a tuning workflow, but it does not explicitly state when to use it, what prerequisites exist, or how to choose between this and related tools. There are no alternative suggestions or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that it generates a script (not executes it) and includes the T-SQL language, which is useful context. However, it does not disclose details such as how schema_filter affects behavior or whether the script is returned as text. It does not contradict annotations, and the added value is modest.

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, tightly worded sentence that conveys the core functionality in under 15 words. There is no redundant phrasing or filler. Every word contributes to the purpose.

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 tool is relatively simple (3 parameters, one optional) and has an output schema. However, the description does not clarify what kind of output to expect (e.g., a script string, file path) or how the optional schema_filter narrows the generated script. While not critical, this missing context prevents a higher score.

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?

Input schema coverage is 100%, with each parameter having a basic description. The tool description adds no extra meaning beyond the schema; it only reiterates the overall transformation goal. This matches the baseline of 3 where the schema carries the parameter documentation weight.

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 uses a specific action verb ('Generate') with a concrete resource ('T-SQL migration script') and a clear goal ('transform source schema to match target'). This unambiguously distinguishes it from sibling tools like compare_schemas, which only compares schemas without generating scripts.

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 no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., need to run compare_schemas first) or situations where it should be avoided. The intended usage is only implied by the name and generic purpose, not stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds minimal behavioral context (e.g., includes blocking information) but does not disclose ordering, pagination, snapshot semantics, or performance implications. This is acceptable given the annotations.

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 sentence of 11 words, front-loaded with the action and resource. There is zero waste and every word earns its place.

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 simplicity, full parameter schema coverage, and existing annotations, the description is largely sufficient. The lack of usage guidance is a minor gap but does not significantly impair selection or invocation.

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 coverage is 100% with both parameters having descriptions in the schema. The tool description adds no parameter-level detail beyond what the schema provides, so the baseline score is 3.

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 uses the specific verb 'List' and identifies a clear resource ('active sessions and running queries') with a useful qualifier ('including blocking information'). It distinguishes from sibling tools like get_wait_stats or get_lock_details by focusing on sessions and queries.

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 no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or alternative tool suggestions, which is a notable gap given the large set of sibling monitoring tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, but the description adds useful behavioral context: results are 'bounded' (limiting output size) and include 'missing-index flags' while excluding raw plan XML. This goes beyond the annotations without contradicting them.

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?

A single concise sentence that front-loads the core purpose and immediately follows with key differentiators. No filler or redundancies; every part earns its place.

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?

With an output schema available and comprehensive annotations, the description fully covers the essential purpose, scope (cached routines), and notable constraints (bounded results, no raw plan XML). It is sufficiently complete for a read-only stats tool of this simplicity.

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?

Input schema has 100% description coverage for all parameters, including defaults and allowed sort values. The description itself does not add parameter-specific meaning beyond what the schema already provides, so baseline 3 is appropriate.

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?

Description clearly states the tool 'Get cached stored procedure and UDF execution statistics', identifying both the action (get) and the resource (cached routine stats). The additional clause 'Returns bounded routine metrics and missing-index flags without raw plan XML' differentiates it from sibling tools that return raw plan XML or focus on other cache aspects.

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?

Implied usage: the description indicates this tool is for routine-level execution metrics and missing-index flags, with the phrase 'without raw plan XML' hinting at a distinction from plan-returning tools. However, it does not explicitly name alternatives or state when to prefer this tool over siblings like get_top_cached_queries or get_plan_cache_analysis.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds meaningful behavioral context: it specifies a 'bounded' input-buffer (limit), scopes to 'current database sessions,' and notes the optional nature of sensitive input-buffer data. This goes beyond basic annotations without contradicting them.

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 sentence that front-loads the tool's purpose ('Get connection diagnostics') and then lists the key deliverable components in a compact list. Every word earns its place, with no filler or redundancy.

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 tool is a read-only diagnostic with no required parameters, and the description covers the main output areas. An output schema exists, so return-value documentation is not needed here. However, the description does not mention the default limit or the database_name default, which are minor context omissions that do not prevent effective use.

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%, with each parameter already having a detailed description (e.g., 'Include sys.dm_exec_input_buffer details...'). The tool description adds minimal parameter-specific meaning beyond that, so a baseline of 3 is appropriate. It does not compensate for any schema gaps because there are none.

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 uses a specific verb ('Get') and resource ('connection diagnostics'), then enumerates specific output components: connection counts by client IP, session summary, and optional bounded input-buffer text. This level of detail distinguishes it from sibling tools like get_active_sessions or get_connection_pool_stats, making its purpose unambiguous.

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 implies a use case by detailing what diagnostics are returned (connection counts, session summary, input-buffer text), but it does not explicitly state when to use this tool over siblings or mention exclusions/alternatives. The context is enough to infer usage, but explicit guidance is absent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond annotations: it specifically scopes the operation to MCP-side (not touching the database) and mentions leak detection. No contradiction exists.

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?

Exactly two compact sentences. The first sentence packs the core purpose and key metrics; the second adds the use case and safety guarantee. No filler or redundancy – every clause earns its place.

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?

For a zero-parameter diagnostic tool with an output schema, the description is complete: it states what it does, what metrics it reports, and when it should be used. The output schema handles return value detail, so nothing essential is missing.

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?

The tool has zero parameters, so the baseline is 4. The description appropriately does not attempt to document nonexistent parameters and instead focuses on output semantics, which is correct for a parameterless tool.

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?

Description opens with a specific verb+resource ('Get MCP server connection pool statistics') and enumerates exact metrics (per-database acquire/release/discard counts, peak utilization, possible leaks), clearly distinguishing it from database-side diagnostic tools. The scope is precise and unambiguous.

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 phrase 'Diagnoses MCP-side slowness without touching the database' provides clear context for when to use this tool (MCP-side performance issues) and a safety consideration, but it does not explicitly name alternatives or exclusion criteria. This fits the 'clear context, no exclusions' level.

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

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

With readOnlyHint=true and destructiveHint=false, safety is already covered. The description adds context by specifying the DMV source and the result contents (SQL text, wait category), and clarifies the real-time nature, providing value beyond annotations.

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, front-loaded sentence that effectively communicates action, source, and key output. No information is wasted.

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?

For a simple read-only tool with one optional parameter and an output schema, the description adequately conveys the purpose and data source. It doesn't need to explain return values because an output schema exists.

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?

The schema fully documents the single optional database_name parameter with its default value, so the description does not need to add parameter details. The description also does not mention parameters, but the schema coverage is complete.

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 action: getting currently waiting tasks in real time, sourced from sys.dm_os_waiting_tasks, with SQL text and wait category. This is specific enough to distinguish from historical wait stats tools like get_wait_stats.

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 phrase 'right now — real-time view' implies this tool is for immediate, current wait information, but the description does not explicitly state when to prefer it over siblings like get_wait_stats or get_query_wait_stats, nor does it mention alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool's safety profile is known. The description adds a detailed scope of what the inventory covers (Query Store, automatic tuning, geo-replication links, etc.), which provides useful context beyond the annotations. However, it does not disclose any additional behavioral traits such as permission requirements, potential result size, or execution cost.

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 sentence that opens with the primary action and resource, then efficiently enumerates the specific configuration categories. It is front-loaded, free of repetition, and every word adds value.

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 simplicity (one optional parameter), rich annotations, and the presence of an output schema, the description adequately covers what the tool does by listing the exact configuration domains it retrieves. There is no need to explain return values or behavioral nuances beyond what the annotations and output schema already provide.

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?

The single parameter database_name is fully described in the schema (optional, defaults to AZURE_SQL_DEFAULT_DATABASE). The tool description adds no extra parameter-related meaning, so the schema carries the full weight. With 100% schema_description_coverage, the baseline score of 3 is appropriate.

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 uses the specific verb 'Get' with the resource 'Azure SQL database configuration inventory' and enumerates detailed sub-categories (version, read-only instance settings, database properties, etc.). This clearly distinguishes it from sibling tools like get_object_details (which focuses on objects) and check_runtime_status (which focuses on runtime health).

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 clearly communicates that this tool returns a database configuration inventory. While it does not explicitly state when not to use it or name alternatives, the context is unambiguous: it is the go-to tool for fetching configuration-related details. There are no exclusions or alternative mentions, but the usage intent is strongly implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context about the data source (system_health session) and output parsing, but does not disclose potential limitations such as session unavailability or permission requirements. Given the annotation coverage, a score of 3 is appropriate.

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 two sentences and front-loaded with the main action ('Get recent deadlock history'). Every word adds value, with no redundancy or filler. This is an example of a well-structured, concise tool description.

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 simplicity, the existing output schema, and the strong annotation hints, the description provides enough context to select and invoke the tool correctly. It clearly identifies the data source and the information returned, making it complete for its purpose.

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% for both parameters (max_events and database_name), so the schema already explains their meaning. The description does not add parameter-specific semantics beyond what is already present, and the baseline of 3 applies.

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 retrieves deadlock history from system_health extended events and parses XML to show victim, participants, resources, and SQL text. This specific verb+resource combination distinguishes it from other diagnostic siblings like get_wait_stats or get_active_sessions.

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 implies use when investigating deadlocks and provides clear context about the source and output. It does not explicitly list exclusions or alternatives, but the tool is unique enough among siblings that the context is sufficient without them.

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

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

Annotations already establish that this is a read-only, idempotent operation with no destructive side effects. The description adds the important behavioral detail that the dependency graph includes both inbound and outbound references, which clarifies the scope of the result beyond the schema.

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?

One concise sentence, front-loaded with the action and object. No redundant information.

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?

With a simple purpose, a complete parameter schema, an output schema, and robust annotations, the description fully covers the tool's intended use. Nothing essential is missing.

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?

All three parameters are fully described in the schema (schema_name, object_name, database_name with default). The description adds no additional parameter semantics, but the schema coverage is 100%, so a baseline of 3 is appropriate.

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 uses a specific verb 'Get' and identifies the resource as 'dependency graph for a database object,' then clarifies the bidirectional nature. This distinguishes it from sibling tools like get_object_details and list_objects, which likely retrieve different object metadata.

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 a clear context: use this tool to retrieve dependency relationships. However, it does not explicitly mention alternatives or conditions when this tool should be preferred over similar 'get' tools, though the sibling list includes get_object_details which could overlap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context that the tool identifies recently unexecuted forced plans and force failures, which is helpful behavioral context about the output. No contradictions.

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?

Two concise sentences, front-loaded with the primary action and immediately adding value about what is identified. No filler.

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 covers the main purpose and output focus (execution stats, staleness, failures). With read-only annotations and optional parameters, it is reasonably complete for a read-only list tool. However, it lacks any usage context relative to the many sibling plan analysis tools.

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?

The input schema provides descriptions for both optional parameters (database_name and window_minutes) with defaults and constraints, so schema coverage is 100%. The description does not add additional parameter semantics beyond the schema.

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 uses the specific verb 'List' and identifies the resource as 'forced plans' with detail about execution stats and staleness warnings. It is clear but does not explicitly distinguish from sibling tools like plan_health_review or review_plan_enforcement.

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?

No guidance on when to use this tool versus alternatives. It only states what the tool does, leaving the agent to infer appropriate use from the sibling tool names.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description adds limited behavioral context. It introduces the concepts of 'scoped', 'durable', and 'cross-skill learning', which describe the nature of the resource, but it does not disclose what happens on missing IDs, error handling, or the role of the optional database_name scope. The description adds some context beyond annotations but remains thin.

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 verb and resource. Every word adds meaning, particularly the qualifiers 'scoped', 'durable', and 'cross-skill'. There is no fluff or repetition of structured fields.

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?

For a simple read tool with an output schema and clear annotations, the description is mostly adequate. However, it lacks guidance on when to use it relative to siblings and does not elaborate on the meaning of 'scoped' or how database_name factors in. The minimalism leaves some gaps for a new agent, especially with a schema that has an undocumented parameter.

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 50% (only handoff_id has a description). The tool description does not explain handoff_id beyond being an identifier or clarify what database_name does. The word 'scoped' vaguely hints at a scope concept, but it does not tie to the parameters. It fails to compensate for the low 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 uses a specific verb ('Read'), names the resource ('handoff'), and includes scope qualifiers ('one', 'scoped', 'durable', 'cross-skill learning'), clearly distinguishing this from sibling tools like create_handoff and resolve_handoff. It is unambiguous and focused.

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 implies usage: fetch a single handoff by identifier. However, it does not explicitly state when to use this tool versus alternatives (e.g., list_learning_candidates or resolve_handoff), nor does it provide exclusions or prerequisites. The 'Read one' phrasing gives minimal guidance but lacks explicit direction.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds behavioral context beyond these by specifying that it warns when average latency exceeds a 20ms threshold, which is useful for setting expectations. This additional detail justifies a score above the annotation-only baseline.

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 two sentences, immediately states the core purpose, and includes only relevant detail (the warning threshold). There is no redundancy or filler, making it appropriately concise and well-structured.

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 tool is simple with one optional parameter, rich annotations, and an output schema, so the description need not explain return values. It covers purpose and a key behavioral detail, making it adequately complete for an agent to select and invoke correctly. Slight gap: no mention of output granularity (per-file vs aggregated), but this is not critical given the output 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?

The input schema fully documents the only parameter (database_name) with a description and default value, so the description adds no further parameter-specific information. Schema coverage is 100%, meeting the baseline for this dimension.

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 function with a specific verb ('Get') and resource ('per-file I/O stats'), enumerating key metrics (read/write latency, throughput, stall times). This distinguishes it from sibling tools like get_wait_stats which focus on waits, and get_storage_diagnostics which focus on storage-level issues.

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 implies usage for investigating I/O performance by listing relevant metrics and mentioning a warning threshold, but it does not explicitly state when to prefer this tool over alternatives or provide exclusions. With many diagnostic siblings, clear guidance would be valuable, but the context is implicitly understood.

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

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

Annotations already declare readOnlyHint and destructiveHint false, covering safety. The description adds that it queries a specific DMV and includes lock modes and SQL text, giving useful context, but does not mention ordering, pagination, or performance implications.

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?

A single sentence that front-loads the purpose and lists the key output fields without unnecessary detail. Every element earns its place.

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 presence of an output schema and complete parameter descriptions, the tool is largely self-explanatory. It could benefit from a brief usage note or alternative pointer, but it is sufficiently complete for a simple read-only diagnostic.

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?

Both parameters (limit, database_name) are fully described in the schema with defaults and semantics. The description does not add any parameter-specific meaning beyond what the schema provides, so it earns the baseline score.

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 uses the specific verb 'get' and names the exact resource (lock details from sys.dm_tran_locks) along with the fields returned. This clearly distinguishes it from sibling diagnostics like wait stats or active sessions.

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?

No guidance is provided on when to use this tool versus alternatives such as get_currently_waiting_tasks or get_wait_stats. The description only states what it does, leaving the agent to infer when it is appropriate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context: it specifically surfaces queries waiting on RESOURCE_SEMAPHORE and those likely spilling to tempdb. This goes beyond the schema and annotations by clarifying what the query results represent, though it does not discuss return formatting or limitations.

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 extremely concise: two sentences that front-load the primary action and then add specific diagnostic value. There is no unnecessary verbosity or repetition; every clause adds relevant detail.

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 output schema exists, the description sufficiently covers the tool's purpose and key diagnostic dimensions (active/pending, RESOURCE_SEMAPHORE, tempdb spill). It does not explain concepts like 'pending' or how to interpret results, but the output schema and read-only nature make this reasonably complete for an agent.

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?

The schema provides 100% coverage for the single optional parameter, including a default behavior description. The tool description adds no additional meaning about the parameter, so it relies on the schema, which is adequate. Baseline 3 is appropriate given the high 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 states the tool retrieves memory grants, specifically active and pending ones. It also identifies the exact resource types (queries waiting on RESOURCE_SEMAPHORE and likely tempdb spills), making it distinct from sibling tools like get_wait_stats or get_tempdb_usage.

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 implies use for diagnosing memory pressure by identifying waiters and tempdb spills, but it does not explicitly mention alternative tools or provide when-to-use versus when-not-to-use guidance. Context is present but indirect.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds no further behavioral context (e.g., access requirements, output format) but does not contradict the annotations, so a baseline score is appropriate.

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 clear sentence with no unnecessary detail. It is appropriately sized and front-loaded, with every word contributing meaning.

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 relatively low complexity, a one-line description plus a rich schema and annotations might suffice. However, it does not clarify the scope of 'detailed information' or how it relates to other inspection tools, leaving a gap in completeness.

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 coverage is 100% with descriptive parameter definitions, so the schema already explains the parameters. The description adds no additional parameter semantics, which is acceptable given the comprehensive schema.

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 'Show detailed information about a schema object' clearly indicates a read operation targeting a specific object. It implies a focused lookup, distinguishing it from list or search tools, but does not specify what 'details' include or how it differs from get_table_stats or get_dependencies.

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?

No guidance is provided on when to use this tool versus alternatives. With sibling tools like list_objects, search_objects, and get_table_stats, the absence of usage context leaves the agent to infer the appropriate scenario.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, which lowers the bar. The description adds valuable context about the tool's scope by detailing what diagnostics are included, going beyond a simple 'get diagnostics' statement. It does not contradict annotations, and while it omits performance or permission details, the read-only nature is well covered.

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 sentence, efficiently listing the main diagnostic categories with a colon list. It front-loads the core purpose and avoids superfluous wording, though the list is dense. It earns a high score for being concise without losing substance.

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?

With a rich output schema, clear annotations, and fully documented parameters, the description does not need to explain return values or parameter usage. It provides a thorough overview of the diagnostic categories, making the tool's function clear. It stops short of explicitly distinguishing from sibling tools, but the core context is sufficiently complete.

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?

The schema descriptions cover all four optional parameters (limit, table_name, schema_name, database_name) at 100% coverage. The description does not add any parameter-specific meaning beyond the schema, so the baseline of 3 is appropriate.

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 specifies a clear action ('Get') and resource ('object and index diagnostics') and enumerates specific diagnostic categories (write-heavy nonclustered indexes, read/write usage, etc.), effectively distinguishing it from broader diagnostic tools. It tells the agent exactly what information to expect.

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 implies use cases by listing the covered diagnostics, but provides no explicit guidance on when to choose this tool over siblings like analyze_index_recommendations or get_table_stats. No exclusions or alternative tool references are given, so the agent must infer applicability from the list.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds useful context about returned fields and warnings for long-running/idle transactions, but doesn't disclose other behavioral traits such as pagination or rate limits. Adequate but not rich.

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?

Single sentence, front-loaded with the key action and a concise list of returned information. No filler or repetition, every word earns its place.

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?

For a read-only listing operation with full parameter schema coverage and an output schema present, the description provides sufficient context. The mention of duration, type, and warnings goes beyond minimal, making it complete for its complexity.

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?

Both parameters are fully documented in the input schema with descriptions for limit and database_name, so the description adds no additional parameter semantics. Baseline 3 is appropriate given high 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 states the tool retrieves open transactions and lists specific attributes (duration, type, log bytes used, warnings). The verb 'Get' and specific resource make it distinct among the many sibling diagnostic tools.

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 no explicit guidance on when to use this tool versus alternatives like get_active_sessions or get_lock_details. It neither specifies intended use cases nor mentions alternative tools, leaving selection to inference from the tool name.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable context by noting the case is 'redacted' and includes 'evidence envelopes' and 'event history', giving the agent a sense of the response structure and that sensitive data may be filtered.

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?

A single, succinct sentence that front-loads the main purpose and lists the key return components. No filler or redundant information.

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 presence of an output schema and annotations, the description is sufficient for a simple read operation. It covers the main resource and its parts, though it omits information about the database_name parameter and any usage nuances, which are minor gaps for this tool.

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?

The schema description coverage is 50% (only case_id has a description). The tool description does not add any parameter-level meaning, leaving database_name completely undocumented. Since coverage is not high and the description doesn't compensate, parameter semantics are weak.

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 action ('Get') and the specific resource ('redacted performance case') plus its associated components ('evidence envelopes, and event history'). This distinguishes it from sibling tools like collect_performance_evidence or get_object_details.

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?

No explicit guidance on when to use this tool versus alternatives. It does not mention any exclusions or name alternative tools (e.g., for querying a case, use this; for collecting evidence, use collect_performance_evidence). The description only states what it does, not the intended scenario.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is clear. The description adds behavioral context by specifying what analysis dimensions it covers (distribution, bloat, top plans, ad-hoc pollution), which goes beyond the annotations without contradicting them.

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 two sentences, front-loads the primary action, and contains no redundant phrases. It packs the essential information (what it analyzes and what it detects) without waste.

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?

For a single-parameter tool with an output schema and comprehensive annotations, the description is largely complete. It explains the tool's purpose and key diagnostic outputs. The only gap is explicit usage guidance relative to siblings, but overall it provides enough context for an agent to invoke it correctly.

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?

The only parameter, database_name, is fully described in the schema with a default and explanation. Schema coverage is 100%, so the description need not elaborate. The description adds no parameter-specific meaning beyond the schema, which is acceptable per the baseline.

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 uses a specific verb ('Analyze') and resource ('plan cache') and enumerates concrete outputs: plan type distribution, single-use plan bloat, top plans by size, and ad-hoc query pollution detection. This clearly distinguishes it from sibling tools like get_top_cached_queries or plan_health_review.

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 implies the tool is for diagnosing plan cache health and detecting ad-hoc pollution, but it does not explicitly state when to prefer this tool over alternatives or provide exclusion criteria. Given many sibling tools, more explicit guidance would be valuable.

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

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

Annotations already disclose the read-only, non-destructive, idempotent nature. The description adds meaningful behavioral context by naming the DMV source and the 50% threshold, aligning with the expected read-only behavior without contradiction.

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 exceptionally concise: two short sentences that immediately communicate the action, data source, and threshold. Every word earns its place with no redundancy.

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?

For a read-only diagnostic tool with strong annotations, a full output schema, and well-documented parameters, the description covers the essential purpose and threshold. Mentioning the 50% ratio and sys.dm_exec_query_stats is sufficient for an agent to select and invoke the tool correctly.

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%, and both parameters (top_n and database_name) have clear descriptions. The tool description adds no additional parameter-level detail, so the baseline of 3 applies.

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 identifies excessively recompiled queries from sys.dm_exec_query_stats with a specific threshold (recompile ratio > 50%). This precise verb+resource combination distinguishes it from sibling diagnostic tools like get_top_queries or get_query_wait_stats.

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?

Usage is implied: if you need to find queries with high recompilation, this tool is appropriate. However, it does not explicitly mention when to use it versus alternatives, nor does it provide exclusions or comparisons to related tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context: each distinct compiled set produced a plan shape in production, and the history cannot show edge cases. No contradictions with annotations.

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 two sentences with no wasted words. It front-loads the core purpose and adds a rationale/limitation note, earning its place.

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 presence of an output schema and comprehensive annotations, the description adequately covers purpose, context, and limitations. It does not mention prerequisites like Query Store being enabled, but this is implied by the tool's context among sibling tools.

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% for both parameters (query_id and database_name with default). The description adds no additional parameter-level detail, so baseline 3 is appropriate.

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 states a specific verb and resource: 'Extract the compiled parameter values behind each Query Store plan for one query.' It clearly distinguishes itself from sibling tools by focusing on per-plan parameter buckets rather than sniffing or statistics.

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?