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

With no annotations, this description carries the full burden of behavioral disclosure. It clearly states the destructive outcomes (deletes a draft, cancels an issue), notes the UI equivalence, and explains the refusal condition. This exceeds the minimum and leaves no important behavioral ambiguity.

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 three tight sentences, front-loaded with the primary action and followed by necessary behavioral nuance. Every sentence contributes critical information, and there is no filler or repetition of schema 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 one-parameter action with no output schema, the description covers the primary behavior, conditional outcomes, and refusal state. It could be more complete by stating what the caller should expect on success or on refusal (e.g., return values), but the core context needed to call it correctly is present.

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 is already fully described in the schema with a concrete example ('projects/my-project/plans/123'), so the description adds no extra meaning. There are no enums or nested objects requiring elaboration; the schema alone provides sufficient semantic 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 a clear, specific action: cancel a change before it runs, and distinguishes the two different objects (draft plan vs. review issue) it affects. It does not explicitly name sibling tools, so it misses the strongest form of sibling differentiation, but the semantics are unambiguous against tools like create_plan, update_plan, or submit_plan_for_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 provides clear context for when to invoke the tool: before a rollout, with distinct handling for draft vs. submitted plans. It also gives an explicit exclusion (refuses when an active rollout exists) and directs the caller to the UI for that case, but it does not name any alternative MCP tool, which prevents 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?

With no annotations, the description carries full burden. It clearly discloses the behavioral lifecycle: only a draft is created, SQL is not executed, execution requires human review and approval, and Bytebase then creates the rollout automatically. It also notes the safety property regarding BYTEBASE_ALLOW_WRITE, adding context 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?

Three sentences, each delivering essential information: what is created, what is not done, and when it is safe to use. No padding or repetition; 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 mutation tool with no annotations and no output schema, the description covers all critical missing context: the side-effect absence, the exact human-backed workflow, and the environmental allow-write condition. An agent can safely invoke this tool with only the schema and this description.

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%, so the baseline is 3. The description adds the conceptual mapping of statement to Sheet and the notion of a Plan as a proposal, which enriches what the schema alone provides. Although it does not elaborate on title, description, or priorBackup, it gives useful domain context for the other 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 states exactly what the tool does: it creates a Sheet (SQL text) and a Plan (proposal) for one database. It also explicitly says it does NOT open an Issue or run the SQL, which distinguishes it from bytebase_query, bytebase_submit_plan_for_review, and issue-related 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 gives explicit guidance on when to use this tool: for writing SQL when bytebase_query is blocked in read-only mode, and safe to use even with BYTEBASE_ALLOW_WRITE unset because nothing executes until human approval. It identifies the alternative (bytebase_query) and the condition that makes this tool the right choice.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description reveals what the tool returns (columns, indexes, foreign keys) but does not state that it is read-only, non-destructive, or require any special permissions. It also omits potential side effects or limitations. For a metadata retrieval tool, this is a notable gap since the agent cannot infer safety from 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, well-structured sentence that front-loads the core purpose ('Full definition of one table') and then lists the specific elements included. There is no redundant or filler content, making it efficient 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?

For a simple describe operation, the description is nearly complete. It explains what the tool returns (columns, types, nullability, indexes, foreign keys) and the schema covers the required parameters. Without an output schema, this description sufficiently communicates the expected result. It does not mention output format or any caveats, but these are minor for this use case.

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 describes both parameters: 'database' provides an example format, and 'table' says it's the exact table name. With 100% schema description coverage, the description adds little beyond the schema. It does not provide additional context about parameter formats or inter-dependencies, 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 clearly states the tool describes a table and enumerates its contents: columns with types and nullability, indexes, and foreign keys. This distinguishes it from siblings like bytebase_search_tables (which finds tables) and bytebase_query (which executes queries). The verb 'describe' and the resource 'table' are specific 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 description implies the tool is for retrieving table schema details, but it does not explicitly say when to use it instead of alternatives. There is no mention of using bytebase_search_tables to find a table before describing it, or that this is a read-only operation. The context is clear from the name, but no explicit guidance on when/when-not 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?

No annotations are provided, so the description carries the burden. It discloses that the tool fetches a plan and decodes the SQL from its Sheet, which is a meaningful behavioral detail beyond a simple 'get'. It does not mention error cases or whether the operation is read-only, but the verb 'Fetch' and the absence of mutation language make the read-only nature reasonably clear.

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 with no wasted words. The first sentence front-loads the resource and the exact fields returned, and the second sentence adds a practical usage hint. Every sentence 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 simple single-parameter read tool with no output schema, the description is largely complete: it names the resource, the fields returned, and the intended workflow. It could mention that the output includes the decoded SQL statement's format or that the plan must exist, but these are minor gaps given the tool's 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?

