Skip to main content
Glama
Nery2004

POS Support MCP Server

by Nery2004

POS Support MCP Server

Overview

POS Support MCP Server is a standalone local Model Context Protocol server for a fictitious point-of-sale technical-support domain. It exposes eleven focused tools for branches, terminals, incidents, historical solutions, and incident management. It is designed for a university networking demonstration and uses only local simulated data.

Related MCP server: brain2

Features

  • Four related entities: branches, terminals, incidents, and incident history.

  • Eight read-only and three mutating business tools.

  • Deterministic similar-incident search without AI or external services.

  • Atomic incident creation, update, resolution, and history writes.

  • Stable seed IDs for reproducible demonstrations.

  • Consistent structured success and business-error responses.

Architecture

MCP Client
    ↓ stdio
POS Support MCP Server
    ↓
Validation / Service Layer
    ↓
Repository Layer
    ↓
SQLite

Protocol registration, business rules, and parameterized SQL are kept in separate modules. The package does not depend on the parent chatbot project.

Requirements

  • Python 3.10 or newer

  • mcp>=2,<3

  • SQLite support from the Python standard library

No database server, web framework, ORM, or external service is required.

Installation

git clone https://github.com/Nery2004/pos-support-mcp-server.git
cd pos-support-mcp-server
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e .

Database Initialization

Create or reset the default database and load deterministic seed data:

python3 -m pos_support_mcp_server.seed --reset

The default file is data/pos_support.db. Override it for an isolated run:

POS_SUPPORT_DB_PATH=/absolute/path/support.db \
python3 -m pos_support_mcp_server.seed --reset

--reset removes only the configured database file and its SQLite sidecars. Runtime database files are ignored by Git.

Running the Server

After installation and seeding:

python3 -m pos_support_mcp_server.server

The installed console entry point is equivalent:

pos-support-mcp

MCP Transport

The server uses the high-level MCPServer API from MCP Python SDK 2.x and runs only over stdio. It opens no network port and writes no debug output to stdout.

Example client configuration after installing the package into the selected Python environment:

{
  "transport": "stdio",
  "command": "/absolute/path/to/.venv/bin/python",
  "args": ["-m", "pos_support_mcp_server.server"],
  "env": {
    "POS_SUPPORT_DB_PATH": "/absolute/path/to/pos_support.db"
  }
}

Replace both absolute paths with paths on the client machine. The interpreter must be the environment where this project was installed.

Available Tools

Read-only:

  • list_branches

  • get_branch

  • list_terminals

  • get_terminal

  • list_incidents

  • get_incident

  • search_similar_incidents

  • get_critical_incidents

Mutating:

  • create_incident

  • update_incident

  • resolve_incident

Tool Parameters

Tool

Parameters

list_branches

optional status

get_branch

branch_code

list_terminals

optional branch_code, status

get_terminal

branch_code, terminal_code

list_incidents

optional branch_code, terminal_code, status, priority

get_incident

incident_id

search_similar_incidents

query, optional branch/terminal, limit=5

create_incident

branch, optional terminal, title, description, priority

update_incident

incident ID and at least one editable field or note

resolve_incident

incident ID, solution, optional note

get_critical_incidents

optional branch_code

Example Usage

Conceptual MCP calls:

{"name": "get_terminal", "arguments": {"branch_code": "001", "terminal_code": "03"}}
{"name": "create_incident", "arguments": {"branch_code": "003", "terminal_code": "04", "title": "Connection drops", "description": "Checkout loses the POS server connection.", "priority": "high"}}
{"name": "resolve_incident", "arguments": {"incident_id": 21, "solution": "Restarted the local POS service."}}

Tools return a structured envelope:

{"success": true, "data": {}}

Seed Data

The deterministic seed contains 4 branches, 16 terminals, 20 incidents, and 35 history records. It covers online/offline terminals, printers, scanners, network timeouts, payments, stopped POS services, and synchronization issues. All names, addresses, incidents, and solutions are fictitious.

