Skip to main content
Glama

Describe the workspace database

describe_database
Read-only

Check whether a workspace includes an SQL database, how much allowance is used, and whether data exists before building database-backed features; if not included, use the key-value store instead.

Instructions

Whether this workspace has its own SQL database, and how much of its allowance is used. Ask before building anything that needs one. included:false means the owner's plan has no database — that is an answer, not an error and not something to retry: say so and use the key-value store (get/set_workspace_data) instead. exists:false with included:true just means nothing has been written yet.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "workspaceId": "<workspaceId>"
    },
    "name": "describe_database"
  }
}

Input Schema

NameRequiredDescriptionDefault
workspaceIdYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.53.0

TDQS

A4.5/5.0
Behavior4/5

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

The annotations already declare readOnlyHint=true, and the description adds genuinely useful semantics beyond that: included:false is a definitive answer rather than an error, and exists:false with included:true simply means no data has been written. It does not describe return shape exhaustively or mention rate limits, but for a read-only status probe the behavioral disclosure is strong and never contradicts the annotation.

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?

Three sentences, front-loaded with the answer the tool provides, then the routing guidance, then the field-level interpretation. No sentence is filler; each carries a distinct instruction or interpretation rule.

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?

With no output schema, the description carries the burden of explaining return values, and it does so by interpreting the included and exists fields. Combined with the read-only annotation and a single obvious parameter, nothing an agent needs to call this correctly is missing.

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

Parameters3/5

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

There is one parameter (workspaceId) with 0% schema description coverage, and the description says nothing about it. The parameter is self-evident from the name and the tool's workspace scope, so this is a minor gap, but the description adds no meaning beyond the schema here.

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 states a specific resource and result: whether the workspace has its own SQL database and how much of its allowance is used. It also implicitly separates this capability check from the sibling query_database/execute_sql operations by framing it as a precondition check ('Ask before building anything that needs one').

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?

It gives explicit timing guidance ('Ask before building anything that needs one') and an explicit alternative when the database is unavailable (get/set_workspace_data). It even warns against a specific wrong behavior — retrying on included:false — which is guidance most definitions omit.

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