mcp

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

The description adds valuable behavioral context beyond annotations: it discloses that this returns a long-running operation requiring polling, takes several minutes, and suggests a 30-second pause strategy. Annotations already indicate it's not read-only, destructive, or idempotent, but the description provides operational timing and polling requirements that aren't captured in structured fields.

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 perfectly structured: a clear purpose statement followed by two bullet points with essential operational guidance. Every sentence earns its place with zero waste, making it front-loaded and highly efficient for an AI agent 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 complexity (clone operation with long-running nature), rich annotations, and the presence of an output schema, the description is complete. It covers the core purpose, operational behavior, and polling requirements without needing to explain return values (handled by output schema) or repeat what annotations already state about safety.

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?

With 67% schema description coverage, the schema already documents most parameters well. The description doesn't add specific parameter semantics beyond what's in the schema, but it doesn't need to compensate significantly given the decent coverage. The baseline of 3 is appropriate since the schema handles the heavy lifting for parameter documentation.

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 specific action ('Create a Cloud SQL instance as a clone') and resource ('of a source instance'), distinguishing it from siblings like create_instance (new instance) or restore_backup (from backup). It precisely defines the tool's function without ambiguity.

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 explicitly provides usage guidance: it instructs to use get_operation to poll status, recommends pausing 30 seconds before rechecking, and notes the operation can take several minutes. This gives clear procedural context for when and how to use this tool versus alternatives like create_instance.

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 annotations cover key behavioral traits (readOnlyHint=false, destructiveHint=false, etc.), so the description's burden is lower. It adds some useful context by emphasizing that project and instance fields are always required, but doesn't disclose operational details like backup duration, impact on instance performance, rate limits, or authentication needs. With annotations providing a basic safety profile, a score of 3 reflects moderate added value without 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?

The description is concise and well-structured in two sentences, with the first stating the purpose and the second providing field usage guidance. There's no unnecessary repetition or fluff, and it's front-loaded with the core action. A slight deduction because the second sentence could be more streamlined, but overall it's 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?

Given the tool's moderate complexity (a write operation with 4 parameters), rich annotations (covering safety and idempotency), and the presence of an output schema, the description is reasonably complete. It covers the basic action and field requirements, though it could benefit from more behavioral context (e.g., backup implications) or usage scenarios. The output schema reduces the need to explain return values, supporting adequacy.

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

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