Search normalizes English and Spanish text, removes punctuation and a small stop-word set, then computes Jaccard similarity over unique terms from title, description, and solution. Only positive scores are returned. Results are ordered by score descending and incident ID ascending, rounded to four decimal places, and limited to 1–20 entries.

Error Handling

Business failures use success: false with stable codes such as BRANCH_NOT_FOUND, TERMINAL_NOT_FOUND, INCIDENT_NOT_FOUND, INVALID_ARGUMENT, and INVALID_STATUS_TRANSITION. Unexpected SQLite errors become a sanitized DATABASE_ERROR; SQL, paths, and stack traces are omitted.

Security

  • Local stdio only; no HTTP server or external requests.

  • Parameterized SQL and constrained business inputs.

  • No arbitrary SQL, shell, Python, filesystem, or command tool.

  • No subprocess execution.

  • Fictitious seed data only.

  • Mutating tools must not be automatically retried by a host.

  • Runtime databases and credentials are excluded from publication.

Testing

Run the standalone tests with a temporary SQLite database per test:

python3 -m unittest discover -s tests -v

The test suite includes a real MCP stdio integration test that starts the server as a subprocess, discovers exactly eleven tools, calls get_branch, and verifies a clean shutdown:

python3 -m unittest tests.test_mcp_integration -v

Project Structure

.
├── .gitignore
├── README.md
├── pyproject.toml
├── data/.gitkeep
├── src/pos_support_mcp_server/
│   ├── __init__.py
│   ├── database.py
│   ├── repository.py
│   ├── responses.py
│   ├── seed.py
│   ├── server.py
│   ├── service.py
│   ├── similarity.py
│   └── validation.py
└── tests/

This repository intentionally contains only the standalone POS Support MCP Server. It excludes chatbot integrations, external services, runtime databases, and environment files.

Available Tools

11 tools
create_incidentB

Create an open branch-wide or terminal-specific support incident.

ParametersJSON Schema
NameRequiredDescriptionDefault
titleYes
priorityYes
branch_codeYes
descriptionYes
terminal_codeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.3/5.0
Behavior3/5

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

With no annotations, the description carries the behavioral burden. It discloses that the incident is created with an 'open' status and that its scope can be branch-wide or terminal-specific, which is useful. However, it does not mention side effects, prerequisites, or what happens if terminal_code is omitted beyond relying on schema default.

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 with no redundant words; it names the action, resource, and key scoping distinction efficiently.

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 sparse for a 5-parameter create tool with no annotations. It omits how priority values should be chosen, how to obtain valid branch/terminal codes, and whether terminal_code absence means branch-wide. Output schema covers return shape, but input semantics remain underspecified.

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 only maps scope to branch_code/terminal_code via 'branch-wide or terminal-specific', leaving title, description, and priority semantics undocumented.

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 a specific verb ('Create') and resource ('support incident'), and qualifies scope as branch-wide or terminal-specific. This clearly separates it from sibling operations like update_incident, resolve_incident, and list_incidents.

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 when-to-use or when-not-to-use guidance is provided, and no alternatives are named. The verb 'Create' implies it is for new incidents, but the description does not mention checking search_similar_incidents first or explain when branch-wide vs terminal-specific should be chosen.

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

get_branchA

Get one branch by its stable business code.

