OceanBase MCP

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.5.2
Disambiguation4/5
Most tools have distinct purposes, but ob_describe_table and ob_get_table_schema overlap in returning column metadata, differing only in policy filtering. Similarly, ob_list_tables and ob_search_catalog both deal with table listings, though search is broader.
Naming Consistency3/5
All tools use the 'ob_' prefix, but verb patterns vary: some use verb_noun (e.g., ob_describe_table, ob_get_constraints), while others are just verbs (e.g., ob_explain, ob_query, ob_ping). This inconsistency could cause confusion.
Tool Count5/5
With 15 tools, the set covers a comprehensive range of read-only database operations (metadata, queries, diagnostics, search, policy) without being overwhelming. The count is appropriate for the domain.
Completeness4/5
The tool surface is thorough for read-only access, covering schema inspection, data sampling, diagnostics, and policy checking. Minor gaps exist, such as querying views or listing profiles beyond diagnostics, but overall coverage is strong.
Average 2.9/5 across 15 of 15 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 278 commits in the last 12 weeks
- Last stable release on July 3, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description should cover behavioral traits. It mentions 'allowed metadata' but does not clarify permissions, side effects, or what the tool returns (e.g., HTML string vs. file). This is insufficient for a tool with 13 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The single-sentence description is concise but under-specified. It omits critical details about parameters, output, and usage, making it more incomplete than concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 param, no annotations, no output schema), the description is vastly incomplete. It lacks information on how parameters affect behavior, what the output format is, and any prerequisites or limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any of the 13 parameters. With 0% schema coverage, the burden is on the description to provide parameter semantics, and it fails entirely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a self-contained HTML ER diagram from OceanBase metadata. However, it does not differentiate from sibling tools like ob_generate_er_diagram or ob_generate_entity_diagram, which may produce similar outputs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With many similar diagram-generation siblings, explicit usage context is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It describes the output but does not mention permissions, side effects, rate limits, or any limitations. For a read-like operation, the description is insufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but severely under-specifies the tool given the 6 parameters. It does not front-load the most critical information about what the compact summary includes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, no output schema, and no description of return format, the description is incomplete. Terms like 'inferred purpose' and 'key fields' are left undefined, leaving the agent with significant ambiguity about the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain any of the 6 parameters (table, schema, profile, maxColumns, includeRelated, relationshipLimit). It adds no meaning beyond the schema field definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a 'compact table summary' with specific elements like 'inferred purpose, key fields, relationship hints, and query entry points.' This verb+resource combination is specific and distinct from sibling tools like ob_describe_table or ob_get_table_schema, though it does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or when not to use it, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It mentions 'read-only' implying safety, but does not describe what happens on validation failure, the output format, or any side effects. Important behavioral details are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it omits critical details such as parameter explanations and output behavior. It is too short for the complexity of the tool, sacrificing completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain the return value, error conditions, or parameter semantics, leaving a large gap in understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 6 parameters with 0% description coverage, and the tool description provides no explanation of any parameter. The description does not add value beyond the schema structure, leaving the agent without guidance on 'sql', 'params', 'schema', etc.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates a SQL snippet for multiple specific aspects (policy, dialect, pagination, plan risk, metadata). It's a specific verb+resource. However, it does not distinguish from similar sibling tools like ob_lint_sql or ob_explain, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like ob_lint_sql or ob_policy_explain. The description only states what it does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description is too brief to disclose behavioral traits. It does not state whether the tool is read-only, performance characteristics, or what the output looks like. For a tool with zero annotations, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but lacks essential structure. It does not front-load key information or earn its place with multiple useful sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and no annotations, the description is woefully incomplete. It does not explain return values, error conditions, or how the comparison results are presented, leaving the agent with insufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds no parameter-level guidance. It does not explain the role of 'profile', 'leftSchema', 'rightSchema', or what 'visible tables' means in terms of the required 'leftTable' and 'rightTable' parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'compare two visible tables' and lists the aspects: columns, indexes, constraints, partitions. This distinguishes it from sibling tools like ob_compare_schemas and ob_compare_metadata_snapshots. However, 'visible tables' is ambiguous and could be clarified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus other compare tools (e.g., ob_compare_schemas, ob_compare_query_results). No prerequisites or exclusions are mentioned, leaving the agent without decision context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It states the tool converts 'read-only SQL', which implies a restriction to SELECT statements, but does not confirm this or explain the conversion process. It also mentions 'documented limitations' without detailing them, obscuring potential failures or edge cases. The tool's behavior regarding loss of information or unsupported syntax remains unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it very concise and front-loaded. However, it sacrifices important details for brevity. While conciseness is valued, the description lacks critical information that could be included without excessive length, such as listing the parameters or briefly explaining limitations. It earns a 3 as it is short but not efficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, no output schema, no annotations, and a large sibling set), the description is insufficient. It does not explain return values, error handling, or how to handle unsupported SQL features. The lack of guidance on when to choose this over ob_rewrite_sql or other query tools leaves the agent underinformed. The description covers only the core purpose but misses a comprehensive overview.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate by explaining each parameter's meaning. However, it only mentions 'read-only SQL' and does not describe the role of 'profile', 'sourceMode', or the required 'targetMode'. For example, 'profile' is optional but its purpose (e.g., conversion profile or tuning) is omitted. The enums for sourceMode and targetMode are not explained, leaving the agent to infer their function. This is a significant gap for a tool with 4 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (convert) and the resource (read-only SQL) and the context (between OceanBase MySQL and Oracle modes). It explicitly mentions documented limitations, which adds specificity. However, it does not differentiate from sibling tools like ob_rewrite_sql, which might also modify SQL. The verb 'convert' is specific enough for a unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It mentions 'read-only SQL' but does not clarify whether it only works on SELECT statements or what the limitations are. There is no mention of prerequisites or when not to use it. The phrase 'with documented limitations' hints at constraints but does not elaborate, leaving the agent without clear usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behaviors. It only mentions 'bounded' output without clarifying side effects, auth requirements, or what 'visible metadata' entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but lacks structure. It omits key details, making it insufficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no annotations, and no output schema, the description is severely incomplete. It does not explain what a data dictionary is or how parameters affect output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 7 parameters, the description adds no information about any parameter. It fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a data dictionary in JSON, Markdown, or HTML from visible metadata. It distinguishes from siblings like diagram generators or query tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool instead of alternatives. No context about prerequisites or appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavioral traits. It states the tool generates metadata but does not mention whether it modifies data, any access requirements, rate limits, or side effects. The word 'allowed' is ambiguous and unexplained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core function. It is appropriately concise, but could benefit from one or two more sentences to clarify behavioral context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters, no output schema, and no annotations, the description fails to provide adequate completeness. It does not explain parameter roles, output format, or operational constraints, leaving significant gaps for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about the 11 parameters. The agent must infer parameter meanings from names alone, which is insufficient. The description adds no semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool generates Mermaid and JSON ER metadata from OceanBase table metadata and relationships. The verb 'Generate' and resource 'ER metadata' are specific, but it does not differentiate from siblings like ob_generate_entity_diagram or ob_generate_er_html, missing some sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, use cases, or exclusion criteria. This leaves the agent without context for choosing this tool over similar ones.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 mentions 'allowed ER metadata' implying some access control but does not disclose read/write behavior, side effects, or permissions required. This is insufficient for a complex tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks structure. It front-loads the main purpose but omits critical details, so it achieves conciseness at the expense of clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 parameters, no output schema, no annotations), the description is severely incomplete. It fails to explain expected outputs, parameter interactions, or any usage constraints, leaving the agent with insufficient information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any of the 13 parameters. With 0% schema description coverage, the agent has no additional guidance on how to use parameters like 'depth', 'table', 'title', etc., making it very difficult to invoke correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates documentation in Markdown, PlantUML, and DOT formats from ER metadata. However, it does not distinguish this tool from siblings like 'ob_generate_er_diagram' or 'ob_generate_er_html', which could lead to confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives. With many similar ER generation tools in the sibling list, the description lacks context for choosing the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions 'bounded' and 'visible metadata' but doesn't explain what that means in practice (e.g., does it mutate data? require permissions?). Lacks details on output, limits, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded. However, it sacrifices detail for brevity, missing important context about parameters and behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 10 parameters, no output schema, no annotations, and many siblings, the description is severely incomplete. It does not define 'onboarding documentation', 'bounded', or how to use the various constraints, leaving the agent without adequate guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, placing the burden on the description. The description only vaguely references 'metadata' and 'business glossary hints', which correspond to some parameters, but fails to explain title, format, maxTables, tablePattern, and others. No parameter semantics provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates onboarding documentation from OceanBase metadata and business glossary hints. The verb 'Generate' and resource 'onboarding documentation' are specific, but the phrase 'bounded' is vague. Among many ob_generate_* siblings, it distinguishes itself by focusing on onboarding, but overlap with ob_generate_data_dictionary or ob_generate_schema_doc is not addressed, so not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or avoid this tool. The description implies it's for onboarding documentation, but doesn't compare to alternatives like ob_generate_schema_doc or ob_generate_table_doc. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It hints at permissions ('allowed') but does not state that the operation is read-only, has no side effects, or any other behavioral characteristics. The transparency is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. While it is very short, it earns points for efficiency, though it may be overly terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters, no output schema, and no annotations, the description is severely lacking. It does not describe the return format, what constitutes constraints, or handle edge cases. One sentence is wholly inadequate for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description adds no meaning to the three parameters (table, schema, profile). It does not explain the role of schema or profile, leaving the agent without semantics beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Return), resource (constraints), and scope (for an allowed OceanBase table). It effectively distinguishes from sibling tools like ob_get_indexes, though it could be more specific about the types of constraints returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 over alternatives such as ob_get_indexes or ob_get_table_schema. There is no mention of prerequisites or contexts where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 implies a read-only operation but does not explicitly state safety, permissions, or potential side effects. An agent might infer it is non-destructive, 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of a single sentence. However, it is too minimal and lacks structure, providing no additional details beyond the purpose. Front-loaded but insufficient for a useful tool description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters, no output schema, and no annotations, the description is highly incomplete. It does not explain return values, parameter roles, or usage context, leaving the agent without essential information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no explanation of the three parameters (table, schema, profile). The agent has no context on their meaning or required formats beyond the schema's basic type constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns indexes for an OceanBase table, specifying verb and resource. It distinguishes from sibling tools like ob_get_constraints or ob_get_partitions, but could be more precise about the scope (e.g., all indexes or specific types).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like ob_describe_table or ob_get_table_schema. The description lacks context for when it's appropriate or what prerequisites exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It only describes the return content, omitting behavioral traits like read-only nature, permission requirements, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and front-loaded with the main purpose, but it sacrifices completeness for brevity. It could include more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters and no output schema or annotations, the description is insufficient. It does not explain the return format, filtering behavior, or how parameters interact, leaving major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%; the description gives no explanation of the 8 parameters. Their purpose and usage are entirely undefined, requiring the agent to infer from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a 'compact, policy-filtered schema map' with specific content (table summaries, key fields, relationship hints). It is specific about the resource and action, but lacks differentiation from similar siblings like ob_get_table_schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as ob_list_tables or ob_describe_table. The description does not mention context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must fully disclose behavior. It only says 'read-only' but does not mention potential performance impacts from parameters like includeSample, includeRelated, or auth requirements. Overall minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but lacks detailed structure. It is front-loaded with the verb and resource, but content-wise it is under-specified for such a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 parameters, no output schema, no annotations, and many sibling tools, the description fails to provide enough context for correct usage. The term 'table context' is undefined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% with 9 parameters. Description adds no information about any parameter's purpose, leaving the agent to guess what each parameter does.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'return the common read-only table context needed for SQL drafting and data inspection', which is a specific verb+resource. However, it does not differentiate from siblings like ob_describe_table or ob_get_table_schema, leaving ambiguity about what 'context' includes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description mentions use for SQL drafting and data inspection but provides no guidance on when to use this tool versus alternatives, nor any exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It only states the purpose but does not explain what success/failure looks like, whether it returns a status or throws errors, or any permission requirements. This is insufficient for a mutation-like check.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at one sentence, but it omits critical details about parameters and output. It is not an example of efficient specification; rather, it is incomplete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description should cover the parameter 'profile' and the return value. With no output schema and zero parameter documentation, the description fails to provide a complete picture for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one optional parameter 'profile' with 0% description coverage in the schema. The tool description does not mention this parameter at all, leaving the agent without any understanding of its meaning or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Verify' and the resource 'OceanBase connection'. It clearly differentiates from sibling tools, which focus on schema exploration and diagnostics, by indicating a connection health check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings like ob_query or ob_describe_table. It does not specify prerequisites or scenarios where ping is appropriate, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It mentions that the tool avoids returning large inline HTML, which implies a file or output side effect, but it does not describe whether the tool is read-only, what permissions are needed, or if it creates/destroys any resources. The behavioral disclosure is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it is also vague. It could be more informative without being verbose. The structure is acceptable for a brief description, but it sacrifices clarity for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (16 parameters, no annotations, no output schema), the description is far from complete. It does not explain what the output is (e.g., a command script, file paths), how to use the parameters, or any pre/post conditions. An agent would struggle to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 16 parameters with 0% description coverage, meaning no parameter descriptions are provided. The tool description adds no explanation of parameters. For example, 'depth', 'strategy', 'chunkSize' are undefined. The agent must guess parameter meanings from names and enums, which is insufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: planning local ER HTML export commands for large OceanBase schemas, and distinguishes itself by noting it avoids returning large inline HTML. However, 'plan' is somewhat vague; it is unclear whether it generates commands, outputs files, or just prepares items. Nevertheless, it is specific enough to convey the core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 its siblings (e.g., ob_generate_er_html, ob_generate_er_diagram). There is no indication of prerequisites, alternatives, or conditions under which this tool is preferred. The agent would have to infer usage context from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the tool does not read the database. It does not disclose other behavioral traits such as side effects, performance implications, or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, consisting of one sentence that front-loads the verb. However, this brevity sacrifices essential details, making it less effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, no output schema, and no annotations, the one-sentence description is grossly incomplete. It fails to explain how to use the tool or what the summary output looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds no meaning to any of the 5 parameters. It provides no hints about the purpose of 'rows', 'columns', 'profile', 'sessionId', or 'maxTopValues'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool summarizes already returned query rows without reading the database, using a specific verb-resource pair and distinguishing it from database-reading tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies it is for in-memory summarization but does not mention when not to use it or specify alternative tools for different contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 mentions finding relationships via FK and naming but does not disclose behavioral traits such as whether it modifies data, required permissions, rate limits, or what happens if the table is not found. The description lacks depth on the 'conservative naming' approach.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is too short for a tool with five parameters and no annotations. It is under-specified, leaving critical details missing. While concise, it sacrifices necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (5 parameters, no output schema, no annotations, 0% schema description coverage), the description is vastly incomplete. It fails to explain key concepts like 'conservative naming-based relationships', the meaning of depth/limit, or how schema and profile parameters affect results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no information about the five parameters (table, depth, limit, schema, profile). The agent must rely solely on the schema, which lacks descriptions. The description adds no semantic value beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'find', the resource 'related tables for an OceanBase table', and the method using foreign-key and naming-based relationships. It distinguishes this tool from siblings like ob_get_constraints or ob_describe_table by specifying the scope of finding relationships beyond just constraints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives. The description does not mention when to prefer this over sibling tools like ob_get_constraints or ob_generate_er_diagram, nor does it exclude scenarios where it should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description should disclose behavior. It does not state if the tool is read-only, requires permissions, or how impact is determined. Users are left guessing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with a clear verb. It is concise but sacrifices necessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no behavioral details. The description omits what the tool returns (e.g., list of affected snippets, severity), making it incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
0% schema description coverage and the description fails to explain any parameters. Terms like metadataDiff, sqlIndex, profile, and maxResults remain undefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: analyze impact on indexed SQL snippets from a metadata diff. It distinguishes itself from siblings like ob_compare_metadata_snapshots and ob_analyze_metadata_impact by focusing on SQL snippets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use or alternatives. The description lacks context for selecting this tool over similar ones like ob_analyze_metadata_impact.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It only states the tool summarizes impact but does not disclose output format, authentication needs, side effects, or whether it is read-only. The lack of output schema exacerbates the opacity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loading the main purpose. However, it sacrifices informativeness for brevity. A slightly longer description with structured details would be more helpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, including complex nested objects, and no output schema or annotations, the description is too minimal. It fails to explain what the tool returns, how to format the diff input, or what qualifies as 'impact'. The tool's complexity demands more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only mentions metadataDiff, sqlIndex, and businessGlossary by name but provides no meaning for profile, maxResults, or the structure of the object-type parameters. This leaves the agent with insufficient information to correctly populate inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Summarize metadata diff impact' clearly indicates the verb (summarize) and resource (metadata diff impact). The mention of optional SQL usage index and business glossary evidence adds specificity. However, it does not fully differentiate from siblings like ob_generate_metadata_change_report which also likely summarize changes, but the focus on 'impact' provides some distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus siblings. The description mentions optional inputs but does not state prerequisites, alternatives, or scenarios. For example, it does not clarify when to prefer this over ob_generate_metadata_change_report or ob_compare_metadata_snapshots.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Mentions read-only but no annotations exist. Lacks disclosure of side effects, permissions, or output format beyond 'evidence-based plan findings'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but overly minimal; front-loads main action but omits essential details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, no output schema, and no annotations, the description is severely incomplete, lacking parameter explanations and return value details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and description provides no information about any of the 4 parameters (sql, params, maxRows, profile). Fails to add value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool runs EXPLAIN for read-only SQL and returns plan findings. However, with sibling ob_explain, it could better differentiate the 'evidence-based' analysis aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Indicates use for strictly read-only statements, but does not specify when not to use or suggest alternatives like ob_explain.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. 'Check' implies read-only, but the description does not explicitly state it is non-destructive, disclose potential side effects, or describe what happens if files are missing. This is insufficient for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at 14 words, front-loading the core action. However, it sacrifices information about parameters, which would be valuable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations, output schema, and parameter descriptions, the description is too brief to be complete. It does not explain the output, expected effects, or provide enough context for the agent to use the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% parameter description coverage, and the description does not mention the 'profile' parameter at all. No meaning is added beyond the schema's type string, leaving the agent without guidance on what profile values are valid or how to use it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks local OpenCode config, agent, and query skill files. It uses a specific verb and resource, but does not differentiate from sibling tools that may also involve checking configuration or status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It mentions 'for the current project' but does not suggest prerequisites, when not to use, or how it compares to other ob_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description partially discloses behavior: it does not read the database or store row values. However, it omits important details such as max rows (1000 from schema), how differences are returned, and any side effects or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it is too brief for a tool with 9 parameters. The key function is front-loaded, but the lack of parameter detail sacrifices completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, annotations, and any parameter descriptions, the description is wholly inadequate. It does not clarify what 'compare' outputs, how to use keys, or the result format, making it hard for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any of the 9 parameters (e.g., 'keyColumns', 'compareColumns') despite 0% schema description coverage. The agent receives no additional meaning beyond the property names in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('compare') and resource ('already returned query results'). It distinguishes this tool from siblings like ob_compare_schemas or ob_compare_tables, making it clear that it operates on query results rather than metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives (e.g., ob_compare_metadata_snapshots). It implies that it compares in-memory results without reading the database, but does not state prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It does not mention permissions, performance, output format, or any side effects. The phrase 'allowed table' hints at access control but leaves ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a single sentence. However, it sacrifices necessary detail for brevity, making it under-specified for the complexity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, no output schema, and no annotations, the description is far from complete. The agent lacks information about return values, parameter usage, and behavioral constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description fails to explain any of the 4 parameters (table, schema, profile, maxColumns). For instance, maxColumns could limit returned columns, but it's not mentioned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns column metadata for a table, but does not differentiate it from similar sibling tools like ob_get_table_schema, which might also return column info. The verb 'describe' is standard but not uniquely distinguishing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description only states what it does, without indicating prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits, but it only states the function's purpose. It does not mention whether the operation is read-only, requires special permissions, or handles errors, leaving significant gaps 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one short sentence), but it is too brief to be effective. While it front-loads the core purpose, it sacrifices necessary detail and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of output schema, annotations, and parameter descriptions, the tool's completeness is severely lacking. The description does not cover return format, error behavior, or usage context, making it inadequate for reliable agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds no explanation of the three parameters (table, schema, profile). The agent must rely solely on parameter names, which is insufficient for proper invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Return partition metadata for an allowed OceanBase table' clearly specifies the action (return) and resource (partition metadata), and it distinguishes this tool from siblings like ob_get_table_schema and ob_describe_table, which return different aspects of a table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 ob_get_indexes or ob_get_constraints. There is no mention of prerequisites, context, or exclusion criteria, leaving the agent to infer usage without support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions 'policy-filtered' and 'allowed' table, implying authorization and filtering, but does not disclose specifics like read-only nature, rate limits, or what 'bounded' entails. Without annotations, the description partially addresses behavior but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it omits critical details, making it under-specified. It is front-loaded but does not earn its place by being sufficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 parameters, no output schema, no annotations), the description is severely incomplete. It fails to explain what a column profile is, how policies filter, or how parameters influence results, leaving the agent without sufficient information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 8 parameters, the description adds no information about any parameter. It fails to explain what parameters like 'columns', 'profile', or 'rowLimit' mean or how they affect the output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'column profiles' with qualifiers 'bounded' and 'policy-filtered', which distinguishes it from sibling tools like ob_describe_table or ob_get_table_stats. However, the term 'profile' is not defined, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives such as ob_describe_table or ob_sample_rows. No context is provided for appropriate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions access policy filtering but omits key details like read-only nature, side effects, rate limits, or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence, but it fails to structure information (e.g., separating purpose from parameter details). It could be expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and 0% parameter coverage, the description is highly incomplete. An agent cannot determine query syntax, limit behavior, or the meaning of schema/profile without additional knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain any of the four parameters (query, limit, schema, profile), leaving the agent to infer their purpose from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Search schemas, tables, columns, and comments', and includes a specific filtering condition ('filtered by access policy'), distinguishing it from sibling tools like ob_list_tables or ob_describe_table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., ob_list_tables, ob_describe_table). The description lacks context for optimal usage or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should disclose behavioral traits. It only says 'with confidence and evidence', which is vague, and does not mention authentication, rate limits, or that the operation is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but the phrase 'with confidence and evidence' adds no functional value and could be replaced with more actionable info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, no output schema, and no annotations, the description is insufficient. It does not explain how results are presented, how the 'limit' parameter works, or how multiple resource types are combined in output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain parameters. It lists searched resources but does not link them to any parameter (e.g., 'schema' to filter by schema, 'includeGlossary' to control glossary search). No parameter purpose is clarified beyond the schema's basic names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (search) and the resources (schemas, tables, columns, comments, business glossary). It uses specific verbs and nouns, but does not differentiate from sibling tools like ob_search_business_glossary or ob_search_catalog.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not specify when not to use it or mention any prerequisites, making it difficult for an agent to decide which search tool to call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions 'from visible table metadata' but does not disclose behavioral traits like performance impact, error conditions, or whether it accesses data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, no redundancy. However, could be expanded with essential details without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, 4 parameters with 0% coverage, and no annotations. The description fails to specify return format, limitations, or additional context needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain any parameter semantics, such as the role of 'maxColumns' or 'schema' and 'profile'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool detects specific types of columns (status, type, channel, etc.) from visible table metadata, with a specific verb and resource that distinguishes it from siblings like ob_detect_time_columns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as ob_describe_table or ob_get_table_schema. Lacks when-not-to-use or prerequisite context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature and that it does not execute, but fails to explain the role of key parameters like runExplain, maxRows, params, or the meaning of 'explain' output. With no annotations, more detail is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise and front-loads the core action, but the brevity sacrifices necessary detail for a tool with 8 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, 0% parameter coverage, and many sibling tools, the description is far too sparse. It leaves the agent guessing about input formats, output, and when to use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description adds no parameter information beyond hinting at 'sql' and 'filePath'. 8 parameters remain undefined, leaving the agent without guidance on how to use them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool explains a read-only SQL snippet, specifying it can come from text or a local project file. It distinguishes from related tools like ob_analyze_query_plan by mentioning the source, but does not explicitly differentiate from ob_explain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like ob_explain or ob_analyze_query_plan. The description only states what it does, not when to choose it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It mentions 'safe pagination' but lacks details on permissions, performance impact, concurrency, or error handling. The read nature is clear, but side effects and limitations are not addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with 16 words, conveying the core purpose efficiently. It earns high marks for conciseness, though it could benefit from a brief second sentence on parameter guidance without sacrificing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, no annotations, no output schema, many siblings), the description is insufficient for correct selection and invocation. It lacks parameter roles, return format, error conditions, and comparative context with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate by explaining key parameters. It only hints at 'timeColumn' and pagination (pageSize, page) but does not describe any of the 7 parameters explicitly. Users cannot map description to schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads recent rows from a table using a time column, specifying the action and resource. It differentiates from siblings like ob_sample_rows (random) and ob_query (general query), but could be more precise about what defines 'recent'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving recent rows with a time column but provides no explicit guidance on when to use this tool over alternatives like ob_sample_rows or ob_query. No exclusions or when-not-to-use scenarios are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only states that the diagram is 'local' and 'entity-focused' but does not clarify what these mean in terms of side effects, permissions, or mutability. There is no contradiction with annotations as none exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core purpose and output formats. While concise, it sacrifices important details that could be included without significant length increases. It is front-loaded with the key verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 parameters, no output schema, no annotations), the description is far from complete. It does not explain the meaning of 'entity-focused', the scope of 'local', or what kind of ER diagram is generated. The minimalism leaves agents without sufficient context to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage and 13 parameters, the description only hints at three parameters (businessTerm, table, formats) and mentions optional HTML. It fails to explain the purpose or constraints of depth, title, schema, profile, maxTables, minConfidence, includeInferred, maxRelationships, and relationshipMode.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's action (generate an ER diagram) and key inputs (business term or table) and outputs (Mermaid, JSON, HTML). However, it does not distinguish this tool from the very similarly named sibling tool 'ob_generate_er_diagram', leading to potential confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as ob_generate_er_diagram or ob_generate_er_html. It also lacks information about prerequisites or scenarios where this tool is most appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'read-only', implying no side effects or mutations. However, with no annotations, it does not disclose additional behavioral traits like authentication requirements, rate limits, or what happens with invalid inputs. It is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence) and front-loaded. However, given the complexity (9 parameters, 0% schema descriptions), the conciseness sacrifices necessary detail. It is not overly verbose, but lacks completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters, no output schema, and no annotation, the description is insufficient. It does not explain return format, parameter interactions, or how the 'context' is structured. The agent would lack critical information to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description mentions three input sources (mapper, SQL file, table) but does not map them to specific parameters (sql, filePath, table). Other parameters like line, maxTables, maxColumns, format, schema, profile are entirely unexplained, leaving the agent with no semantic guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates 'read-only table and column context' for three types of input: MyBatis mapper, SQL file, or explicit table. The verb 'generate' and the resource are specific, but it does not differentiate from similar sibling tools like ob_get_table_context or ob_describe_table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The context signals and sibling list show many related tools, but the description offers no criteria for selecting this tool, such as 'use for MyBatis mapper context specifically'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions 'bounded' and 'without returning sample values' but does not explain what 'bounded' means, whether the operation is read-only, or any permission requirements. The behavioral context is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that conveys key points: bounded, JSON/Markdown, one table, no sample values. It is efficient but could benefit from a bit more structure or additional sentences to improve completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, no output schema, no annotations), the description is severely inadequate. It does not describe the output structure, parameter usage, constraints, or any contextual details needed for proper invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for 10 parameters. The description only implicitly references the 'table' parameter and the output format, but fails to explain the purpose of other parameters like title, schema, profile, maxColumns, maxExamples, relationshipLimit, includeQueryExamples, and includeRelationships. The agent cannot correctly set these parameters without external knowledge.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates JSON or Markdown documentation for a single visible table, and explicitly excludes sample values. This distinguishes it from sibling tools like ob_describe_table and ob_get_table_schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 over alternatives, such as ob_generate_schema_doc or ob_get_table_ddl. It does not mention scenarios, prerequisites, or decision factors like choosing between JSON and Markdown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states that the tool does not execute the target query, which is a key behavioral trait. However, with no annotations provided, the description should also disclose other aspects like side effects, permissions, or limits. It does not, relying only on the read-only and safety preview hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 18 words, which is concise and front-loaded with the main verb. However, given the complexity of the tool (8 parameters, no schema descriptions), the description could benefit from a bit more structure, such as listing the key parameters or outputs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters, no output schema, and no annotations. The description only provides a high-level overview. It lacks information on return values, parameter semantics, and usage context. For an agent to correctly invoke this tool, more detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the 8 parameters have descriptions in the input schema. The description itself does not explain any parameter purpose or constraints. This is a significant gap, as the agent has no information about what each parameter controls.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool prepares candidate tables, fields, read-only SQL drafts, and safety previews without executing the query. The verb 'prepare' is specific and the resource is well-defined. However, it does not explicitly differentiate from sibling tools like ob_generate_query or ob_build_select, which may have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, typical use cases, or situations where it should be avoided. This leaves the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear full burden. It mentions 'bounded' and 'sampled' but does not disclose whether the tool is read-only, its performance impact, error handling, or output format details. Critical behavioral traits are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the main output components. It is not verbose, but it could benefit from slight restructuring to separate output from input constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, no output schema, and no annotations, the description is too sparse. It does not cover return structure, edge cases, or limitations beyond 'bounded'. The tool's complexity demands more detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain any parameter's purpose or how they affect the profile. For example, 'profile', 'rowLimit', and 'topValues' are not described. The description only lists what the output contains, not how to control it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a 'table-level profile' with concrete components (metadata counts, key fields, time/status fields, sampled null overview). The verb 'Return' indicates output, and 'bounded' hints at limits. However, it does not explicitly distinguish this from sibling tools like ob_describe_table or ob_get_table_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as ob_profile_columns or ob_get_table_summary. The description lacks context about prerequisites, typical use cases, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a key behavioral trait: read-only execution. However, with no annotations provided, it does not elaborate on other aspects like error handling, response format, or authentication needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence with no wasted words. However, it could be slightly expanded to cover key details without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has four parameters, no output schema, and no annotations, the description is insufficient. It does not explain query execution behavior, result format, or how parameters are used.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to any of the four parameters (sql, params, maxRows, profile). It does not explain what 'params' represents or the purpose of 'maxRows'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Run') and resource ('SQL statement against OceanBase'), and adds the key constraint 'strictly read-only'. However, it does not differentiate from sibling tools like ob_explain or ob_sample_rows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for read-only queries but provides no explicit guidance on when to use this tool versus alternatives (e.g., ob_sample_rows, ob_explain) or when not to use it (e.g., for DML operations).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks behavioral disclosure beyond the basic function. No annotations are present, so the description should convey read-only nature, required permissions, or any side effects. It does not, leaving the agent to assume safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It is front-loaded and to the point, though slightly under-specified for a four-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has four parameters, no output schema, and no annotations, the description is insufficiently complete. It does not explain what 'likely' means, the return format, or how parameters affect behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention any of the four parameters (table, schema, profile, maxColumns). With 0% schema coverage, the description adds no value beyond the schema itself, failing to explain required vs optional or provide context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool detects likely create, update, and business time columns from visible table metadata. It uses a specific verb and resource, distinguishing it from sibling tools like ob_detect_dimension_columns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not specify when to use this tool versus alternatives like ob_describe_table or ob_profile_columns. No context about prerequisites or limitations is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states 'strictly read-only', indicating non-destructiveness, but provides no details on output format, authentication needs, rate limits, or other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core purpose efficiently. However, it is slightly under-specified for completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain the parameters or expected output, making it insufficient for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the tool description does not explain any of the four parameters (sql, params, maxRows, profile). The agent has no guidance on how to use them beyond the schema's structural constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs EXPLAIN on a SQL statement, which is a specific verb+resource. It distinguishes from siblings like ob_query (which runs actual queries) and ob_policy_explain (explains policies).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for read-only SQL statements, but does not explicitly mention when to use this tool over alternatives like ob_query or ob_policy_explain. No exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the tool does not execute SQL and includes policy context and metadata hints, but lacks detail on return format, limitations, or side effects; with no annotations, the coverage is moderate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundancy, but overly terse; could be more structured to include key aspects without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output description, error handling, and parameter details; insufficient for a tool with no output schema and 5 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and no parameter information in the description, the agent receives no additional meaning beyond the raw schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool explains a SQL error with policy context and metadata hints, and distinguishes it from siblings like ob_explain and ob_policy_explain by specifying it does not execute SQL.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like ob_policy_explain or ob_lint_sql; the description only implies usage for error explanation without execution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It does not disclose behavioral traits such as side effects, permissions, limitations, or the format of the output beyond stating it is Markdown or HTML.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff, but it could be more informative without losing conciseness by including parameter details or usage notes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, 0% schema coverage, no output schema, and no annotations, the description is insufficient. It does not explain the required metadataDiff, optional parameters, or what the report contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description only mentions 'diff and impact evidence' without explaining the parameters (e.g., title, format, summaryOnly, profile, impact). It adds minimal meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a Markdown or HTML metadata change report from diff and impact evidence. It specifies the output format and the inputs, distinguishing it from sibling report generators like ob_generate_performance_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. The description implies it requires diff and impact evidence but does not mention prerequisites, exclusions, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 only says 'Generate bounded JSON or Markdown documentation' without explaining what 'bounded' means operationally (e.g., limits enforced by maxTables, relationshipLimit, etc.), nor does it mention read-only nature, permissions, or performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and not verbose, but its brevity sacrifices necessary detail. It could be restructured to front-load the purpose while still including key parameter hints. As is, it is minimally acceptable in length but inadequate in content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, no annotations, no output schema), the description is severely incomplete. It does not explain the 'bounded' concept, parameter roles, or output format structure. The agent would need to guess how to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 9 parameters with 0% schema description coverage. The description adds no meaning to any parameter; it only loosely references 'one schema' which corresponds to the 'schema' parameter. Critical parameters like title, format, maxTables, tablePattern, etc., are left entirely unexplained, leaving the agent without guidance on how to populate them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates bounded JSON or Markdown documentation for visible tables in one schema. The verb 'Generate' and resource 'schema documentation' are specific, and the mention of 'JSON or Markdown' clarifies output format. Among many sibling 'generate' tools, this one is distinct as it pertains to schema-level documentation, not table or query-level.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implicit usage context by mentioning 'one schema' and 'visible tables', but it does not explicitly state when to use this tool versus alternatives like ob_generate_table_doc or ob_generate_data_dictionary. No when-not-to-use or alternative guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions 'bounded' and 'visible' metadata, implying scope and output format, but does not clarify output structure, whether it modifies data, or error states. It provides some behavioral context but is incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the main purpose. It is concise, but a bit more structure (e.g., listing key parameters briefly) could improve clarity without losing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 optional parameters, no output schema, and no annotations, the description is insufficient. It does not explain output shape, constraints, or how to use parameters effectively. The tool's capabilities are only vaguely outlined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It only hints at format through 'JSON or Markdown' but does not detail 'schema', 'profile', 'maxTables', or others. The enum for 'format' is implicitly covered, but other parameters remain undefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: generating a bounded JSON or Markdown data dictionary from visible table and column metadata. It uses specific verbs and resource nouns. However, it does not differentiate from the similar sibling tool 'ob_generate_data_dictionary', which may cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor does it mention any prerequisites or exclusions. The sibling list is extensive, but the description lacks any contextual cues to help the agent decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions 'bounded, policy-filtered' which implies security restrictions and limited results, but lacks details on side effects, authentication needs, or other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 15 words, front-loaded with action. No unnecessary information. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four parameters, no output schema, and no annotations, the description is too brief. It does not explain what 'policy-filtered' means, parameter roles, or what the returned metadata contains, leaving the agent without sufficient context to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description provides no explanation of parameters. The schema defines four fields, but the agent gets no additional meaning from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns metadata for specific object types (views, sequences, etc.) using a specific verb. However, it does not explicitly differentiate from similar sibling tools like ob_describe_table or ob_get_table_schema, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies it is for non-table objects, but does not state when-not or provide alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions 'allowed' but does not explain access control. It does not disclose if the tool is read-only, whether it requires special permissions, or how output formatting differs between 'native' and 'structured'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks structured formatting (e.g., bullet points). It is not verbose, but could be more informative without becoming long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, 4 parameters with 0% coverage, and 62 sibling tools, the description is incomplete. It does not explain return format, the distinction between native vs structured DDL, or how parameters affect output. Also missing any example or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Description adds no meaning to parameters (table, schema, profile, maxColumns). For example, it does not clarify what 'profile' or 'maxColumns' controls or how 'schema' differs from the table's schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the action ('Return') and resource ('DDL metadata for an allowed OceanBase table'), clearly distinguishing this from siblings like ob_describe_table or ob_get_table_schema. The title also reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. It does not explain what 'native or structured' means or when each format is appropriate. Siblings are numerous but no differentiation provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It mentions 'policy-filtered' but does not explain what policies apply, whether the operation is read-only, or any side effects. Lacks details on permissions or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it concise and front-loaded. However, it is under-specified; the brevity sacrifices necessary detail, resulting in a mediocre balance between conciseness and informativeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, no output schema, and no annotations, the description is incomplete. It omits return format, pagination behavior (maxColumns), filtering options (schema/profile), and constraints. An agent using this tool would lack critical context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description only adds meaning for the 'table' parameter (one table). It does not explain 'schema', 'profile', or 'maxColumns', leaving the agent to infer their purposes without guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Return'), the resource ('table columns and types'), and a key qualifier ('policy-filtered'). It distinguishes itself from siblings like ob_describe_table or ob_get_table_ddl by focusing on schema with policy filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as ob_describe_table, ob_get_table_summary, or ob_get_table_ddl. No mention of prerequisites or scenarios where it is inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 disclosing behavioral traits. It does not explicitly state that the tool is read-only, safe, or does not modify state. While listing capabilities implies a read operation, agents benefit from explicit safety guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that immediately conveys the tool's purpose. It is front-loaded with the verb and resource, and contains no redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description should explain the return structure or format. It only lists what is included but not how the results are organized (e.g., as a list, JSON structure). Additionally, the parameter is undocumented, leaving the tool's completeness lacking for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter ('profile') with 0% schema description coverage. The description does not mention the parameter at all, leaving its purpose completely undefined. The agent cannot infer how to use the optional profile parameter from the description alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists specific resources: tool groups, tool versions, active compatibility mode, and read-only limits. It uses a specific verb ('List') and resource ('capabilities'), which distinguishes it from sibling list tools like ob_list_tables or ob_list_objects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or scenarios where this tool is appropriate, which is especially problematic given many sibling list tools exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool returns 'policy-filtered' metadata but does not disclose permissions, rate limits, side effects, or whether the listing is live or cached. Minimal behavioral context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it concise, but it is overly minimal. It could include additional context (e.g., filtering behavior, output format) without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters with no schema descriptions, no output schema, and no annotations, the description is incomplete. It does not explain how the tool filters, what the output contains, or any constraints (e.g., maximum limit). A more detailed description is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain any of the 5 parameters (limit, query, schema, profile, objectTypes), leaving the agent with no semantic guidance beyond the schema structure. The list of example object types is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('list') and the resource ('policy-filtered Oracle object metadata'), listing specific object types like views, sequences, synonyms, procedures, functions, and packages. This distinguishes it from sibling tools such as ob_list_tables or ob_get_object_metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when listing metadata for certain object types but provides no explicit guidance on when to use this tool over alternatives like ob_list_tables or ob_search_catalog. No exclusions or scenarios are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that results are filtered by access policy and user-specific, which is helpful. However, it does not explicitly state it's read-only or describe potential edge cases (e.g., empty results). Behavioral transparency is adequate for a simple list tool but could be improved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it sacrifices completeness. It could be restructured to front-load key info and include parameter details. The conciseness feels like under-specification rather than efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description should at minimum explain the parameter's role. It fails to do so, leaving the agent to guess about 'profile'. Contextually incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'profile' has no description in the schema (0% coverage) and is not mentioned in the tool description. The description does not explain what profile is, whether it's required, or how it affects results. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'List' and resource 'schemas/databases', and adds context about visibility to current user and filtering by access policy. This clearly distinguishes it from sibling tools like ob_list_tables or ob_list_profiles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., ob_search_catalog). No mention of prerequisites or scenarios. The description only states what it does, not when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry behavioral info. It correctly indicates read-only nature and that limits are respected. However, it omits details like session lifecycle, error handling on invalid session, or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose and key constraint. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a pagination tool with no output schema and no annotations, the description is too minimal. It lacks prerequisites (session must exist from ob_start_query_session), side effects (advances session cursor), and details on pagination limits. Incomplete for safe autonomous usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with no parameter descriptions. The description does not explain any parameter beyond the implied sessionId. No additional meaning is provided for orderBy, pageSize, or profile.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs the next page for a read-only query session, and the title reinforces 'Query Next Session Page'. It implies distinction from ob_query_page and ob_query_prev_page but does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings like ob_query_page, ob_query_prev_page, or ob_start_query_session. The description only states a limitation (no bypassing limits) without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behavior. It states the tool is 'read-only' and 'bounded', which is helpful. However, it does not explain what output is returned, whether checks are run as a SQL query, or any potential performance impacts or limitations like the row limit or maximum columns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence (16 words) that front-loads the action and context. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, no output schema, no annotations, and many sibling tools for data profiling and analysis, the description is insufficiently complete. It does not explain return values, how to interpret results, or what happens when parameters are omitted. The agent would need additional knowledge to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions the types of checks but does not explain the purpose of any of the 7 parameters (e.g., `profile`, `nullRatioThreshold`, `columns`). This leaves the agent without guidance on how to set parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'run' and the resource 'data quality checks', and enumerates the types of checks (nulls, duplicate key risk, dimensions, time columns). This provides clear purpose and sets it apart from sibling tools that focus on other operations like profiling or sampling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the tool is 'bounded read-only', implying safety, but it does not explicitly indicate when to use this tool over alternatives like `ob_profile_table` or `ob_detect_dimension_columns`. No when-not or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 states it returns 'evidence-based structural changes' but does not disclose side effects, permissions, or what 'evidence-based' entails. This is insufficient for a comparison tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loading the core purpose. However, it sacrifices necessary detail for brevity, earning a high but not perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain what 'evidence-based changes' means, how parameters affect behavior, or what the output structure is.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not explain any of the 6 parameters (profile, riskOnly, changedOnly, summaryOnly, beforeSnapshot, afterSnapshot). The description adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares two metadata snapshots and returns structural changes. The verb 'compare' and resource 'metadata-only snapshots' are specific, distinguishing it from siblings like ob_compare_schemas or ob_compare_tables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives like ob_compare_schemas or ob_compare_tables. While the tool name implies snapshot comparison, the description lacks usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It mentions 'bounded' but does not explain what that means (e.g., limits on differences or tables). No info on required permissions, rate limits, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence, 12 words) and front-loaded with the core purpose. However, given the complexity of 6 parameters, it may be too minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 6 parameters and no output schema, the description is extremely brief. It omits details about the 'bounded' nature, output format, and how parameters influence comparison, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no details on the 6 parameters (profile, maxTables, leftSchema, rightSchema, tablePattern, compareCommonTables). Schema coverage is 0%, so the description must compensate but fails entirely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares two schemas by table list and per-table metadata differences, which distinguishes it from siblings like ob_compare_tables (table-level) and ob_compare_metadata_snapshots (snapshot-level).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (compare schemas at table/metadata level) but lacks explicit guidance on when not to use or alternatives like ob_compare_tables or ob_compare_metadata_snapshots.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavioral traits beyond 'check'. It fails to state whether the tool is read-only, what side effects might occur (e.g., logging, performance impact), or the nature of the output (e.g., report, pass/fail). With no annotations, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the tool's purpose without excess. However, it could be structured slightly better by front-loading the verb and list. Still, it is appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and no parameters, the description carries full burden. It lacks details on return format, safety (e.g., read-only), and prerequisites. For a diagnostic tool, this is insufficient for an agent to invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100% trivially. The description adds value by listing the domains checked (profile, policy, TLS, HTTP, production hardening), which is meaningful context beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks multiple configuration domains (profile, policy, TLS, HTTP, production hardening). It uses a specific verb 'check' and specifies resources, distinguishing it from siblings that focus on single aspects (e.g., ob_list_profiles, ob_policy_explain).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. For example, it doesn't mention that this is a comprehensive diagnostic compared to specific checks like ob_ping or ob_list_profiles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the tool uses multiple evidence sources (glossary, catalog, comments, relationships), implying a read-only discovery operation. However, it omits details on authorization, rate limits, or whether results are truncated, relying on agent inference.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the core action and resources. Every part adds value, with no redundancy or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has six parameters, no annotations, and no output schema, the description fails to provide sufficient context. The agent lacks details on parameter formats, behavior, or expected results, making correct invocation difficult.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description only explains the 'term' parameter implicitly. Other parameters (limit, schema, profile, includeRelated, relationshipLimit) are not mentioned, leaving the agent to guess their meaning from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds candidate tables based on a business term, using specific sources like glossary and catalog metadata. It distinguishes from sibling tools like ob_find_columns or ob_search_catalog, though 'visible candidate tables' is slightly ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus other search or lookup tools. The description only states what it does, without indicating alternative tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It declares the tool is read-only, which is helpful. However, it does not disclose whether the SQL is executed, permission requirements, or output format. The mention of data sources (EXPLAIN, stats, indexes) adds some transparency but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but at the expense of necessary detail. It lacks structure and fails to cover key aspects like parameters or usage context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and moderate complexity (4 params, diagnostic tool), the description is incomplete. It does not explain what the report contains, how to interpret it, or any limitations. More context is needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about any of the four parameters (sql, params, maxRows, profile). This is a critical gap as the description does not compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Generate', the resource 'performance advisory report', and the sources 'EXPLAIN, table statistics, and index metadata'. It distinguishes itself from sibling tools like ob_explain or ob_get_table_stats by combining multiple data sources into an advisory report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'read-only', implying safe usage, but does not explicitly state when to use this tool over alternatives (e.g., when to use ob_explain vs this report). No guidelines on prerequisites or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral transparency. It only reveals that the query is not executed, but omits other important traits like side effects, read-only nature, required permissions, or what 'bounded' means. This is insufficient for a tool with 10 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loading the key purpose. However, given the tool's complexity (10 parameters, many siblings), a slightly more structured approach could improve usability without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is markedly incomplete given the tool's complexity: no output schema, no annotation context, no parameter guidance, and only a high-level purpose. It fails to provide enough context for an AI agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain any of the 10 parameters (e.g., sql, format, params, schema). The description adds no meaning beyond the schema, which itself lacks descriptions. This is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: generating bounded JSON or Markdown documentation for a SQL snippet without executing it. The verb 'Generate' and resource 'documentation for a SQL snippet' are specific, and the 'without executing' clause distinguishes it from sibling tools that execute or analyze query plans.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (for documentation without execution) but does not provide explicit guidance on when not to use or how it compares to alternatives like ob_explain or ob_generate_query. Given many siblings, more explicit differentiation would improve scReadabilitycores.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses read-only and non-execution behavior, but with no annotations, it lacks detail on other behavioral traits like rate limits, permission needs, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is concise and front-loaded with the key action. However, it could be more structured for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too brief given the tool's complexity (6 parameters, no output schema). It does not explain what the generated examples look like, how scenarios affect output, or what the return format is.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no clarification on any of the 6 parameters (table, schema, maxRows, profile, scenarios, maxColumns). The agent gets no help beyond the schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates scenario-based read-only SQL examples from policy-filtered table metadata without executing them. This distinguishes it from sibling tools like ob_generate_query which may execute or generate different types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not specify conditions or exclusions, leaving the agent to infer from the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the tool does not expose cached content, which is a behavioral constraint. However, with no annotations provided, the description carries the full burden and does not disclose other behaviors such as required permissions, rate limits, or whether the tool is safe (read-only hints).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded with the core purpose. While it could benefit from additional context, every word serves a purpose and there is no extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one undocumented parameter and no output schema, the description is incomplete. The agent lacks information about the output format or structure of the cache settings and counters, and the 'profile' parameter is unexplained, which is inadequate for proper tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter 'profile' with no description (0% schema coverage). The tool description does not explain what 'profile' represents or how to use it, leaving the agent without necessary semantic context to use the parameter correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns profile-scoped metadata cache settings and counters, with a specific constraint of not exposing cached content. This distinguishes it from sibling tools like ob_refresh_metadata_cache which handles cache refresh operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of appropriate contexts, prerequisites, or when to avoid using it, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions 'filtered by access policy', hinting at security behavior, but does not clarify if the operation is read-only, what privileges are required, or whether results are paginated. The description is insufficient for a tool without annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is concise but could be better structured (e.g., front-loaded key info). The brevity is acceptable, though a bit more detail would improve it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 undocumented parameters, no output schema, and no annotations, the description is too sparse. It does not explain the optional parameters (limit, schema, profile) or any usage context beyond the basic purpose. The tool's complexity demands a richer description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions in the schema. The description does not mention the parameters (limit, schema, profile) at all, failing to add meaning beyond the bare schema types. This is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'tables', specifying the scope 'visible to the current OceanBase user' and the filtering condition 'by access policy'. It effectively distinguishes from sibling tools like ob_list_profiles and ob_list_schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for viewing accessible tables, but provides no explicit guidance on when to use this tool versus alternatives (e.g., ob_describe_table, ob_get_table_schema). There are no when-not-to-use instructions or examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden. It discloses core behavior (rewrite, no execution, SELECT/WITH only) but omits details like output format, error conditions, and permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 11-word sentence is highly concise and front-loaded, but lacks structure that could separate core purpose from usage notes, making it slightly too brief for full clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and 6 undocumented parameters, the description is insufficient to guide correct invocation among 50+ siblings, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description adds no meaning to the 6 parameters (sql, params, maxRows, etc.). The agent cannot infer their roles from the description alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool rewrites SELECT/WITH SQL into a safer read-only form without execution, distinguishing it from siblings like ob_build_select (builds SQL) or ob_lint_sql (lints).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 vs. alternatives such as ob_convert_sql_dialect or ob_validate_sql_snippet, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Only states 'close' but omits side effects (e.g., resource cleanup, permission needs, error conditions). For a mutating operation, more transparency is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key action and resource. No extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, no annotations, minimal description. Lacks return value semantics, prerequisites (e.g., session must exist), and relationship to start/get session tools. Despite simplicity, agents need more to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions). The description vaguely mentions 'selected profile' but doesn't explain the purpose of either parameter (sessionId is required, profile optional). Fails to compensate for missing schema docs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'close' and resource 'in-memory query session', with clear scope 'for the selected profile'. It effectively distinguishes from sibling tools like ob_start_query_session and ob_get_query_session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., ob_start_query_session). Does not specify context like 'close after finishing queries' or 'session must be active'. Agents lack decision-making cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It clarifies that the tool does not invent relationships, implying it only reports existing evidence. However, it lacks details on permissions, side effects, error behavior, or output format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 14-word sentence that efficiently conveys the core purpose and a key behavioral constraint. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high parameter count (9), lack of output schema, and no annotations, the description is insufficient. It does not explain parameter semantics, return value nature, or provide enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 9 parameters with 0% description coverage. The description only mentions 'two OceanBase tables' broadly, leaving all 7 optional parameters (depth, schema, profile, etc.) completely unexplained. No added meaning beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it explains visible relationship evidence between two OceanBase tables, with the important qualifier 'without inventing missing relationships.' This distinguishes it from sibling tools like ob_find_related_tables or ob_describe_table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like ob_find_related_tables or ob_compare_tables. It does not mention prerequisites, limitations, or context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that the tool uses a static index and does not execute SQL or read files, implying safety and speed. However, it omits limitations (e.g., index must exist) and does not mention idempotency or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core function. Every word adds value with no repetition or fluff. Highly concise and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and no annotations, the description is too brief. It does not explain how to construct the sqlIndex parameter or how filtering with table/column works. An AI agent would lack sufficient context to use the tool reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain any of the 7 parameters (e.g., table, column, sqlIndex, maxResults). It fails to add meaning beyond the input schema, which is insufficient for an AI to know how to use the parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds project SQL usages from a static index without executing SQL or reading files. It differentiates from other find tools like ob_find_columns or ob_find_recent_rows by specifying the data source (static index) and non-invasive behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., ob_analyze_change_sql_impact, ob_find_columns). The description implies it's lightweight and safe, but does not state when to prefer it or exclude other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description transparently states it is read-only and hides parameter values, providing some behavioral context beyond a bare minimum. However, it omits error handling and side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 11 words, concise and front-loaded with the key action. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and minimal description, an agent lacks context on what the returned 'query session context' contains or how to handle responses. More detail is needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain parameters (profile, sessionId). It adds no value beyond the schema, leaving the agent without semantics for using them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns a read-only query session context without exposing parameter values, specifying verb and resource. It distinguishes from siblings like ob_start_query_session and ob_close_query_session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like ob_start_query_session, ob_query, etc. The description only states what it does, not when.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 implies a read operation but does not explain permissions, potential cost, error handling, or what happens if the table is not allowed. No mention of destructive actions, auth needs, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence of 11 words that efficiently communicates the core purpose. No wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, no output schema, and returning optimizer statistics with metadata counts, the description is too sparse. It does not describe return values, behavior on errors, or the scope of 'allowed.' Incomplete for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'for an allowed OceanBase table' but does not explain the parameters (table, schema, profile) or their valid values. No additional meaning is added beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and specifies the resource: 'table-level optimizer statistics and metadata counts for an allowed OceanBase table.' This distinguishes it from sibling tools like ob_get_table_schema (returns schema) and ob_describe_table (describes columns).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 ob_get_table_schema or ob_explain. It does not mention when-not to use it or suggest any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 the core behavior (explaining policy decisions) but does not mention side effects, permissions, or error handling. The description is minimally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the core purpose without redundant words. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description is too brief. It does not explain the return format, how to interpret results, or what 'explain' entails in terms of output structure. A more complete description is needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for parameters. The description does not mention any parameters (sql, params, profile) or their meaning. With three parameters and no schema descriptions, the description fails to add value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: explaining whether a SQL statement is allowed and which checks apply. It uses a specific verb ('Explain') and resource ('SQL Policy Decision'), distinguishing it from siblings like ob_explain (query plan) and ob_query (execute).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as ob_explain or ob_query. It lacks explicit when-to-use or when-not-to-use information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the context as 'in-memory read-only,' indicating safety and temporary nature. However, lacks details on session lifecycle, memory limits, or interaction with other session tools (e.g., ob_close_query_session).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence of 10 words is very concise. However, it could include more parameter guidance without losing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 11 undocumented parameters, no output schema, and no annotations, the description is grossly insufficient for correctly invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no explanation for any of the 11 parameters (e.g., sql, page, table, params, schema, columns, orderBy, profile, pageSize, warnings, businessTerm).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates an in-memory read-only query context for follow-up paging, refinement, and summarization. This distinguishes it from direct query tools like ob_query which execute immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for paging, refinement, and summarization, but no explicit when-to-use or when-not-use, nor alternatives like ob_query or ob_prepare_query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It does not explain what 'visible' means, whether there are auth requirements, rate limits, or any side effects. The tool has 7 parameters but no behavioral context beyond the search criteria.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 15 words, front-loading the purpose. Every word is functional with no fluff. It is appropriately sized for a read-only search tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, 0% schema coverage, no annotations, and no output schema, the description is grossly insufficient. It does not explain return values, pagination, or how to combine parameters. For a tool with 57 siblings, more context is needed to help the agent select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 5 search criteria but does not align them clearly with the 7 parameters. For example, 'name' corresponds to 'query', but this is implicit. Parameters like 'limit', 'schema', 'profile' are not explained. The description adds some mapping but is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'find' and resource 'visible columns' with multiple search criteria (name, comment, data type, table pattern, business term). It clearly distinguishes from sibling tools like ob_describe_table or ob_find_tables_by_business_term by focusing on columns across tables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching columns by various attributes but provides no explicit guidance on when to use this tool vs alternatives like ob_search_catalog or ob_describe_table. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explicitly states 'strictly read-only' and mentions pagination, but lacks details on permissions, rate limits, error handling, or behavior for invalid queries. The transparency is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is front-loaded with key attributes (read-only, pagination) and is concise. However, it could include brief parameter descriptions without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six parameters and no output schema or annotations, the description is incomplete. It does not explain required pagination behavior (e.g., need for orderBy), return format, or error responses. The agent lacks sufficient context for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds no parameter-specific information. It does not explain the purpose of 'sql', 'pageSize', 'orderBy', etc., beyond what the schema names imply. The agent must guess parameter roles, risking incorrect usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a read-only SELECT/WITH query with server-side pagination. It specifies the verb 'Run', the resource 'query', and key features (read-only and pagination), distinguishing it from siblings like ob_query which likely lacks pagination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like ob_query or ob_query_preview. The description does not mention prerequisites, when not to use, or alternative tools for different scenarios, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It conveys a read-only search returning mappings, and hints at permission filtering via 'allowed', but does not disclose response format, pagination, or potential side effects. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and resource, no fluff. Could benefit from structured bullet points for parameters, but the compactness is acceptable for a simple search tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters (one required), no output schema, and no annotations, the description leaves many gaps: response format, pagination, meaning of 'allowed', role of 'profile'. Not complete enough for confident usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with no descriptions in the input schema for any parameter. The description only mentions 'search' and 'mapped to schemas/tables/columns', which implies query and schema as filters but fails to explain limit, profile, or their behavior. Insufficient compensation for missing schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (search) and resource (business glossary terms), and specifies the mapping context to OceanBase schemas, tables, and columns. This distinguishes it from sibling tools like ob_search_catalog or ob_list_tables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. With 27 sibling tools, the lack of usage context or exclusions makes it hard for an agent to decide when to invoke this over others like ob_search_catalog or ob_get_table_schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It states the tool is read-only and reports on grants, but does not clarify what 'appears read-only' means or any additional side effects. It is minimally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no unnecessary words. It directly states the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and parameter details, the description is somewhat incomplete. It provides the core purpose but omits expected output format and parameter semantics, which are important for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter ('profile') with 0% description coverage, and the tool description does not mention it at all. The agent has no information on its purpose, allowed values, or whether it's optional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inspects database grants and checks if the account appears read-only. The verb 'inspect/report' and resource 'grants/permissions' are specific, and it is distinct from sibling tools like ob_query or ob_ping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 over alternatives, such as when to check permissions vs. querying data. No context is given for typical use cases or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It states read-only and no execution, which discloses the key behavioral trait (non-destructive). However, it lacks details on authentication, rate limits, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the key verb and resource, containing no fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, no output schema, and no annotations. The description is insufficient: it does not explain what a 'SQL template' is, how to use 'scenarios', or the format of the generated output. For a tool of moderate complexity, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to any of the 6 parameters. It does not explain the purpose or constraints of parameters like 'scenarios' or 'maxColumns', which are left entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (generate), resource (SQL templates), source (policy-filtered table metadata), and constraint (read-only, without execution). It distinguishes from siblings like ob_query (executes) and ob_get_table_ddl (returns DDL).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for generating templates without executing, but lacks explicit guidance on when to use this tool versus alternatives (e.g., ob_query for execution, ob_explain for plan). No exclusion or context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses boundedness (topN), masking, and sample limits (rowLimit), which are key behavioral traits. However, it does not explain what masking does, how limits are enforced, or if there are side effects like data access restrictions. Lacks depth but covers core aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence of 12 words, no fluff. Front-loaded with the key action and resource. Every part is meaningful, making it highly efficient for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six parameters, no output schema, and complex concepts like masking, the description is too brief. It does not explain the return format, interaction between topN and rowLimit, what 'allowed column' means (policy-driven?), or error scenarios. Leaves significant gaps for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 0% of schema parameters have descriptions. The tool description adds meaning by referencing 'bounded' (topN), 'sample limits' (rowLimit), and 'one allowed column' (column), but ignores parameters like schema and profile. It partially compensates for the lack of parameter descriptions but is insufficient for a full understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a bounded top-value distribution for one column, specifying the action (return) and resource (distribution for an allowed column). This distinguishes it from siblings like ob_profile_columns which profile multiple columns or ob_get_table_stats which provides statistics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies usage for value distribution queries but does not compare with siblings like ob_profile_columns or ob_describe_table, nor does it state prerequisites or constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is read-only and does not return data, and mentions optional EXPLAIN risk. However, with no annotations present, the description should provide more detail about side effects, errors, or performance implications. It gives basic behavioral intent but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
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 and key aspects. It is concise with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and a large sibling set, the description is too brief. It does not explain what the lint output looks like or how parameters affect behavior. The agent would likely need additional information to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fails to explain any of the five parameters (sql, params, maxRows, profile, runExplain). Only 'runExplain' is hinted at via 'optional EXPLAIN risk'. The add minimal value, leaving the agent to guess parameter meanings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lints read-only SQL for multiple aspects (policy, dialect, pagination, ordering, sensitive fields) and optionally checks EXPLAIN risk without returning data. This specific verb+resource combination distinguishes it from siblings like ob_explain, ob_policy_explain, and ob_convert_sql_dialect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for read-only SQL linting without data return, but does not explicitly state when to use this tool versus alternatives like ob_explain for query plans or ob_policy_explain for policy analysis. No exclusions or context are provided, leaving the agent to infer appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool clears in-memory cache entries, which is a mutating (destructive) operation. It mentions scoping by schema or table and the active profile. However, without annotations, the agent lacks information about side effects (e.g., whether clearing the cache affects other users or sessions), required permissions, or the impact on subsequent metadata queries. The transparency is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core action ('Clear in-memory metadata cache entries') and immediately adds the scoping qualifier. Every word serves a purpose; there is no redundancy or filler. It is appropriately sized for a straightforward tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters with no schema descriptions, no output schema, and no annotations, the description is far from complete. It does not explain return values (success/failure, number of entries cleared), prerequisites, or the effect on other profiles. For a mutation tool, critical context (e.g., idempotency, performance impact) is missing. The description covers only the basic purpose and scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. The description mentions 'optionally scoped by schema or table', which maps conceptually to the 'schema' and 'table' parameters. However, it does not explain how these parameters interact (e.g., whether table requires schema), the meaning of the 'profile' parameter (which overrides the 'active profile'?), or any default behavior. The compensation is partial and leaves ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('clear'), the resource ('in-memory metadata cache entries'), and the scope ('for the active profile', 'optionally scoped by schema or table'). This distinguishes it from sibling tools like `ob_get_cache_status` which retrieves cache status, or `ob_get_object_metadata` which retrieves metadata without clearing. The specificity of verb and resource makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when clearing the metadata cache is desired, but it provides no explicit guidance on when to use this tool versus alternatives (e.g., `ob_capture_metadata_snapshot` or `ob_describe_table`). There is no mention of preconditions, consequences, or situations where this tool is inappropriate. The agent is left to infer usage from the name and purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 states the snapshot is 'metadata-only' and 'bounded', hinting at non-destructive behavior, but does not explicitly confirm read-only nature, performance implications, or what happens on limit violations. It adds moderate behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with 14 words, making it very concise. However, it sacrifices parameter information, which could be justified as the schema should handle that, but with 0% coverage, it should compensate. Still, the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, no output schema, and no annotations, the description fails to explain what a snapshot is, what the tool returns, or how it integrates with siblings. It covers purpose but not the full operational context needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description provides no explanation of the 10 parameters. It does not mention schema, profile, maxTables, or any other parameter, leaving the agent without guidance on how to use them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Capture', the resource 'metadata snapshot', and specifies it is 'bounded', 'metadata-only', and for 'offline diff and impact analysis'. This distinguishes it from sibling tools like 'ob_compare_metadata_snapshots' which compare snapshots, and 'ob_analyze_metadata_impact' which is for analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its usage for offline diff and impact analysis, providing clear context. However, it does not explicitly state when not to use this tool or mention alternatives, though the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 mentions 'read-only' and 'without executing it,' which is good, but it does not disclose whether the tool modifies the session (despite an updateSession parameter), permissions required, or state changes. This leaves several behavioral aspects unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 18 words, front-loaded with the core action and constraints. No redundant or filler content; every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters and no output schema or annotations, the description lacks detail on return values (presumably the SQL string), the role of profile, and the behavior of updateSession. It covers the primary purpose but leaves gaps for a complete understanding of the tool's capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It covers columns, filters, ordering, and pagination (page, pageSize) but omits explanation of profile, addColumns, updateSession, and keepExistingColumns. Seven out of ten parameters lack any context in the description, leaving the agent to infer their purposes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool builds a refined read-only SELECT from a query session without executing it, listing structured columns, filters, ordering, and pagination. It distinguishes itself from sibling tools like ob_query (which executes) and ob_build_select (which likely executes) by emphasizing no execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used after a query session is started and for building a refined query without execution, but it does not explicitly state when to use it over alternatives like ob_build_select or ob_prepare_query. No exclusions or prerequisites beyond requiring a sessionId.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds value by disclosing policy-filtering and masking behavior. However, it does not cover other behavioral aspects like destructiveness or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the purpose. However, it could benefit from a brief mention of key parameters for better structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, four parameters, and no annotations, the description is incomplete. It does not explain terms like 'allowed table' or 'policy-filtered', leaving significant gaps for an agent to understand correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description adds no information about the four parameters (limit, table, schema, profile). The description must compensate for this gap but fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a policy-filtered sample from a table and mentions masking of sensitive fields. It distinguishes itself from sibling tools like ob_query and ob_describe_table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for quick sampling but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It mentions 'read-only' and 'without executing', indicating safety, but does not disclose what happens on validation failure or whether it checks existence of table/columns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It efficiently communicates the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations or output schema and 8 parameters, the description is too sparse. It does not explain what the tool returns (e.g., a SQL string) or how to use the result, and it lacks details on validation semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description only enumerates parameter categories (table, columns, filters, ordering, pagination) without adding semantic details for the 8 parameters. Parameter names are self-explanatory, but no extra value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool builds a parameterized read-only SELECT query from validated components without executing it. It specifies the verb 'Build' and the resource 'SELECT', and distinguishes from execution tools like ob_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for constructing a query for review or further processing by noting 'without executing it', but lacks explicit guidance on when to choose this over siblings like ob_generate_query or ob_prepare_query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that no SQL execution occurs, which is a key safety trait. However, with no annotations, the description fails to mention whether the tool has side effects, requires specific permissions, or has limitations. It provides some transparency but not enough for an agent to fully understand behavioral boundaries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single effective sentence that immediately conveys the core action and key differentiator (no SQL execution). No unnecessary words, and the structure is front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 optional parameters, no output schema, and no annotations, the description is too sparse. It does not explain what 'candidates' means, how results are structured, or the role of parameters like 'schema' and 'profile'. The agent lacks sufficient context to use the tool effectively without additional clarification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 6 parameters and 0% schema coverage, the description adds little meaning beyond parameter names. It explains 'sql' is the input SQL but does not clarify 'line', 'schema', 'profile', 'filePath', or 'maxCandidates'. An agent would have to guess the semantics, which is insufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds unknown tables or columns in SQL and returns metadata-based candidates without executing the SQL. This specific verb+resource combination distinguishes it from siblings like ob_explain or ob_find_columns that have overlapping but distinct purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when SQL contains unknown references, but it does not explicitly state when to use or not use this tool versus alternatives. No mention of prerequisites or exclusions, leaving the agent without clear guidance on when to choose this over similar tools like ob_explain_error or ob_find_columns.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 tool is read-only and does not execute the query. However, it does not mention required permissions, potential side effects on policy evaluation, or the nature of the preview output. Still, the core behavioral trait is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately conveys the tool's purpose and key constraint. Every word earns its place; no redundancy or filler. It is well front-loaded with the action 'Preview'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, no output schema, no annotations, and 29 siblings, the description is too brief. It does not explain return values, parameter details, or comparison to siblings like ob_explain. An agent would lack sufficient context to use the tool correctly, especially for parameters like 'profile' and 'maxRows'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no information about the 4 parameters (sql, params, maxRows, profile). The agent receives no guidance on how to use these parameters, e.g., that 'sql' must be a SELECT statement, or the purpose of 'profile'. The description fails to compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool previews policy, sensitive-column, and EXPLAIN risk for a read-only SQL statement, specifying it does not execute the query, which distinguishes it from execution siblings like ob_query. The verb 'preview' and resource 'read-only SQL statement' are specific and unique among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for assessing risks before executing a query by stating 'without executing the target query', but it does not explicitly state when to use this tool vs alternatives like ob_explain or ob_analyze_query_plan. No exclusionary guidance or alternative names are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description accurately notes it returns information, implying no side effects. It adds context about the content but could explicitly state it is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that efficiently conveys the tool's purpose without extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the lack of explanation for the 'profile' parameter limits completeness, leaving the agent unsure how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The optional 'profile' parameter is not explained in the description, and schema coverage is 0%. The description fails to add meaning to the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a usage guide with specific content (workflow, safety rules, notes), and this distinguishes it from sibling tools that perform analysis or queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for reference but does not explicitly state when to use it or contrast with alternatives. Given many siblings, clear guidance would help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses read-only nature and states that row, timeout, output, and policy limits are not bypassed. However, it doesn't describe error handling or session state requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, straightforward sentence that efficiently conveys the core action and constraint, though it could be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, and the description omits return value documentation. It also fails to explain how sessionId is used or what happens on invalid session.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no details about parameters, despite 0% schema coverage. Parameters like orderBy, profile, pageSize, and sessionId are not explained, requiring the agent to infer from context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs the previous page for a read-only query session, using a specific verb and resource. It implies a distinct pagination direction from siblings like ob_query_next_page and ob_query_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the name and title for paginating backward, but no explicit when-to-use or when-not-to-use guidance is provided, nor any mention of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It communicates that the tool is non-destructive ('without writing files') and output is bounded. However, it omits details like whether the tool is idempotent, success/error states, or any authentication requirements. The provided traits are useful but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys all essential information without waste. Every word is purposeful and contributes to understanding the tool's core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (including complex ones like columns and profile) and no output schema or annotations, the description is too sparse. It fails to clarify input requirements (e.g., row structure, column definitions) or output format expectations, leaving the agent under-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate by explaining parameter purposes. It only mentions 'Markdown or CSV preview string' and 'bounded', leaving parameters like columns, maxRows, and profile unexplained. The agent cannot infer how to correctly set these parameters without additional knowledge.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Generate', the resource 'Markdown or CSV preview string', and the context 'from already returned rows without writing files'. It effectively distinguishes this tool from siblings like ob_query (which fetches rows) and ob_summarize_result (which summarizes rows).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when rows are already available and a lightweight text preview is needed without writing files. It does not explicitly exclude specific alternatives, but the context of siblings like ob_query_preview or ob_compare_query_results is sufficiently differentiated by the 'without writing files' clause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. Only hints at 'redacted settings' but doesn't elaborate on behavior, side effects, or what 'redacted' means.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, extremely concise, front-loaded. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimal but adequate for a simple parameterless list tool. However, 'redacted settings' is vague; more detail on return structure would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so baseline 4. Description adds no parameter info, but none is needed. Schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists OceanBase MCP profiles, using a specific verb and resource. Differentiates from siblings like ob_query or ob_list_tables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. Usage is implied because it's a simple list tool, but no alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![oceanbase-mcp MCP server](https://glama.ai/mcp/servers/sevoniva-labs/oceanbase-mcp/badges/card.svg)](https://glama.ai/mcp/servers/sevoniva-labs/oceanbase-mcp)

Score Badge

Copy to your README.md:

[![oceanbase-mcp MCP server](https://glama.ai/mcp/servers/sevoniva-labs/oceanbase-mcp/badges/score.svg)](https://glama.ai/mcp/servers/sevoniva-labs/oceanbase-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sevoniva-labs/oceanbase-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server