Skip to main content
Glama
enesjakozh
truaxki

MCP Variance Log

by truaxki
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

MCP Variance Log

Agentic tool that looks for statistical variations in conversation structure and logs unusual events to a SQLite database. Built using the Model Context Protocol (MCP), this system is designed to be used with Claude Desktop or other MCP-compatible clients.

Requirements

  • Python ≥3.10

  • MCP ≥1.2.0

  • SQLite3

  • UV (Python package installer and environment manager)

Related MCP server: ClaudeX

Quick Start

# Clone and install
git clone https://github.com/truaxki/mcp-variance-log.git
cd mcp-variance-log
uv pip install -e .

Add to Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "mcp-variance-log": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\username\\source\\repos\\mcp-variance-log",  # Update this path
        "run",
        "mcp-variance-log"
      ]
    }
  }
}

Add to Claude Desktop preferences:

Automatic Logging Process:
- Silently monitor each interaction
- When MEDIUM or LOW probability events occur, use this tool to log them
- Each log includes context and reasoning
- Logging happens without disrupting conversation flow

Usage

Automatic Logging Examples

prompt: "What if I told you I could lift 1000 lbs?"

{
  `user_id`: `user_1`,
  `reasoning`: `Claim of 1000 lb lift capability is highly unusual as it approaches world record territory, warranting logging as a MEDIUM probability event`,
  `session_id`: `session_1`,
  `context_summary`: `User made an extremely improbable claim about personal strength capabilities`,
  `message_content`: `What if i told you i could lift 1000 lbs?`,
  `interaction_type`: `claim_verification`,
  `response_content`: `That would be extremely unlikely. The current world record for weight lifted by a human (deadlift) is 1,104.5 lbs, set by Hafthor Björnsson in 2020 under very specific conditions. Only a handful of people in history have lifted close to 1,000 lbs.`,
  `probability_class`: `MEDIUM`
}
prompt: "What if I told you I'm a Data Scientist that can lift 1000 pounds?"

{
  `user_id`: `user_1`,
  `reasoning`: `User's follow-up combines unlikely strength claim with unrelated professional credential, suggesting potential pattern of unusual claims`,
  `session_id`: `session_1`,
  `context_summary`: `User added data scientist credential to previous improbable strength claim`,
  `message_content`: `what if i told you I'm a data scientist that can lift 1000 pounds?`,
  `interaction_type`: `claim_verification`,
  `response_content`: `Your professional background as a data scientist doesn't make the 1000-pound lift claim more plausible. Such a lift would still be near the all-time world record of 1,104.5 lbs.`,
  `probability_class`: `LOW`
}

Dataframe view

prompt: "Read-logs from this morning"

ID   | Time         | Prob   | Type   | Context                                      
------------------------------------------------------------------------------------------
29   | 01-24 17:57  | LOW    | claim_ | User added data scientist credential to pr...
28   | 01-24 17:56  | MEDIUM | claim_ | User made an extremely improbable claim ab...

Text 2 SQL

prompt: "Can you search the logs for entry 29?"

[{'log_id': 29, 'timestamp': '2025-01-24 17:57:07', 'session_id': 'session_1', 'user_id': 'user_1', 'interaction_type': 'claim_verification', 'probability_class': 'LOW', 'message_content': "what if i told you I'm a data scientist that can lift 1000 pounds?", 'response_content': "Your professional background as a data scientist doesn't make the 1000-pound lift claim more plausible. Such a lift would still be near the all-time world record of 1,104.5 lbs.", 'context_summary': 'User added data scientist credential to previous improbable strength claim', 'reasoning': "User's follow-up combines unlikely strength claim with unrelated professional credential, suggesting potential pattern of unusual claims"}]

Detailed Installation

  1. Ensure Python 3.10+ and UV are installed.

Install UV using one of these methods:

# Using pip (recommended for Windows)
pip install uv

# Using installation script (Linux/MacOS)
curl -LsSf https://astral.sh/uv/install.sh | sh

  1. Clone and install:

git clone https://github.com/truaxki/mcp-variance-log.git
cd mcp-variance-log
uv pip install -e .

  1. Configure Claude Desktop:

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-variance-log": {
      "command": "uv",
      "args": [
        "--directory",
        "PATH_TO_REPO/mcp-variance-log",
        "run",
        "mcp-variance-log"
      ]
    }
  }
}