ParametersJSON Schema
NameRequiredDescriptionDefault
branch_codeYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/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 of behavioral disclosure. It communicates a read-style lookup by code, which is useful, but it omits behavior for missing or invalid codes, authorization needs, and error handling. For a simple getter this is minimally transparent 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 eight words, front-loaded with the verb and object, and contains no filler or repetition of schema details. Every word earns its place.

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 one-parameter get-by-code tool with an output schema present, the description is largely complete: it states the operation, resource, and key parameter semantics. It could add a note about not-found behavior or point to list_branches for discovering codes, but those are minor gaps.

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 schema provides only the parameter name, title, and minLength, with 0% description coverage. The description adds meaningful semantics by explaining that branch_code is a 'stable business code,' distinguishing it from an internal ID or arbitrary label. It lacks format examples, but for a single required parameter this is sufficient.

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 and resource ('Get one branch') and clearly distinguishes itself from list-oriented siblings like list_branches by specifying a single object lookup. The qualifier 'by its stable business code' adds concrete selection semantics.

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 this tool is for retrieving a single branch when you already have a stable business code, but it never explicitly names an alternative such as list_branches for browsing branches. It gives no when-not-to-use guidance, so usage is only implied rather than stated.

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

get_critical_incidentsA

List unresolved critical incidents, optionally for one branch.

ParametersJSON Schema
NameRequiredDescriptionDefault
branch_codeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
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 the core filtering behavior (unresolved, critical, optional branch scope) and the verb 'List' implies a read-only, non-destructive operation. It does not mention pagination, sorting, or behavior when branch_code is omitted, but these are minor for a simple list tool and covered by the output schema.

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 concise sentence, front-loaded with the action and resource, followed by the qualifier. No filler or redundant phrasing.

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?

Simple tool with one optional parameter and an output schema. The description covers the tool's purpose and the branch filter; the schema documents the parameter; the output schema documents return values. For a list operation, this is sufficient information for an agent to select and invoke the tool correctly.

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?

Schema has 0% description coverage, so the description must compensate. The phrase 'optionally for one branch' tells the agent that branch_code is a filter that narrows to a single branch and that omitting it returns all branches (matching the schema default null). This adds meaning beyond the raw schema type, though it does not detail accepted value formats.

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 action ('List') on a specific resource ('unresolved critical incidents') with an optional branch filter. This distinguishes it from siblings like list_incidents (general list) and get_incident (single item).

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?

Usage is implied: the description indicates it is for unresolved critical incidents and optionally a specific branch, but it never explicitly names list_incidents as the alternative for other incident types or states when not to use this tool. With a sibling named list_incidents, explicit routing would improve clarity.

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

get_incidentB

Get an incident with its branch, optional terminal, and ordered history.

ParametersJSON Schema
NameRequiredDescriptionDefault
incident_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.4/5.0
Behavior3/5

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

With no annotations, the description carries the behavioral burden. It discloses that the result includes a branch, an optional terminal, and ordered history, which is useful. However, it does not mention error behavior, authentication needs, or that this is a read-only operation, relying on the verb 'Get' to imply it.

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 with no filler. It conveys the action, the target resource, and the key included components efficiently.

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 has only one parameter and an output schema exists, the description is largely sufficient: it identifies the incident, notes the included related data, and lets the schema define the exact return shape. Minor gaps around alternative selection and error behavior remain.

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%, and the description does not compensate by explaining incident_id beyond the resource name. The single parameter is self-descriptive from its name and integer type, so this is not a critical gap, but 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 the action ('Get') and resource ('an incident'), and specifies what is included: 'its branch, optional terminal, and ordered history.' This distinguishes it from list-oriented siblings, though it does not explicitly name any alternative.

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 singular 'an incident' and the required incident_id imply this is for retrieving a specific incident, but the description does not explicitly state when to choose this over get_critical_incidents, search_similar_incidents, or list_incidents. Usage context is implied rather than stated.

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

get_terminalB

Get one terminal by branch code and branch-local terminal code.

ParametersJSON Schema
NameRequiredDescriptionDefault
branch_codeYes
terminal_codeYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.2/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 only states that the tool 'gets' a terminal, implying a read operation, but it does not describe what happens if the terminal is not found, any access requirements, or whether the response is a single object versus a wrapped result.

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 entire description is one clean sentence that front-loads the action and resource, then states the two required identifiers. Every word earns its place, and there is no redundant or filler content.

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 and has an output schema, so return values are already covered. However, the description is sparse: it omits usage guidance, alternative routing, and edge-case behavior such as not-found handling. For a basic get-by-composite-key tool this is minimally viable, but there are clear gaps around when to use it.

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?

