Bytebase: list databases

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.