Schema description coverage is 100%, so the schema already documents the single 'plan' parameter with an example. The description adds no additional parameter-level meaning beyond what the schema provides, 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 states a specific verb ('Fetch') and resource ('a plan'), and enumerates exactly what is returned: title, description, target database, status, and full SQL statement. It also distinguishes itself from sibling tools by noting the SQL is decoded from the plan's Sheet, which is a unique behavior.

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 says to use this tool before bytebase_update_plan to see current content, providing clear context for one key use case. It does not explicitly mention when not to use it or name alternatives like bytebase_list_issues, but the guidance is sufficient for the primary workflow.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It correctly implies a read-only listing operation but does not explicitly state that it is non-destructive, nor does it mention any potential side effects, rate limits, or pagination behavior. The reference string format is a useful behavioral detail, but overall the disclosure is minimal and typical of a simple list tool.

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. The core action and purpose are front-loaded, and the downstream usage note is appended cleanly. Every sentence earns its place, making it efficient and easy to scan.

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 list tool with no output schema, the description covers the essential output fields and even explains how the output maps to a useful reference string. It does not describe the exact response structure or possible limits, but for a tool this simple and with no required parameters, the description is sufficient for an agent to call it correctly and interpret the results.

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 already describes three of four parameters (search, project, environment) natural language, giving 75% coverage. The description adds no extra meaning to these parameters and does not clarify the undocumented 'refresh' parameter. Since schema coverage is high, a baseline of 3 is appropriate, but the description could have explained the refresh flag or how parameters interact with the output format, which it does not.

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', the resource 'databases', and the specific attributes returned (instance, engine, environment). It also ties the tool to a concrete downstream use case (discovering the reference string for bytebase_query), which distinguishes it from sibling tools like bytebase_search_tables or bytebase_describe_table.

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 says when to use this tool: to discover the reference string for bytebase_query. It even gives the format of that string. However, it does not mention when *not* to use it or alternative tools for similar purposes (e.g., search_tables for finding tables within a database), so it falls short of a 5 on this dimension.

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 no annotations, the description carries the behavioral burden. It discloses a non-obvious consequence: 'required: true' means Bytebase will reject the issue if no label is attached. It does not spell out the exact return shape, but the list semantics and purpose are sufficient for this simple read-only tool.

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 with no filler; the main directive is front-loaded and the downstream rationale is compressed into a short, meaningful clause. Every sentence 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 one-parameter list tool with no output schema, this is nearly complete: it tells the agent why to call it, when to call it, and what label semantics matter downstream. The only minor omission is an explicit statement of the return payload, which the phrasing strongly implies.

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% and the single project parameter already includes a description and example ('Salla-prod'). The description adds no new parameter-level details, so the baseline 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 names a concrete operation ('List') and a specific resource ('issue labels a project has configured'), clearly distinguishing it from siblings like bytebase_list_issues. It also ties it to a downstream action, making its role 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?

It explicitly says when to call this tool: before bytebase_submit_plan_for_review when the project defines labels, and why ('offer them as choices rather than guessing label names'). This gives an agent actionable routing without ambiguity.

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?

No annotations are provided, so the description carries the full burden. It only states the basic listing function and status inclusion, but does not disclose whether it is read-only, any pagination behavior, default limits, or authentication requirements. The 'List' verb implies read-only, but this is not explicit.

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 action and object. It is concise 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?

For a simple list tool, the description is mostly adequate, but it omits details like default limit (present in schema) and does not mention that results are filtered by the given project. With no output schema, it hints at return content (statuses) but not the full shape. Given the sibling context, a bit more differentiation would help, but the current level is acceptable.

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 already describes 'project' and 'limit' with useful context, and the enum for 'status' is self-explanatory. The description adds no parameter details, but with 67% schema coverage it does not need to compensate significantly. The status parameter lacks a textual description, but the enum values are clear.

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 lists schema/data change issues in a project and includes review/approval status. The verb 'List' and resource 'schema/data change issues' are specific, and the scope 'in a project' distinguishes it from sibling tools like list_projects and list_databases.

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 given on when to use this tool versus alternatives. With multiple sibling tools (e.g., list_projects, get_plan), the description does not mention conditions or exclusions, leaving the agent to infer usage from the tool name 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?