Schema description coverage is 0%, so the description must add meaning to the parameters. It does this by explaining that terminal_code is 'branch-local,' clarifying that the key is composite and that codes are scoped per branch. This is valuable disambiguation beyond the raw schema property names, though it does not fully specify formats 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 verb 'Get' and the resource 'one terminal,' specifying that it retrieves a single record by two identifiers. It is distinct from list_terminals because it uses 'one' rather than 'list,' but it does not explicitly name or contrast sibling 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?

The description provides no guidance about when to use this tool instead of siblings like list_terminals or get_branch. There is no context for when a user needs a single terminal by composite key versus a list or branch-level retrieval, and no exclusions are mentioned.

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

list_branchesA

List fictitious branches, optionally filtered by status.

ParametersJSON Schema
NameRequiredDescriptionDefault
statusNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior3/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. 'List' implies a read-only operation and the optional status filter communicates the main behavioral variation. However, it does not mention pagination, ordering, data scope ('fictitious'), or any other behavioral details that would help an agent understand the call outcome beyond the schema.

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 with no redundant words. It states the core action first and adds the optional filtering condition second. Every word earns its place.

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 simple list tool with one optional parameter and an output schema present, the description is largely sufficient. The only notable gap is the lack of explicit guidance about sibling tools, but the low complexity and schema coverage keep the tool invocable without more detail.

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?

Schema description coverage is 0%, so the description must compensate. It does so by explaining that 'status' acts as an optional filter, which is meaningful semantic information beyond the raw schema property definition. The enum values are already present in the schema, so the description's contribution is appropriate for the single parameter.

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'), the resource ('fictitious branches'), and the optional scoping mechanism ('filtered by status'). This distinguishes it from sibling tools like get_branch (singular retrieval) and list_terminals/list_incidents (different resources).

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 the tool: whenever a list of branches is needed, with status as an optional filter. It does not explicitly name excluded alternatives or say 'use get_branch for a single branch', but the resource scope is evident from the tool name and description.

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

list_incidentsB

List incidents using optional branch, terminal, status, and priority filters.

ParametersJSON Schema
NameRequiredDescriptionDefault
statusNo
priorityNo
branch_codeNo
terminal_codeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.3/5.0
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 of behavioral disclosure. It communicates that this is a non-destructive listing operation and that filters are optional, but it does not disclose pagination, ordering, filter-combination semantics, or what happens when no filters are supplied.

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 the primary action and resource front-loaded. Every word contributes meaning, and there is no redundant or filler content.

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?

For a straightforward filtered list tool, the description covers the core action and parameters, and an output schema exists so return structure does not need to be explained. But with no annotations, it lacks guidance on default behavior, pagination, or how to choose between this and the several incident-related sibling 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 0%, so the description must compensate. It identifies the four parameters and their role as filters, which adds some meaning beyond their names. However, it does not explain matching behavior, code formats for branch_code/terminal_code, or whether filters combine; the schema's enums already cover status and priority values.

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 states a specific verb ('List') and resource ('incidents'), and names the four filtering dimensions. It is clear enough to distinguish this tool from single-item tools like get_incident and semantic search like search_similar_incidents, though it does not explicitly contrast itself with any sibling.

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 this is the general-purpose tool for listing incidents, and the optional filters give context about its use. However, it provides no explicit guidance about when to prefer get_incident, search_similar_incidents, or get_critical_incidents instead.

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

list_terminalsB

List terminals, optionally filtered by branch and status.

ParametersJSON Schema
NameRequiredDescriptionDefault
statusNo
branch_codeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.2/5.0
Behavior2/5

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

