surreal-mcp

by lfnovo

Overview Schema Related Servers Score Discussions

Python

Remote

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation4/5
Most tools have distinct purposes, but there is some overlap between 'merge', 'patch', and 'update' that could cause confusion. 'merge' and 'patch' both handle partial updates with different syntaxes, and 'update' is for full replacements, which might be misselected by an agent. However, descriptions clarify these differences, and other tools like 'create', 'delete', and 'select' are clearly distinct.
Naming Consistency5/5
All tool names follow a consistent verb-only pattern (e.g., create, delete, insert, merge, patch, query, relate, select, update, upsert). There are no deviations in style or convention, making the naming highly predictable and readable across the set.
Tool Count5/5
With 10 tools, the server is well-scoped for a SurrealDB MCP server, covering essential CRUD operations, bulk inserts, queries, and graph relations. Each tool serves a clear purpose, and the count is neither too sparse nor overwhelming for database interaction tasks.
Completeness5/5
The tool set provides comprehensive coverage for SurrealDB operations, including create, read (select, query), update (update, merge, patch, upsert), delete, bulk operations (insert), and graph relations (relate). There are no obvious gaps; agents can perform full lifecycle management and complex queries without dead ends.
Average 4.7/5 across 10 of 10 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under MIT License.
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

Behavior4/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 effectively discloses behavioral traits: it's a mutation tool (implied by 'modify'), explains the internal conversion to merge, lists supported operations, and notes limitations. However, it lacks details on permissions, rate limits, or error handling beyond the return structure.
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 well-structured with sections for purpose, usage, args, returns, examples, and notes. It is appropriately sized but could be more front-loaded; the detailed parameter explanations are valuable but make it slightly verbose. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (mutation tool with 4 parameters, 0% schema coverage, no annotations) and the presence of an output schema, the description is complete. It covers purpose, usage, parameters with examples, return values, and limitations, providing all necessary context for effective tool use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/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 fully. It adds significant meaning beyond the schema: explains 'thing' format, details 'patches' structure with examples, and clarifies 'namespace' and 'database' defaults. This provides comprehensive parameter semantics not 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 tool's purpose: 'Apply JSON Patch operations to a specific record (RFC 6902).' It specifies the exact action ('apply'), resource ('record'), and standard ('RFC 6902'), distinguishing it from siblings like 'update' or 'merge' by focusing on patch operations.
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 provides clear context for when to use this tool: for applying JSON Patch operations to modify records. It mentions an alternative ('merge') and notes limitations ('Complex operations like "move" or "test" are not fully supported'), but does not explicitly state when to choose this over siblings like 'update' or 'merge'.
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 provided, the description carries the full burden of behavioral disclosure. It effectively describes that this creates relationships, stores data on relationships, enables future graph queries, and models many-to-many relationships. It also explains the return structure and includes error handling information. The main gap is lack of information about permissions, rate limits, or idempotency.
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 well-structured with clear sections (purpose, bullet points, args, returns, examples, note). While comprehensive, it's appropriately sized for a complex tool with 6 parameters. The front-loaded purpose statement is excellent, though some redundancy exists between the bullet points and later content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, graph operations), no annotations, and an output schema that only defines structure without semantics, the description provides excellent completeness. It covers purpose, parameters with examples, return values with examples, and even includes query syntax for future use. The combination of structured sections and practical examples makes it highly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by providing detailed parameter explanations. Each parameter is clearly defined with format examples (e.g., 'table:id'), the optional nature of 'data', 'namespace', and 'database' is explained, and concrete examples show how parameters work together. This adds significant value 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 specific action ('Create a graph relation'), identifies the resource ('between two records in SurrealDB'), and distinguishes from siblings like create/insert/update by focusing on graph relationships rather than general record operations. The bullet points further clarify the purpose and benefits.
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 provides clear context for when to use this tool ('Create a graph relation between two records'), and the examples demonstrate typical use cases. However, it doesn't explicitly state when NOT to use it or mention alternatives among the sibling tools for similar operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/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 thoroughly explains the irreversible nature, cascading effects (removing graph edges, triggering hooks), failure conditions (FOREIGN KEY constraints), and even includes edge-case behavior (no error if record doesn't exist). This provides comprehensive behavioral context beyond basic parameter documentation.
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 well-structured with clear sections (purpose, warnings, args, returns, examples, notes) and every sentence adds value. While comprehensive, it could be slightly more concise by integrating some details more tightly, but the information density is high and organization supports quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with no annotations, 3 parameters, and 0% schema coverage, this description is exceptionally complete. It covers purpose, behavioral consequences, all parameters, return values (though output schema exists), examples, warnings, and even suggests alternatives. Nothing essential is missing given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description fully compensates by explaining all three parameters. It clarifies 'thing' as 'the full record ID in format "table:id"' with examples, and explains the optional 'namespace' and 'database' parameters with their default behaviors from environment variables. This adds substantial meaning 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 tool's purpose with specific verb ('Delete') and resource ('a specific record from the database by its ID'). It distinguishes itself from sibling tools like 'create', 'update', and 'patch' by focusing on permanent removal rather than creation or modification.
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 provides clear context about when to use this tool ('permanently removes a record') and includes a cautionary note about irreversibility. It suggests an alternative ('Consider using soft deletes') but doesn't explicitly contrast with specific sibling tools like 'patch' or 'update' for partial modifications.
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 provided, the description carries the full burden of behavioral disclosure. It clearly explains this is a partial update operation that only modifies specified fields while leaving others unchanged. It describes the return structure in detail and mentions the tool's equivalence to 'patch' but with different syntax. However, it doesn't mention authentication requirements, rate limits, or error handling beyond the error field in returns.
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 well-structured with clear sections (purpose, usage scenarios, Args, Returns, Examples, Note) and front-loads the core functionality. While comprehensive, some sections like the detailed examples and note could be slightly condensed. Every sentence adds value, but the overall length is substantial for a tool description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutation operation with 4 parameters, 0% schema coverage, and sibling tools), the description provides complete context. It explains the partial update behavior, provides detailed parameter semantics, includes a comprehensive return structure, offers practical examples, and positions the tool relative to siblings. The presence of an output schema reduces the need to explain return values, which the description acknowledges by documenting the return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by providing detailed parameter explanations. Each parameter (thing, data, namespace, database) is clearly explained with examples, format requirements, and default behavior. The data parameter receives particularly thorough treatment with multiple examples showing different update scenarios.
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 as 'Merge data into a specific record, updating only the specified fields' with the specific verb 'merge' and resource 'record'. It explicitly distinguishes from the sibling 'patch' tool in the note section, stating this uses object merging syntax instead of JSON Patch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'This is useful when you want to:' followed by three specific scenarios. It also explicitly compares to the 'patch' sibling tool, indicating this is an alternative with different syntax. The examples further illustrate appropriate usage contexts.
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 provided, the description carries the full burden. It effectively communicates this is a read-only operation (implied by 'select', 'retrieve', 'get data'), describes the return format in detail, and provides examples of successful outcomes. It doesn't mention error handling beyond the return structure or rate limits, but covers core behavioral aspects well.
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 well-structured with clear sections (purpose, usage guidelines, args, returns, examples). While somewhat lengthy, every section adds value. The front-loaded purpose and usage guidelines are efficient, though the detailed parameter explanations and examples make it comprehensive rather than minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read operation tool with 4 parameters, 0% schema coverage, no annotations, but with an output schema, this description is exceptionally complete. It covers purpose, usage, all parameters, return format, and provides multiple examples. The output schema means the description doesn't need to explain return values, which it does anyway, adding extra clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by providing comprehensive parameter documentation. It explains all 4 parameters (table, id, namespace, database), their purposes, formats, optionality, and default behaviors. The id parameter gets particularly detailed treatment with multiple format examples and the None case explanation.
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 with specific verbs ('select all records', 'retrieve a specific record') and resources ('from a table', 'by its ID'). It distinguishes this read operation from sibling tools like create, delete, update, etc. which are write operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides when-to-use guidance with bullet points ('Fetch all records', 'Retrieve a specific record', 'Get data for display or further processing'). It distinguishes this from other tools by being the primary read operation tool in a set that includes many write operations.
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 provided, the description carries the full burden and does an excellent job disclosing behavioral traits. It explains the destructive nature ('completely replacing its content'), specifies what fields are preserved/excluded (ID, timestamps), describes the automatic timestamp update, mentions environment variable fallbacks, and documents the return structure. It doesn't mention authentication or rate limits, but covers most critical behavioral aspects.
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 well-structured with clear sections (purpose, args, returns, examples, warning) and front-loads the most important information. While comprehensive, it could be slightly more concise as some information is repeated (e.g., the warning about using 'merge' for partial updates appears twice).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with no annotations, 4 parameters, 0% schema coverage, but with an output schema, the description provides complete context. It covers purpose, usage guidelines, parameter semantics, behavioral details, return values, and includes examples. The output schema existence means the description doesn't need to explain return structure in detail, which it acknowledges by summarizing rather than fully specifying.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by providing detailed semantic explanations for all parameters. It explains the 'thing' parameter format with examples, clarifies that 'data' must contain 'complete new data', and describes the optional 'namespace' and 'database' parameters with their environment variable fallback behavior.
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 with specific verbs ('update a specific record', 'completely replacing its content') and distinguishes it from siblings like 'merge' and 'patch'. It explicitly identifies the resource as a 'record' and specifies it's a full replacement operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives: 'For partial updates that only modify specific fields, use 'merge' or 'patch' instead.' It also includes a warning section reinforcing this distinction and names specific sibling tools.
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 provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: the conditional create/merge logic, success conditions ('always succeed unless there's a database error'), and return structure. It could improve by mentioning potential side effects or performance implications, but covers core behavior well.
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 well-structured with clear sections (purpose, behavior, args, returns, examples) and uses bullet points effectively. It's appropriately detailed for a complex tool but could be slightly more concise in the examples section, which includes three detailed examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (conditional create/update logic), 4 parameters with 0% schema coverage, and no annotations, the description provides comprehensive coverage. It explains purpose, usage, behavior, parameters, and return values in detail. The presence of an output schema reduces the need to fully document returns, but the description still provides helpful context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by providing detailed semantic information for all parameters. It explains the format and purpose of 'thing' (record ID format), the behavior of 'data' (merged if record exists), and the optional nature and defaults for 'namespace' and 'database' parameters.
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 with specific verbs ('create if it doesn't exist, merge/update if it does') and identifies the resource ('record'). It distinguishes this from siblings like 'create', 'update', 'merge', and 'patch' by explaining the conditional logic that combines their functionalities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('perfect when you want to ensure a record exists with specific data, regardless of whether it already exists'). It distinguishes it from alternatives by explaining its unique upsert behavior, which differs from separate create or update operations available among siblings.
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 provided, the description carries full burden and does well by disclosing key behaviors: auto-generated ID, automatic timestamp addition, schema validation, and fallback to environment variables for namespace/database. It doesn't mention error handling specifics or rate limits, but covers most critical 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?
The description is well-structured with clear sections (purpose, system behavior, args, returns, examples, note). Every sentence adds value - no redundancy. The information is front-loaded with the core purpose first, followed by supporting details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters with 0% schema coverage and no annotations, the description provides comprehensive coverage: purpose, usage guidelines, parameter details with examples, return format, and sibling differentiation. The output schema exists, so return values don't need explanation in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/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 fully compensate. It provides detailed parameter explanations with examples for 'data', clarifies optional vs. required parameters, explains default behaviors for namespace/database, and gives concrete examples of valid inputs.
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: 'Create a new record in a SurrealDB table with the specified data.' It specifies the verb ('create'), resource ('record in a SurrealDB table'), and distinguishes from siblings by mentioning auto-generated ID and pointing to 'upsert' for custom IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use alternatives: 'If you need to specify a custom ID, use the 'upsert' tool instead.' It also clarifies the default behavior (auto-generated ID) and when to use optional parameters (namespace/database overrides).
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 provided, the description carries full burden and does well. It discloses behavioral traits: bulk operation optimization, automatic ID generation, timestamp handling, schema validation, and fallback behavior for namespace/database parameters. It doesn't mention error handling specifics beyond the return structure, but covers most key behaviors for a write operation.
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 well-structured and appropriately sized. It starts with the core purpose, then provides optimization context, behavioral details, parameter explanations with examples, return format, usage example, and finally sibling tool guidance. Every section adds value with no wasted sentences, and information is front-loaded effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a bulk insert operation with 4 parameters, no annotations, but with an output schema, the description is complete. It covers purpose, usage guidelines, behavioral traits, parameter semantics with examples, return format explanation, and sibling tool differentiation. The output schema existence means the description doesn't need to detail return structure, which it acknowledges while still explaining key aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by providing detailed parameter semantics. It explains each parameter's purpose, provides examples for the 'data' array, and clarifies default behavior for optional parameters. The description adds substantial meaning beyond what the bare schema provides, making parameter usage clear.
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: 'Insert multiple records into a table in a single operation.' It specifies the verb ('insert'), resource ('records into a table'), and scope ('multiple records in a single operation'). It also distinguishes from sibling 'create' tool in the Note section, making it specific and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'optimized for bulk inserts when you need to create many records at once' and 'more efficient than calling 'create' multiple times.' It also explicitly states when not to use it: 'For single record creation, use the 'create' tool instead.' This gives clear alternatives and context for tool selection.
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 provided, the description carries full burden and delivers well. It discloses key behavioral traits: queries execute sequentially, failure doesn't stop execution (error captured per query), and namespace/database fallback to environment variables. It doesn't mention authentication needs, rate limits, or side effects, but covers execution flow thoroughly.
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?
Well-structured and appropriately sized. Front-loaded with purpose and usage guidelines, followed by parameter details, return format, and example. Every sentence earns its place: no fluff, clear sections with headings (Args, Returns, Example). Efficient communication of complex functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters with 0% schema coverage, no annotations, but with output schema (Returns section), the description is complete. It explains all parameters thoroughly, describes execution behavior, provides usage guidance versus siblings, and documents the return structure. The example solidifies understanding. No gaps for a general-purpose query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/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 fully. It does: each parameter (queries, namespace, database) is explained with meaning, optionality, defaults, and examples. The 'queries' parameter gets extensive examples showing array usage and query types. This adds significant value 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 tool 'Execute one or more SurrealQL queries against the connected SurrealDB database' with specific verb ('Execute') and resource ('SurrealQL queries'). It distinguishes from siblings by mentioning 'complex queries that don't fit the other tool patterns' and listing specific sibling-incompatible use cases like JOINs, DEFINE statements, and transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use this for complex queries that don't fit the other tool patterns' with concrete examples (SELECT with JOINs, DEFINE, transactions, graph traversal). This clearly indicates when to use this tool versus the simpler sibling tools like select, create, update, etc.
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:

[![surreal-mcp MCP server](https://glama.ai/mcp/servers/lfnovo/surreal-mcp/badges/card.svg)](https://glama.ai/mcp/servers/lfnovo/surreal-mcp)

Score Badge

Copy to your README.md:

[![surreal-mcp MCP server](https://glama.ai/mcp/servers/lfnovo/surreal-mcp/badges/score.svg)](https://glama.ai/mcp/servers/lfnovo/surreal-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/lfnovo/surreal-mcp'

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