No annotations are provided, so the description carries the full burden. It discloses that results are scoped to the configured identity's visibility, which is useful, but it omits any mention of caching behavior (despite a refresh parameter implying a cache), potential pagination, or that this is a read-only operation. For a simple listing tool with zero annotation coverage, this is a significant gap.

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, tightly worded sentence that leads with the action and resource, includes the scope qualifier, and contains zero filler. It is perfectly sized for a simple list tool and front-loads the essential 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?

For a tool with no required parameters and no output schema, the description is mostly adequate but leaves some context unaddressed. It does not explain that results may be cached (relevant given the refresh parameter), nor does it clarify the return format. Since there are no annotations to fill these gaps, the description could be more 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 sole parameter 'refresh' is fully described in the schema (100% coverage), so the description does not need to add more. The description does not mention the parameter at all, but the schema already provides its meaning. Baseline 3 is appropriate; no additional value is added, but none is required.

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 ('List'), a specific resource ('Bytebase project'), and a precise scope ('every ... the configured identity can see'). It clearly distinguishes from sibling tools like list_databases by resource type, leaving no ambiguity about what it returns.

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 by its resource name but provides no explicit guidance on when to choose this tool over alternatives. There is no mention of exclusions or conditions, though the resource distinction is inferable. Given siblings like bytebase_list_databases, a note about when to use this vs. that would strengthen 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively states the tool is read-only, enforces a whitelist of SQL keywords, and explicitly mentions data masking and audit logging. This goes beyond a generic 'runs a query' and is essential for an agent to predict side effects. The only minor gap is not detailing error handling or rate limits, but the key behavior 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 three sentences with zero waste. The first sentence states purpose and output format, the second immediately states the read-only constraint (critical safety), and the third covers identity and policies. It is front-loaded with the most important operational detail (read-only), making it highly 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 (4 params, 2 required, one enum) and no output schema, the description covers the essentials: purpose, safety constraints, and execution context. It omits details like error responses or pagination beyond the limit parameter, but the schema covers most parameter specifics. The read-only guarantee is the most critical missing piece that would otherwise require external knowledge, and it is present, so it is complete enough for safe 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 schema already provides 100% coverage for all parameters, including examples and defaults, so the baseline is 3. The description adds value by clarifying what 'read-only' means for the statement parameter (restricting to specific SQL keywords), which is not in the schema. For dataSource, it offers a default behavior (read-only replica), complementing the enum. Thus, it exceeds 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 states a specific verb+resource ('Execute SQL through the Bytebase SQL Editor') and immediately distinguishes itself from sibling tools like bytebase_query_history and bytebase_describe_table by focusing on executing queries. It also clarifies the read-only nature, which is not evident from the tool name alone.

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?

It clearly states the read-only constraint (only SELECT/WITH/SHOW/DESCRIBE/EXPLAIN) and mentions execution under the configured identity, which implies permissions apply. However, it doesn't explicitly describe scenarios when to prefer this over siblings like bytebase_describe_table for schema exploration, or when to use the admin dataSource, leaving some inference to the agent.

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?

There are no annotations, so the description carries the behavioral transparency burden. The words 'recorded' and 'history' imply a read-only retrieval rather than query execution, but the description does not explicitly disclose safety, auth needs, ordering, or retention 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?

Two short sentences deliver the core purpose and use cases without bloating the definition. The phrase 'recorded by Bytebase' is slightly redundant with the tool title, but it does not waste meaningful space.

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 two-parameter list tool with no output schema and no annotations, the description gives the core intended uses but leaves out details such as what fields history entries contain and how results are sorted beyond 'recent'. This is adequate but not thorough.

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 effectively high because both parameters have descriptions, including a default for limit and the filtering purpose of database. The description adds no extra parameter-level detail beyond the schema, so a baseline rating 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 identifies the tool as a source of recent SQL Editor queries recorded by Bytebase, with concrete use cases. It is not purely a restatement of the title, though it does not explicitly name or contrast the sibling bytebase_query.

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?

It gives clear context for when to use the tool: recovering a previously run query or learning how a table is normally joined. However, it does not name alternatives or explicitly say when not to use this tool, so it stays just short of full routing 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?

With no annotations provided, the description carries the burden of behavioral transparency. It states that the tool returns only names and row counts, which is a key behavioral trait that helps an agent know what to expect. It also mentions the scale of the database to justify its behavior. This goes beyond the schema definition and adds value.

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 (three sentences) and front-loaded with the core purpose, then provides usage guidance and return scope. Every sentence adds value without 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?