Config locations:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

Tools

Monitoring

  • log-query: Tracks conversation patterns

    • HIGH: Common interactions (not logged)

    • MEDIUM: Unusual patterns (logged)

    • LOW: Critical events (priority logged)

Query

  • read-logs: View logs with filtering

  • read_query: Execute SELECT queries

  • write_query: Execute INSERT/UPDATE/DELETE

  • create_table: Create tables

  • list_tables: Show all tables

  • describe_table: Show table structure

Located at data/varlog.db relative to installation.

Schema

CREATE TABLE chat_monitoring (
    log_id INTEGER PRIMARY KEY AUTOINCREMENT,
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
    session_id TEXT NOT NULL,
    user_id TEXT NOT NULL,
    interaction_type TEXT NOT NULL,
    probability_class TEXT CHECK(probability_class IN ('HIGH', 'MEDIUM', 'LOW')),
    message_content TEXT NOT NULL,
    response_content TEXT NOT NULL,
    context_summary TEXT,
    reasoning TEXT
);

Troubleshooting

  1. Database Access

  • Error: "Failed to connect to database"

    • Check file permissions

    • Verify path in config

    • Ensure /data directory exists

  1. Installation Issues

  • Error: "No module named 'mcp'"

    • Run: uv pip install mcp>=1.2.0

  • Error: "UV command not found"

    • Install UV: curl -LsSf https://astral.sh/uv/install.sh | sh

  1. Configuration

  • Error: "Failed to start MCP server"

    • Verify config.json syntax

    • Check path separators (use \ on Windows)

    • Ensure UV is in your system PATH

Contributing

  1. Fork the repository

  2. Create feature branch

  3. Submit pull request

License

MIT

Support

Issues: GitHub Issues

Available Tools

8 tools
append_insightB

Add a business insight to the memo

ParametersJSON Schema
NameRequiredDescriptionDefault
insightYesBusiness insight discovered from data analysis

TDQS

B3.3/5.0
Behavior2/5

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

With no annotations provided, the description bears full disclosure burden. It only says 'Add', implying mutation, but does not explain side effects, whether the insight is appended or replaced, constraints like max length, or whether changes are reversible.

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, front-loaded sentence with no unnecessary words. Every element (verb, object, target) earns its place.

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 simple schema (one string) and no output schema, the description suffices minimally. However, it lacks context about what 'the memo' is, how to access or verify appended insights, and how this tool relates to the sibling database tools.

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?

Schema description coverage is 100%, so baseline is 3. The tool description repeats 'business insight' from the schema's property description without adding extra semantic meaning or usage context beyond what the schema already provides.

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 'Add' and resource 'business insight' targeting 'the memo', clearly indicating the action. Among sibling tools (read_query, write_query, etc.), none relate to adding insights, so it stands out distinctly.

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. While siblings are database-oriented, the description does not explicitly state scenarios, prerequisites, or exclusions.

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

create_tableC

Create a new table in the SQLite database

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesCREATE TABLE SQL statement

TDQS

C2.6/5.0
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 only says 'Create a new table' without disclosing behavioral traits: whether it fully executes the query, whether confirmation is shown, effects on existing data, or error handling. The word 'Create' implies mutation but no safety details are given.

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 short sentence, concise and to the point. However, it could add more value in a sentence or two 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?

Given one parameter and no annotations or output schema, the description is insufficient. It doesn't address return value, error conditions, or how it differs from similar sibling tools. The agent lacks context to decide when to call this tool safely.

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?

Schema coverage is 100%, so the parameter 'query' is already documented with description 'CREATE TABLE SQL statement'. The description adds no additional meaning beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Create a new table in the SQLite database', which is clear but generic. It does not distinguish this tool from siblings like 'write_query' that could also create tables, especially since SQLite allows table creation via arbitrary 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?

The description gives no guidance on when to use this tool versus alternatives such as 'write_query' or 'read_query'. It does not mention prerequisites (e.g., database must already exist) or limitations (e.g., no support for temporary tables).

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

describe_tableC

Show structure of a specific table

ParametersJSON Schema
NameRequiredDescriptionDefault
table_nameYesName of the table to describe

TDQS