Schema description coverage is 100%, so the schema already fully documents all parameters (project, instance, location, description). The description reiterates that project and instance are always required and that location and description are optional, but doesn't add meaningful semantic context beyond what's in the schema (e.g., format examples, constraints, or real-world usage). Baseline 3 is appropriate when the schema does the heavy lifting.

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: 'Takes a backup on a Cloud SQL instance.' This specifies the verb ('takes a backup') and resource ('Cloud SQL instance'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'restore_backup' or 'clone_instance' beyond the obvious action difference, which prevents a perfect score.

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 minimal usage guidance, focusing only on which fields to populate ('Always populate the project and instance fields...'). It doesn't explain when to use this tool versus alternatives like 'restore_backup' or 'clone_instance', nor does it mention prerequisites, dependencies, or typical scenarios for backup creation. This leaves the agent with insufficient context for optimal tool selection.

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 valuable behavioral context beyond annotations: it discloses that the operation returns a long-running operation requiring polling, takes several minutes, and has specific security considerations (ipv4_enabled defaults). While annotations cover basic safety (destructiveHint=false), the description provides crucial operational details about timing and async 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 excessively long with multiple JSON configuration examples that could be referenced elsewhere. While the first few bullet points are valuable, the detailed configuration blocks (development, production, SQL Server) could be condensed or moved to documentation, making the description less 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?

Given the tool's complexity (14 parameters, long-running operation) and the presence of both comprehensive schema descriptions and output schema, the description is complete. It covers the async nature, timing expectations, security considerations, and provides practical configuration guidance, addressing all critical aspects for proper tool 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?

With 100% schema description coverage, the baseline is 3. The description adds some value by explaining default configurations and providing example JSON structures, but doesn't significantly enhance understanding of individual parameters beyond what the comprehensive schema already documents.

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 specific action ('Initiates the creation') and resource ('Cloud SQL instance'), distinguishing it from siblings like clone_instance, create_backup, and update_instance. It establishes this as the primary instance creation tool rather than modification or cloning.

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 explicit guidance on when to use this tool vs alternatives: it mentions using get_operation to poll status, create_user for subsequent IAM setup, and gives specific configuration examples for development vs production environments. It also distinguishes from execute_sql for data operations.

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 valuable behavioral context beyond annotations: it explains the long-running operation nature requiring polling, default role assignment, authentication requirements for using with execute_sql, and specific limitations (SQL Server unsupported, allowlist requirements for password secrets). While annotations cover basic safety (readOnlyHint=false, destructiveHint=false), the description provides operational details that help the agent understand how to work with this tool effectively.

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?

While well-structured with clear sections, the description is quite lengthy with extensive examples and limitations. Some information could be more efficiently presented, and the examples (while helpful) make the description verbose. However, the information is generally relevant and organized logically.

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 this is a complex creation tool with 6 parameters and significant behavioral considerations, the description provides comprehensive context: it covers prerequisites, operational patterns (polling), limitations, authentication implications, and database-specific behaviors. With an output schema available, it appropriately focuses on usage rather than return values, making it complete for agent decision-making.

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?

Despite 100% schema description coverage, the description adds significant practical meaning: it explains how the 'type' parameter affects authentication methods, provides concrete examples of how 'name' formatting differs between PostgreSQL and MySQL, clarifies the purpose of 'password_secret_version', and shows how parameters work together in complete request examples. This goes beyond the schema's technical definitions to show real-world 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 the specific action ('Create a database user') and resource ('for a Cloud SQL instance'), distinguishing it from siblings like 'list_users' or 'update_user'. The opening sentence directly communicates the tool's function without ambiguity.

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 explicit guidance on when to use this tool versus alternatives: it mentions using 'get_operation' to poll status, specifies when to use 'execute_sql' with the created user, and explicitly states limitations like not supporting SQL Server. It also distinguishes between user types and provides clear examples for different scenarios.

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 context beyond annotations. While annotations indicate destructiveHint=true (implying mutations), the description details specific limitations (10MB response truncation, 30-second timeout, SQL Server unsupported), authentication requirements, error handling procedures, and response interpretation guidance. This goes well beyond what annotations provide.

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 comprehensive but lengthy and could be more front-loaded. While all content is valuable (prerequisites, limitations, troubleshooting), it spans multiple sections and could benefit from better organization. Some sentences are verbose, though none are wasteful.

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 (destructive SQL execution with authentication requirements) and the presence of annotations and output schema, the description provides excellent completeness. It covers prerequisites, limitations, error handling, authentication workflows, and response interpretation, making it highly informative for safe and 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?

With 100% schema description coverage, the input schema already documents all 6 parameters thoroughly. The description doesn't add parameter-specific information beyond what's in the schema, so it meets the baseline of 3. The description focuses on behavioral context rather than parameter details.

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: 'Execute any valid SQL statement... on a Cloud SQL instance.' It specifies the scope (DDL, DCL, DQL, DML) and distinguishes it from sibling tools like execute_sql_readonly by not having read-only restrictions.

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 explicit guidance on when to use this tool versus alternatives. It mentions prerequisites (instance requirements, user setup), troubleshooting steps for errors, and references sibling tools like get_instance, list_users, create_user, and update_user for related operations.

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?

Despite annotations indicating read-only, idempotent, and non-destructive behavior, the description adds significant behavioral context: limitations (10MB response truncation, 30-second timeout, no SQL Server support), authentication requirements (IAM user/service account), and response handling (checking 'message' and 'status' fields for partial errors). This goes well beyond what annotations provide.

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 lengthy and includes extensive troubleshooting steps, which may be useful but reduces conciseness. It is front-loaded with core functionality but could be more streamlined, as some sections (e.g., detailed error handling) might be better placed elsewhere.

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, rich annotations, and output schema, the description is highly complete. It covers prerequisites, limitations, error handling, authentication details, and integration with sibling tools, leaving no significant gaps for an AI agent to understand and use the tool effectively.

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?

With 100% schema description coverage, the baseline is 3. The description adds value by clarifying parameter interactions (e.g., 'auto_iam_authn' ignoring the 'user' field) and database-specific requirements (Postgres vs. MySQL for 'database' parameter). However, it doesn't fully detail all 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 clearly states the tool's purpose: 'Execute any valid read only SQL statement on a Cloud SQL instance.' It specifies the verb ('Execute'), resource ('read only SQL statement'), and target ('Cloud SQL instance'), and distinguishes it from its sibling 'execute_sql' by emphasizing the read-only nature.

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 explicit guidance on when to use this tool, including prerequisites (e.g., IAM authentication setup, instance requirements) and alternatives (e.g., using 'get_instance' to check settings, 'create_user' for IAM setup). It also details error scenarios and troubleshooting steps, offering comprehensive 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, non-destructive, and closed-world behavior, so the description doesn't need to repeat these. It adds minimal context by specifying 'details' retrieval, but doesn't elaborate on rate limits, authentication needs, or error handling beyond what annotations provide.

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, direct sentence that efficiently conveys the core action without unnecessary words. It is front-loaded and appropriately sized for its purpose, with no wasted 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 low complexity (simple retrieval), rich annotations (read-only, non-destructive), and the presence of an output schema, the description is reasonably complete. However, it could benefit from slight elaboration on usage context to fully compensate for the lack of guidance.

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?

With 100% schema description coverage, the input schema fully documents both parameters ('project' and 'instance'). The description adds no additional meaning or clarification beyond what the schema provides, such as format examples or constraints, meeting the baseline for high 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 verb ('Get') and resource ('details of a Cloud SQL instance'), making the purpose evident. However, it doesn't explicitly distinguish this tool from its sibling 'list_instances', which might retrieve multiple instances rather than details of a specific one.

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 like 'list_instances' for multiple instances or 'get_operation' for operation details. It lacks context on prerequisites or exclusions, leaving usage unclear.

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 this is a read-only, non-destructive operation (readOnlyHint: true, destructiveHint: false). The description adds useful context about the long-running nature and recommended polling behavior, which goes beyond the annotations. However, it does not disclose other behavioral traits like rate limits, authentication needs, or error handling, leaving some gaps.

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

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

The description is appropriately sized and front-loaded, starting with the core purpose. The second sentence adds necessary context about operation duration, and the third provides actionable guidance. Each sentence earns its place, but it could be slightly more streamlined by combining ideas without losing clarity.

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 (simple status check), rich annotations (read-only, non-destructive), and the presence of an output schema (which handles return values), the description is mostly complete. It covers the purpose, usage context, and behavioral advice. However, it lacks details on prerequisites or error scenarios, which could enhance completeness 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 input schema has 100% description coverage, clearly documenting both required parameters ('project' and 'operation'). The description does not add any semantic details about these parameters beyond what the schema provides. According to the rules, with high schema coverage (>80%), the baseline score is 3, as the description does not compensate with extra parameter insights.

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: 'Get the status of a long-running operation.' It specifies the verb ('Get') and resource ('status of a long-running operation'), making it easy to understand what the tool does. However, it does not explicitly distinguish this from sibling tools like 'get_instance' or 'list_instances,' which slightly reduces clarity in context.

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 on when to use this tool: for checking the status of operations that 'take several minutes to complete.' It also offers guidance on handling extended durations by suggesting a pause before rechecking. However, it does not explicitly state when not to use it or name alternatives among sibling tools, such as for immediate operations.

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 context beyond annotations. Annotations indicate non-read-only, non-destructive, non-idempotent, and closed-world hints, but the description elaborates on practical aspects: the need for file uploads to Cloud Storage, IAM permission requirements, propagation delays for permissions, file type detection from extensions, database parameter differences between MySQL and PostgreSQL, and the return of a long-running operation requiring polling. This provides crucial operational details not covered by 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 comprehensive but lengthy, with some redundancy. While it efficiently covers prerequisites, permissions, and usage examples, it includes detailed step-by-step instructions and multiple code samples that could be streamlined. The information is well-structured but could be more front-loaded, as key usage guidelines are embedded in the middle rather than highlighted upfront.

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 (data import with permissions, file handling, and database engine variations), the description is highly complete. It addresses prerequisites, permissions, parameter usage, database-specific behaviors, and output handling (long-running operations). With an output schema present, it appropriately focuses on operational context rather than return value details, making it sufficient for effective tool 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?

The description adds meaningful context beyond the input schema. With 67% schema description coverage, the schema documents parameters like 'uri', 'database', and 'fileType', but the description clarifies semantics: it explains URI format expectations (gs:// vs local files), when 'database' is required (PostgreSQL vs MySQL), how file types are inferred from extensions, and provides sample importContext structures for different database engines. This compensates well for the schema's partial 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's purpose: 'Import data into a Cloud SQL instance.' It specifies the verb ('import'), resource ('data'), and target ('Cloud SQL instance'), distinguishing it from siblings like 'create_instance', 'execute_sql', or 'restore_backup' which perform different operations on Cloud SQL resources.

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 explicit guidance on when to use this tool versus alternatives. It mentions prerequisites like uploading files to Cloud Storage and granting permissions, and explicitly names alternative tools for related tasks: 'get_instance' to obtain service account details and 'get_operation' to poll the import status. It also advises on when to use system defaults for optional parameters.

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 this as read-only, non-destructive, and closed-world, which the description doesn't contradict. The description adds minimal behavioral context beyond annotations - it implies this returns all instances but doesn't mention pagination behavior, rate limits, or authentication requirements that would be helpful for an agent.

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 that gets straight to the point with zero wasted words. It's perfectly front-loaded and appropriately sized for a listing operation.

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 has comprehensive annotations, 100% schema coverage, and an output schema exists, the description is reasonably complete. However, it could better address when to use this versus other listing/retrieval operations, especially with multiple sibling tools available.

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?

With 100% schema description coverage, all four parameters are well-documented in the input schema. The description adds no additional parameter semantics beyond what's already in the structured fields, so it meets the baseline expectation but doesn't provide extra value.

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 verb ('List') and resource ('all Cloud SQL instances in the project'), making the purpose immediately understandable. However, it doesn't differentiate this tool from other list operations like 'list_users' or explain why this specific listing is needed versus those alternatives.

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. With sibling tools like 'get_instance' for retrieving a single instance and 'list_users' for listing different resources, there's no indication of when this listing is appropriate versus those other operations.

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, and openWorldHint=false, indicating a safe, read-only operation with limited scope. The description adds minimal behavioral context beyond this, specifying the resource type but not detailing aspects like pagination, sorting, or authentication requirements. It does not 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?

The description is a single, clear sentence that directly states the tool's purpose without unnecessary words or fluff. It is front-loaded and efficiently communicates the essential information, making it easy to understand at a glance.

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 (list operation with two parameters), the presence of annotations covering safety and scope, and an output schema (which handles return values), the description is reasonably complete. It specifies the resource but could improve by mentioning output format or limitations. However, for a basic list tool, it provides adequate 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?

The input schema has 100% description coverage, fully documenting the 'project' and 'instance' parameters. The description does not add any additional meaning or context beyond what the schema provides, such as explaining relationships between parameters or usage examples. With high schema 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 clearly states the verb ('List') and resource ('all database users for a Cloud SQL instance'), making the purpose immediately understandable. However, it does not explicitly differentiate this tool from potential siblings like 'list_instances' or 'get_instance', which would require a more specific scope or comparison.

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 needing to list users for a specific Cloud SQL instance, but it does not provide explicit guidance on when to use this tool versus alternatives like 'get_instance' or 'update_user'. There is no mention of prerequisites, exclusions, or specific scenarios that would favor this tool over others.

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 indicate non-destructive, non-read-only, non-idempotent, non-open-world behavior. The description adds valuable context beyond annotations: it explains this is a long-running operation requiring polling, specifies that it doesn't impact instance availability, and details the structured response format with INFO/WARNING/ERROR findings. No contradiction with annotations 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?

The description is well-structured and front-loaded with core purpose, but could be more concise. Some sentences like 'Addressing any reported issues is crucial...' are somewhat redundant given earlier warnings. However, most content earns its place by providing necessary operational guidance.

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 (long-running operation with structured results) and the presence of both detailed input schema and output schema (implied by get_operation reference), the description is complete. It covers purpose, usage, behavioral details, response handling, and limitations without needing to duplicate schema 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?

With 100% schema description coverage, the baseline is 3. The description adds some semantic context by emphasizing that target_database_version 'MUST be provided' and giving an example (POSTGRES_15), but doesn't significantly elaborate on other parameters beyond what the schema already documents thoroughly.

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 specific verb ('Checks') and resource ('Cloud SQL PostgreSQL instance'), specifying it's for major version upgrade readiness. It distinguishes from siblings by focusing on pre-check rather than actual operations like upgrade_instance (not listed but implied) or other instance management 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 explicit guidance on when to use this tool ('before attempting the actual upgrade'), when not to use it ('does not run on read replicas'), and alternatives for follow-up actions ('Use the get_operation tool'). It also specifies prerequisites like requiring target_database_version and being PostgreSQL-only.

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 valuable behavioral context beyond annotations. While annotations already indicate this is a destructive, non-idempotent write operation, the description provides critical implementation guidance: the restore creates the instance if needed, and parameters must be confirmed with the user. It also clarifies the relationship between source/target projects and instances, which isn't captured in 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 appropriately front-loaded with the core purpose, but contains some redundancy with the schema (e.g., backup identifier formats are documented in both). The 11 sentences could be more efficiently structured, though all provide some value. The 'Confirm the parameters' sentence feels tacked on rather than integrated.

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 this is a complex, destructive operation with 5 parameters and an output schema, the description provides excellent contextual completeness. It covers the purpose, parameter relationships, backup identifier formats, instance creation behavior, and user confirmation requirement. With annotations covering safety aspects and an output schema handling return values, the description focuses appropriately on usage 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?

With 100% schema description coverage, the baseline is 3. The description adds significant value by explaining the three possible formats for backupId, clarifying when sourceInstance is required, and warning about not confusing source_project with target_project. This provides practical usage guidance beyond the schema's technical documentation.

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: 'Restores a backup to a Cloud SQL instance.' This is a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'clone_instance' or 'create_backup' beyond the obvious semantic difference.

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 about when to use this tool ('Restores a backup to a Cloud SQL instance') and includes important guidance: 'Do not try to create the instance before the restore, the restore itself will create the instance if needed.' It also mentions confirming parameters with the user. However, it doesn't explicitly state when NOT to use it or name specific alternatives among siblings.

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 valuable behavioral context beyond annotations: it explains that updates return long-running operations requiring polling, warns about potential downtime/restarts for certain changes, and emphasizes user confirmation for disruptive operations. While annotations already indicate destructive/mutative nature, the description provides specific operational details that enhance transparency.

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

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

The description is perfectly structured and concise: a clear opening sentence states the purpose, followed by two bullet points with essential operational guidance. Every sentence earns its place with zero wasted words, and critical information is front-loaded appropriately.

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 (destructive mutation with 12 parameters), the description provides excellent contextual completeness. It covers operational behavior (long-running operations), risk warnings (downtime), and usage guidance, while relying on the comprehensive schema for parameter details and annotations for safety profile. With output schema present, return values don't need explanation.

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?

With 100% schema description coverage, the input schema already documents all 12 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline of 3 where the schema does the heavy lifting for parameter documentation.

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 specific action ('partially updates') and resource ('configuration settings of a Cloud SQL instance'), distinguishing it from siblings like 'create_instance' (full creation) or 'get_instance' (read-only). It precisely defines the scope as partial updates rather than full replacements.

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 explicit guidance on when to use this tool vs alternatives: it mentions using 'get_operation' to poll status, warns about downtime for certain operations (requiring user confirmation), and implicitly distinguishes from 'create_instance' (updates vs creation) and 'get_instance' (mutation vs read).

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 context beyond annotations: it explains that the tool returns a long-running operation requiring polling, details how role updates work with different revokeExistingRoles settings, provides special MySQL handling instructions, and gives comprehensive examples. Annotations cover basic safety (non-destructive, non-idempotent), but the description adds crucial operational details.

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 well-structured with clear sections (common use case, operational notes, special cases, key parameters, role update logic, examples). However, it's quite lengthy (over 500 words) with some redundancy in the examples section. Every sentence adds value, but it could be more concise while maintaining clarity.

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 this is a complex mutation tool with 7 parameters (4 required) and an output schema, the description provides exceptional completeness. It covers prerequisites, operational behavior, parameter interactions, special cases, and detailed examples. The presence of an output schema means return values don't need explanation, and the description fully addresses the tool's 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?

Despite 100% schema description coverage, the description adds substantial value by explaining the interaction between 'database_roles' and 'revokeExistingRoles' parameters, providing detailed examples of how different combinations affect outcomes, and clarifying MySQL-specific handling of the 'name' parameter. This goes well beyond the schema's basic parameter descriptions.

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 specific action ('update a database user'), resource ('for a Cloud SQL instance'), and scope ('only supports updating users to assign database roles'). It distinguishes from siblings like 'create_user' by focusing on updates rather than creation.

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?

Explicit guidance is provided: 'Before calling the `update_user` tool, always check the existing configuration of the user such as the user type with `list_users` tool.' It also mentions using 'get_operation' to poll status and provides MySQL-specific instructions, clearly indicating when and how to use this tool.

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