No annotations are supplied, so the description must carry the behavioral burden. 'List' implies a read-only operation and the optional filters are mentioned, but nothing is disclosed about pagination, ordering, authorization, or failure modes. The safety profile is only inferred from the verb.

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 conveys the operation and filters with no filler. It is appropriately sized for the tool's simple signature.

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 description is enough to understand the basic list operation and optional filters, and an output schema covers return values. However, with no annotations and no usage or behavioral context, an agent still lacks guidance on pagination/ordering and how this tool relates to get_terminal.

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 needed to explain branch_code and status. It names both filter dimensions but does not clarify what values are valid, how branch_code should be sourced, or the meaning of each status, leaving the agent to infer from the schema's enum and naming.

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') with a clear resource ('terminals') and names the two optional filtering dimensions. This distinguishes it from siblings like get_terminal (single terminal retrieval) and list_branches (different resource).

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 when-to-use guidance or alternatives; it only states what the tool does and that filters are optional. It does not say to prefer get_terminal for a single terminal or explain when branch/status filtering is appropriate.

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

resolve_incidentC

Resolve an active incident with a required applied solution.

ParametersJSON Schema
NameRequiredDescriptionDefault
noteNo
solutionYes
incident_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.7/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 only says the incident must be active and a solution is required; it omits side effects such as status changes, behavior on already-resolved incidents, idempotency, permissions, or any consequences beyond applying the solution. This is insufficient for a mutating action.

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 short, front-loaded, and contains no filler – every word contributes to the core purpose. However, the brevity sacrifices useful detail that could be conveyed without bloating, so it is efficient rather than ideal.

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 3-parameter mutation tool with no annotations, the description is insufficiently complete. While an output schema exists, the agent lacks guidance on how resolve_incident differs from update_incident, preconditions, and parameter semantics. The description covers only the basic verb and a single requirement.

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 needed to explain the parameters, but it only mentions that a solution is required and applied. It does not clarify that incident_id identifies the target, what note is for, or what format/meaning solution should have. The schema provides only types and lengths, leaving the agent without semantic grounding.

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 states a clear verb ('Resolve') and resource ('active incident') and notes a required component ('solution'), making the core action understandable. However, it does not explicitly contrast with the sibling 'update_incident' or other incident tools, so full differentiation is left to inference.

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 when-to-use or when-not-to-use guidance is given. The phrase 'active incident' implies a precondition, but the description does not mention alternatives like 'update_incident' for modifying details, nor what to do if the incident is not active. The agent is left to infer the appropriate context.

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

search_similar_incidentsB

Find incidents using deterministic local Jaccard text similarity.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryYes
branch_codeNo
terminal_codeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.2/5.0
Behavior3/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 usefully reveals that the similarity is deterministic and local, which are meaningful behavioral traits. However, it does not clarify what 'local' means, whether results are sorted, or whether this is a read-only operation, leaving important behavior unexplained.

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, tight sentence with no filler. It conveys the core mechanism and distinguishes the tool from simple incident listing, making every word earn 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?

For a search tool with four parameters and no annotations, the description is too sparse. It omits how branch_code and terminal_code scope the search, what the default limit means, how results are ranked, and when this tool should be preferred. The output schema may document the return shape, but the behavioral and usage context remains incomplete.

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, but it only references text similarity and does not explain the query, limit, branch_code, or terminal_code parameters. The parameter names are suggestive but not descriptive, and the description adds no insight into how they affect the search.

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 states a clear verb ('Find incidents') and resource, and adds a distinctive method ('deterministic local Jaccard text similarity') that separates it from typical listing or retrieval tools like list_incidents or get_incident. It could be stronger by explicitly naming the sibling it is not, but the core purpose is unambiguous.

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 this is for finding textually similar incidents rather than exact-match retrieval or listing, but it does not provide explicit guidance on when to choose this tool over list_incidents or get_incident. No alternative tools or exclusion criteria are mentioned.

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

update_incidentB

Edit an active incident or move it from open to in_progress.

ParametersJSON Schema
NameRequiredDescriptionDefault
noteNo
titleNo
statusNo
priorityNo
descriptionNo
incident_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.2/5.0
Behavior3/5

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