Given the tool's simplicity (3 params, no output schema), the description is sufficient. It covers usage context and the return format, and the schema covers parameters. It could mention response format details beyond names and row counts, but not necessary for a search 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 has 100% description coverage, so the baseline is 3. However, the description adds meaning to the 'pattern' parameter by clarifying it matches on table names first and then column names, and it explains the default limit behavior in context. This slight enhancement justifies a 4.

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 that this tool finds tables by name or column name within a database. It also distinguishes itself from dumping a schema and mentions the scale of production databases (~1000 tables), which sets specific expectations for its use.

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?

It explicitly says 'Prefer this over dumping a schema' and mentions the alternative bytebase_describe_table for columns, which provides clear guidance on when to use this tool versus alternatives. Although it doesn't list all possible exclusions, the key context is covered.

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?

Although annotations are absent, the description clearly discloses the consequential side effect: submitting the plan starts the approval workflow and, on approval, Bytebase creates the rollout and runs the SQL. It also warns against premature submission with a specific 'Do not call unless' note, compensating fully for the missing 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?

Three purposeful sentences: the first states the action, the second provides the workflow context, and the third adds a necessary guardrail about labels. No redundant filler or repeated schema content.

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 two-parameter tool with no output schema and no annotations, this description covers purpose, side effects, trigger conditions, and optional-parameter handling. An agent has enough context to decide whether and how 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?

Both parameters are fully described in the input schema, so the baseline is 3. The description adds valuable semantic context by telling the agent where the plan value comes from (bytebase_create_plan) and how to treat labels: check the project's label definitions and ask the user instead of inferring them.

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 and resource — "Open a review Issue for a Plan" — and distinguishes this from sibling tools such as bytebase_create_plan and bytebase_list_issue_labels. It also clarifies the tool's role in the approval workflow (starting the rollout after approval), leaving no 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?

It explicitly says when to call it: after bytebase_create_plan and only after the user confirms the plan is ready. It also gives a concrete condition for not calling it from the label workflow, telling the agent to check bytebase_list_issue_labels first and ask the user rather than guessing.

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 no annotations provided, the description carries full behavioral disclosure burden and does so well: title edits redirect to the review Issue, statement edits create a new immutable Sheet and repoint the plan, and post-rollout changes are refused. These are important side effects beyond a generic 'update' wording.

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?

Three dense sentences front-load the core action and then add distinct constraints and side effects. Every sentence earns its place and there is no unnecessary repetition of schema details.

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 mutating tool with no annotations and no output schema, the description covers the editable fields, lifecycle limitations, side effects, and supported plan provenance. An agent has enough context to call it correctly and anticipate important behavioral outcomes.

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 50%, so the description compensates by explaining what the optional title, description, and statement parameters do, including statement's Sheet-repointing behavior and title's Issue redirection. It adds real meaning beyond the raw schema, though it says little specific about the description parameter.

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 opens with a specific verb and resource: 'Edit a plan's title, description, and/or SQL statement.' It also distinguishes the tool from create/get/submit/close plan siblings by detailing its update scope and the special-case behavior around review 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?

It gives explicit when-to-use and when-not-to-use conditions: the tool works before and after submission, statement changes are refused after a rollout, and only single-spec plans created by bytebase_create_plan are supported. This is enough for an agent to route correctly.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses what the tool returns (server version, identity, token validity) and implies it is a read-only, safe diagnostic, but it does not explain potential side effects (though likely none) or what happens on failure. It could be more explicit about being non-destructive, but the described behavior is clear enough.

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, front-loaded with the core purpose, followed by a clear usage trigger. Zero waste, 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 zero-parameter, read-only diagnostic tool, the description is almost complete. It covers what it does and when to use it. The only minor gap is not explicitly stating that it performs no side effects or changes, but given the tool's simplicity and the output list provided, this is a minor omission.

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 0 parameters, and schema coverage is 100%, meaning there is nothing for the description to add. With zero parameters, baseline is 4, and the description appropriately adds context about what the tool returns without needing 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?

States a specific verb (verify) and resource (Bytebase token) with concrete outputs (server version, identity, token validity). The title explicitly frames it as identity & connectivity check, which further clarifies its purpose. Distinct from siblings, which are all data/resource operations (list, search, describe, query, create, etc.), so an agent can tell it apart immediately.

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?

Provides explicit guidance to run this tool first when any operation returns 401/403, which is a clear and actionable use case. However, it does not mention when NOT to use it or alternatives (e.g., other auth-related tools), but given the sibling context shows no other similar tool, the guidance is sufficient.

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