C2.9/5.0
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 states 'show structure' but does not specify what 'structure' entails (e.g., column names, types, constraints), whether it requires permissions, or if it's read-only (implied but not explicit). This leaves gaps in understanding the tool's behavior and limitations.

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, clear sentence: 'Show structure of a specific table'. It is front-loaded with the core purpose, has no redundant words, and efficiently communicates the essential action without unnecessary elaboration, making it highly concise and well-structured.

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 (a read operation with one parameter) and lack of annotations or output schema, the description is incomplete. It does not explain what 'structure' includes (e.g., schema details), potential errors (e.g., if table doesn't exist), or return format, leaving the agent with insufficient context for reliable use.

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?

The input schema has 100% coverage, with 'table_name' fully described as 'Name of the table to describe'. The description adds no additional parameter semantics beyond this, such as format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate, as the schema handles the parameter documentation adequately.

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 'Show structure of a specific table' clearly states the verb 'show' and resource 'structure of a specific table', making the purpose evident. However, it does not explicitly differentiate from siblings like 'list_tables' (which likely lists table names) or 'read_query' (which might query table data), leaving room for ambiguity in sibling context.

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 (e.g., table must exist), exclusions (e.g., not for querying data), or refer to sibling tools like 'list_tables' for discovery or 'read_query' for data retrieval, offering minimal usage context.

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

list_tablesA

List all tables in the database

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
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. 'List all tables' clearly indicates a read-only enumeration, but it does not disclose potential performance implications, whether system tables are included, or any other behavioral nuances. This is 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, simple sentence of six words that precisely states the tool's function. It is front-loaded and contains no filler, earning a perfect score for conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter list operation with no output schema and no annotations, the description gives the essential purpose. However, it does not specify the return format (e.g., an array of table names) or whether the list is ordered or filtered. A brief note about the output 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?

The tool has zero parameters, so there is no parameter information to convey. The baseline of 4 applies because the description needs to add nothing beyond the schema, which is empty.

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 'List' and clearly identifies the resource as 'tables in the database'. This distinguishes it from siblings like execute_query and get_table_schema, which operate on query results or individual table schemas.

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 the tool is for enumerating database tables, which provides clear context for when to use it. It does not explicitly exclude alternatives or mention siblings, but the purpose is self-evident in a database toolset.

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

log-queryC
            Conversation Variation analysis
            Continuously monitor our conversation and automatically log unusual or noteworthy interactions based on the following criteria:

            1. Probability Classifications:
            HIGH (Not Logged):
            - Common questions and responses
            - Standard technical inquiries
            - Regular clarifications
            - Normal conversation flow

            MEDIUM (Logged):
            - Unexpected but plausible technical issues
            - Unusual patterns in user behavior
            - Noteworthy insights or connections
            - Edge cases in normal usage
            - Uncommon but valid use cases

            LOW (Logged with Priority):
            - Highly unusual technical phenomena
            - Potentially problematic patterns
            - Critical edge cases
            - Unexpected system behaviors
            - Novel or unique use cases
ParametersJSON Schema
NameRequiredDescriptionDefault
session_idYesUnique identifier for the chat session. Format: <date>_<user>_<sequence> Example: 20240124_u1_001 Components: - date: YYYYMMDD - user: 'u' + user number - sequence: 3-digit sequential number Valid examples: - 20240124_u1_001 - 20240124_u1_002 - 20240125_u2_001
user_idYesIdentifier for the user
interaction_typeYesType of interaction being monitored
probability_classYesClassification of interaction probability
message_contentYesThe user's message content
response_contentYesThe system's response content
context_summaryYesSummary of interaction context
reasoningYesExplanation for the probability classification

TDQS

C2.3/5.0
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 describes what gets logged (unusual interactions based on probability classes) but doesn't disclose behavioral traits such as whether this is a read or write operation, permission requirements, rate limits, or what happens after logging (e.g., stores data, triggers alerts). The focus is on criteria rather than tool behavior, leaving gaps in 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?

The description is structured with bullet points for probability classifications, which is clear but verbose. It's front-loaded with 'Conversation Variation analysis', but the content is overly detailed for criteria rather than the tool's purpose. Some sentences could be condensed, and it includes unnecessary repetition (e.g., listing examples for each class). It's not optimally concise for a tool description.

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 complexity (8 required parameters, no annotations, no output schema), the description is incomplete. It focuses on logging criteria but doesn't explain what the tool does with the input (e.g., queries logs, analyzes data, stores entries). Without annotations or output schema, it should provide more context on behavior and results, but it falls short, leaving the agent unclear on the tool's function.

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?

Schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly. The description doesn't add meaning beyond the schema; it mentions probability classifications (HIGH, MEDIUM, LOW) which align with the 'probability_class' parameter's enum, but this is redundant. With high schema coverage, the baseline is 3, as the description doesn't compensate with additional param insights.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Conversation Variation analysis' and 'automatically log unusual or noteworthy interactions', which gives a vague purpose but doesn't specify what the tool actually does (e.g., query logs, analyze conversations, or create logs). It's more about criteria for logging than the tool's function. The title is null, and the name 'log-query' suggests querying logs, but the description focuses on monitoring criteria without clearly stating the tool's action.

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 criteria for when interactions are logged (MEDIUM and LOW probability classes), but it doesn't explicitly state when to use this tool versus alternatives like 'read-logs' or 'write_query'. It implies usage for logging based on probability, but lacks clear guidance on tool selection, prerequisites, or exclusions compared to sibling tools.

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

read-logsB

Retrieve logged conversation variations from the database.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitYesMaximum number of logs to retrieve
start_dateNoFilter logs after this date (ISO format YYYY-MM-DDTHH:MM:SS)
end_dateNoFilter logs before this date (ISO format YYYY-MM-DDTHH:MM:SS)
full_detailsNoIf true, show all fields; if false, show only context summaries

TDQS

B3.1/5.0
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 mentions retrieval but fails to specify if this is a read-only operation, what permissions are needed, or details about rate limits or pagination. This leaves significant gaps in understanding the tool's 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?

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and wastes no space, making it highly concise and well-structured.

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 tool's moderate complexity (4 parameters, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks details on behavioral traits, usage context, and output format, leaving room for improvement in completeness.

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?

The input schema has 100% description coverage, clearly documenting all four parameters with details like defaults and formats. The description adds no additional meaning beyond the schema, so it meets the baseline score of 3 without compensating for any gaps.

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 ('retrieve') and resource ('logged conversation variations from the database'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'log-query' or 'read_query', which might have overlapping functionality, so it misses the highest score.

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 'log-query' or 'read_query', nor does it mention any prerequisites or exclusions. This lack of context leaves the agent without clear usage instructions.

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

read_queryA

Execute a SELECT query on the SQLite database

            Schema Reference:
            Table: chat_monitoring
            Fields:
            - log_id (INTEGER PRIMARY KEY)
            - timestamp (DATETIME)
            - session_id (TEXT)
            - user_id (TEXT)
            - interaction_type (TEXT)
            - probability_class (TEXT: HIGH, MEDIUM, LOW)
            - message_content (TEXT)
            - response_content (TEXT)
            - context_summary (TEXT)
            - reasoning (TEXT)

            Example:
            SELECT timestamp, probability_class, context_summary 
            FROM chat_monitoring 
            WHERE probability_class = 'LOW'
            LIMIT 5;
ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSELECT SQL query to execute

TDQS

A3.9/5.0
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 discloses that this tool executes SELECT queries (implying read-only behavior), provides a detailed schema reference for the main table, and includes a concrete example showing query structure and limitations (LIMIT 5). However, it doesn't mention potential errors, performance considerations, or authentication 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?

The description is appropriately sized and front-loaded with the core purpose. The schema reference and example are useful additions, though the example could be more concise. Every sentence earns its place by providing necessary context for query construction.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (executing arbitrary SELECT queries), no annotations, and no output schema, the description does well by providing a detailed table schema and example. However, it lacks information about return format, error handling, or query limitations beyond the example, leaving some gaps for a tool with significant behavioral implications.

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?

Schema description coverage is 100% (the single parameter 'query' is fully described in the schema as 'SELECT SQL query to execute'), so the baseline is 3. The description adds value by providing a schema reference and example query that clarifies what constitutes a valid query, but doesn't add syntax or format details beyond what the schema implies.

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 ('Execute a SELECT query') and resource ('on the SQLite database'), distinguishing it from sibling tools like write_query (which presumably handles writes) and list_tables/describe_table (which handle metadata). The description explicitly mentions SELECT queries, which helps differentiate from other database operations.

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 through the example (showing a SELECT query on the chat_monitoring table), but doesn't explicitly state when to use this tool versus alternatives like read-logs or log-query (which might be for specific log access). There's no guidance on prerequisites, error conditions, or explicit exclusions.

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

write_queryC

Execute an INSERT, UPDATE, or DELETE query

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesNon-SELECT SQL query to execute

TDQS

C2.9/5.0
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 states the tool executes queries but doesn't mention critical aspects like whether it requires specific permissions, if changes are reversible, potential side effects (e.g., data loss), error handling, or transaction behavior. This is a significant gap for a mutation tool.

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 that directly states the tool's function without any unnecessary words. It is front-loaded with the core action and resource, making it easy to parse and understand 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 the complexity of a mutation tool with no annotations and no output schema, the description is incomplete. It lacks information on behavioral traits (e.g., safety, permissions), expected outputs, error conditions, and how it differs from sibling tools. This leaves the agent with insufficient context for reliable tool selection and invocation.

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?

The schema description coverage is 100%, with the single parameter 'query' documented as a 'Non-SELECT SQL query to execute'. The description adds value by specifying the allowed query types (INSERT, UPDATE, DELETE), which clarifies the parameter's semantics beyond the schema's generic 'Non-SELECT' label. However, it doesn't provide additional details like syntax examples or 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's purpose with specific verbs (INSERT, UPDATE, DELETE) and resource (query), making it evident this executes data manipulation SQL statements. However, it doesn't explicitly distinguish itself from sibling tools like 'create_table' or 'log-query', which might also involve database 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?

The description provides no guidance on when to use this tool versus alternatives like 'read_query' for SELECT queries or 'create_table' for table creation. It mentions the types of queries (INSERT, UPDATE, DELETE) but doesn't specify contexts, prerequisites, or exclusions, leaving the agent to infer usage from the tool name alone.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updates
    • First observedappend_insight
    • First observedcreate_table
    • First observeddescribe_table
    • First observedlist_tables
    • First observedlog-query
    • First observedread_query
    • First observedread-logs
    • First observedwrite_query
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

C2.8/5.0

Scored across 8 tools

Disambiguation3/5

Most tools have distinct purposes (e.g., create_table vs. list_tables), but there is overlap between log-query and read-logs, as both involve logging/retrieving conversation variations, which could cause confusion. Additionally, read_query and write_query are clearly distinct from each other but share the database query domain with other tools like describe_table.

Naming Consistency2/5

Naming is inconsistent with mixed conventions: some use snake_case (append_insight, create_table), others use kebab-case (log-query, read-logs), and some are unclear (read_query vs. write_query, which are snake_case but differ in verb style). There is no uniform pattern across all tools, making it harder to predict naming.

Tool Count4/5

With 8 tools, the count is reasonable for a server focused on database operations and conversation logging. It covers core functions without being overly bloated, though the scope might feel slightly broad due to mixing database management with logging features.

Completeness3/5

For database operations, there is good coverage (create, list, describe, read, write), but lacks update/delete specific tools, relying on write_query for those. For conversation logging, it has logging and retrieval, but no direct management tools like delete_logs or update_logs, leaving minor gaps in the lifecycle.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Paprika SQL MCP Server

    jonaheaton
    F
    license
    Not graded
    quality
    F
    maintenance
    A Model Context Protocol desktop extension that allows Claude to query and interact with custom SQL databases in real-time during conversations.
    1
    -

  • ClaudeX

    kunwar-shah
    A
    license
    A
    quality
    B
    maintenance
    Persistent memory + FTS5 full-text search for Claude Code conversation history. Indexes ~/.claude/projects/ JSONL into SQLite, exposes 10 MCP tools (store/recall/search memories, browse sessions, get summaries) plus prompts. Includes a web UI for visual exploration
    10
    42
    93
    MIT

  • flightlog

    RobHudson72
    A
    license
    A
    quality
    D
    maintenance
    An MCP server that indexes Claude Code conversation history into SQLite, enabling full-text search across past sessions for context recovery and cross-agent observability.
    10
    3
    MIT

Appeared in Searches