With no annotations, the description carries the behavioral burden. It clearly indicates this is a mutating operation and discloses the only supported status transition, which is the most likely side effect. It does not mention permissions, reversibility, or behavior on already-resolved incidents, but the basic safety profile of a state-changing update is evident.

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 the verb and resource first; the status transition earns its place as key behavioral context. It is efficient, though it could have added a brief alternative-tool pointer without becoming bloated.

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 output schema exists and the input schema carries field constraints, the description offers enough for a basic call: edit an active incident, optionally move to in_progress, and rely on the schema for fields. It is incomplete around what 'active' means, whether resolved incidents are excluded, and how this relates to resolve_incident.

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 needed to add meaning to the six parameters, but it adds none. The schema's self-explanatory names and constraints partially compensate; still, the description does not clarify distinctions like note vs description or how the optional fields interact.

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 uses the specific verb 'Edit' and names the resource, an incident, while constraining the action to active incidents and the status transition open to in_progress. It is clear enough to distinguish from create_incident and resolve_incident, though it does not explicitly name those 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 phrase 'active incident' and the open->in_progress transition communicate when the tool applies, but no alternative tools are named and no 'when not to use' guidance is provided. Usage must be inferred from the limited status transition rather than stated explicitly.

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. Dates show when Glama detected each change.

  1. 11 tool updatesv0.1.0
    • First observedcreate_incident
    • First observedget_branch
    • First observedget_critical_incidents
    • First observedget_incident
    • First observedget_terminal
    • First observedlist_branches
    • First observedlist_incidents
    • First observedlist_terminals
    • First observedresolve_incident
    • First observedsearch_similar_incidents
    • First observedupdate_incident

TDQS

A3.5/5.0

Scored across 11 tools

Disambiguation4/5

Most tools are clearly distinct: get_* for single resources, list_* for collections, and create/update/resolve for incident lifecycle. The main overlap is get_critical_incidents, which largely duplicates list_incidents with status and priority filters, though it may serve as a convenience shortcut.

Naming Consistency4/5

Tool names generally follow a verb_noun pattern with singular get_ and plural list_ prefixes, and create/update/resolve are consistent. The slight inconsistency is get_critical_incidents returning a list rather than using list_, but the naming remains readable and predictable.

Tool Count5/5

Eleven tools is well-scoped for a POS support domain, covering branch/terminal lookup, incident management, and incident search. Each tool has a clear role, and the count feels appropriate without unnecessary bloat.

Completeness4/5

The incident lifecycle is well covered with create, update, resolve, and detailed retrieval, and branch/terminal context is supported. Minor gaps exist such as no explicit cancel/reopen operation or dedicated comment/note endpoint, but agents can handle most support workflows.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    A universal SQLite database management tool that enables SQL query execution through MCP protocol. Supports SELECT/INSERT/UPDATE/DELETE/CREATE operations with built-in SQL injection protection across stdio, SSE, and streamable-http communication modes.
    MIT
  • F
    license
    Not graded
    quality
    C
    maintenance
    A database-first personal knowledge management system powered by a local MCP server, providing 29 tools to manage and search structured knowledge (meetings, emails, people, accounts, projects, todos, etc.) via a single SQLite file.
    -
  • A
    license
    Not graded
    quality
    C
    maintenance
    A security-focused Model Context Protocol server for task management over stdio, backed by SQLite. It exposes tools to create, list, complete, delete, and search tasks with strict validation, parameterized SQL, confirmation for deletes, and full audit logging.
    10
    MIT
  • A
    license
    B
    quality
    C
    maintenance
    Enables local engineering workflow management by consolidating tickets, QA evidence, time tracking, root cause investigation, knowledge, and reporting into a single SQLite database, allowing generation of complete ticket packages for handoffs, dailies, or career evidence.
    23
    319
    MIT

Latest Blog Posts

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/Nery2004/pos-support-mcp-server'

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