Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona herramientas y recursos estandarizados para interactuar con la API de PI Dashboard. Esta implementación permite a Claude y a otros asistentes de IA compatibles con MCP acceder y gestionar de forma segura los recursos de PI Dashboard, incluyendo categorías y gráficos.
A continuación se muestran escenarios de uso típicos para este servidor MCP después de completar la configuración.
Autenticación inicial:
Ejecute las siguientes instrucciones para establecer una conexión:
Ensure the PI API MCP server is running
Set the API URL to http://localhost:8224/pi/api/v2
Use the authenticate tool for authentication guidance
Check the connection status to verify everything is working
List two charts from the dashboardAnálisis de gráficos:
Si el ID del gráfico 450 contiene información de metadatos, utilice el siguiente mensaje:
Retrieve the metadata from chart ID 450
Extract the chart JSON data from ID 450
Identify chart IDs associated with claims
Obtain JSON data for the identified charts
Analyze the data to generate actionable insightsEjemplo de salida:
Para instalar pi-api-mcp-server para Claude Desktop automáticamente a través de Smithery :
npx -y @smithery/cli install @mingzilla/pi-api-mcp-server --client claudeRelated MCP server: tableau-mcp-navi
No es necesaria la configuración del servidor MCP
Configuración del archivo de configuración del cliente MCP:
{
"mcpServers": {
"pi-api": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"API_URL=http://localhost:8224/pi/api/v2",
"-e",
"PI_API_KEY=XXXXXXXX",
"mingzilla/pi-api-mcp-server"
],
"disabled": false,
"autoApprove": [
"keep-session-alive",
"check-connection",
"authenticate",
"list-categories",
"get-category",
"list-charts",
"get-chart",
"export-chart",
"get-filterable-attributes",
"export-chart"
]
}
}
}
Nota importante : Si no se proporciona el parámetro --api-url durante la inicialización, el servidor le solicitará que configure la URL de la API con la herramienta set-api-url antes de ejecutar cualquier operación. Este diseño permite una configuración flexible en entornos donde la URL no está predeterminada al inicio.
Acceda a la configuración de su aplicación Claude for Desktop en:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Ventanas: %APPDATA%\Claude\claude_desktop_config.json
Linux: utilice otras herramientas por ahora, por ejemplo, Cline: pídale que le muestre el archivo de configuración de MCP
get-filterable-attributes : obtiene la lista de atributos que se pueden usar para filtrar examinando una entidad de muestra
Get the filterable attributes for chart entitiescheck-connection : comprueba si la URL de la API actual y la autenticación son válidas
set-api-url : configura la URL de la API base para todas las solicitudes
Set the API URL to http://localhost:8224/pi/api/v2autenticar : obtener orientación sobre las opciones de autenticación
authenticate-with-credentials : Autenticar con nombre de usuario y contraseña (opción de último recurso)
keep-session-alive : verifica y actualiza el token de autenticación actual (también se utiliza para la autenticación basada en token)
cerrar sesión : invalida el token actual y finaliza la sesión
set-organization : Establece el ID de la organización para solicitudes posteriores
list-categories : enumera todas las categorías con soporte de filtrado
get-category : Obtener una categoría por ID
create-category : Crea una nueva categoría
update-category : Actualizar una categoría existente
delete-category : Eliminar una categoría
list-category-objects : enumera todos los objetos de una categoría específica
list-charts : enumera todos los gráficos con soporte de filtrado
get-chart : Obtener un gráfico por ID
delete-chart : Eliminar un gráfico
export-chart : Exportar un gráfico en varios formatos
auth://status : Obtener el estado de autenticación
categorías://lista : Lista todas las categorías
categorías://{id} : Obtener una categoría específica
categorías://{categoryId}/objects : Obtener objetos para una categoría específica
charts://list : Lista todos los gráficos
charts://{id} : Obtener un gráfico específico
charts://{id}/export/{format} : Exportar un gráfico en un formato específico
analizar-categorías : Analizar categorías en el panel
analizar-gráficos : Analizar gráficos en el panel
compare-charts : Compara datos entre dos gráficos
category-usage-analysis : Analiza cómo se utilizan las categorías en los gráficos
use-filters : muestra cómo usar filtros de manera efectiva con esta API
A continuación se muestran algunos ejemplos de consultas para utilizar con Claude después de conectarse al servidor:
Please use the set-api-url tool to set the PI API URL to http://localhost:8224/pi/api/v2Please help me authenticate to the PI API.I have a token. Please use the keep-session-alive tool with my token: [YOUR_TOKEN_HERE]Please check if my connection to the PI API is working properly.List all categories in the dashboard.Get details about category with ID 123.List all the charts available in the dashboard.Export chart with ID 456 as a PDF.Get the filterable attributes for chart entities to understand what fields I can filter on.List charts with description containing "revenue" using the filter option.Analyze the categories in the dashboard.Compare data between charts 123 and 456.Show me how to use filters effectively with this API.Nota: también puedes utilizar start.sh para ejecutar el servidor de desarrollo.
# Clone the repository (SSH or HTTPS option)
git clone git@github.com:mingzilla/pi-api-mcp-server.git
cd pi-api-mcp-server
# Install dependencies
npm install
./dependencies.sh # Installs global dependencies to enable MCP client connection via "@mingzilla/pi-api-mcp-server"
# Build the project
npm run build
# Execute the server
npm start# Global installation
npm install -g @mingzilla/pi-api-mcp-server
# Direct execution via npx
npx @mingzilla/pi-api-mcp-server --api-url "http://localhost:8224/pi/api/v2" --auth-token "XXXXXXXX"Integración con Claude para escritorio:
Ejecute las instrucciones en la sección "Ejecución local"
Asegúrese de que ./dependencies.sh se haya ejecutado para instalar las dependencias necesarias
Implemente la siguiente configuración (Nota: "@mingzilla/pi-api-mcp-server" hace referencia al paquete instalado a través de "Ejecución local")
{
"mcpServers": {
"pi-api": {
"command": "npx",
"args": [
"-y",
"@mingzilla/pi-api-mcp-server",
"--api-url",
"http://localhost:8224/pi/api/v2",
"--auth-token",
"XXXXXXXX"
],
"autoApprove": [
"keep-session-alive",
"check-connection",
"authenticate",
"list-categories",
"get-category",
"list-charts",
"get-chart",
"export-chart",
"get-filterable-attributes",
"export-chart"
]
}
}
}Ejecute el servidor usando ./start.sh
Establezca la configuración con la ruta al archivo build/index.js
./start.sh{
"mcpServers": {
"pi-api": {
"command": "node",
"args": [
"/home/mingzilla/dev/tool-mcp-pi-api-server/build/index.js",
"--api-url",
"http://localhost:8224/pi/api/v2",
"--auth-token",
"XXXXXXXX"
],
"autoApprove": [
"keep-session-alive",
"check-connection",
"authenticate",
"list-categories",
"get-category",
"list-charts",
"get-chart",
"export-chart",
"get-filterable-attributes",
"export-chart"
]
}
}
}actualizar código -> iniciar servidor local -> probar servidor local con ruta de archivo a index.js
Actualizar el archivo readme.md -> cambiar la sección de configuración de mcpServers: docker + node + npx
./publish.sh - publicar en npm
./dockerBuild.sh -> ./dockerPublish.sh (edite el número de versión para que coincida con package.json) -> pruebe la configuración de Docker
enviar código a github
Licencia MIT
Ming Huang (mingzilla)
Guide for authenticating with the PI API
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It merely says 'Guide for authenticating' but does not disclose whether it returns a token, initiates a flow, or outputs instructions. Behavioral effects are absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one phrase) and front-loaded, but it lacks substance. Conciseness is good, but at the expense of clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, output schema, or annotations, the description is insufficient. It fails to explain the tool's operation or outcome, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description does not need to add parameter information. No misinformation is present, achieving the baseline of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Guide for authenticating with the PI API', which identifies the resource and action but is vague. It does not clarify whether the tool performs authentication or provides instructions, and it does not distinguish it from the sibling 'authenticate-with-credentials'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'authenticate-with-credentials' or 'check-connection'. The description omits any context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Authenticate with the PI API using username and password (last resort option)
| Name | Required | Description | Default |
|---|---|---|---|
| credentials | Yes | Username and password as 'username password' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions using username and password but does not explain side effects like session creation, security implications, or error states. 'Last resort' hints at reduced preference but lacks specificity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool performs authentication but does not describe the return value (e.g., token) or how the agent should use the resulting authenticated session. Essential context for an AI agent is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds no extra meaning beyond what the schema already provides. It essentially restates the schema's description of the only parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (authenticate), the resource (PI API), and the method (username and password), and distinguishes it as a 'last resort option', which sets it apart from sibling authentication tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'last resort option' explicitly guides when to use this tool (when other authentication methods fail or are unavailable), implying when not to use it. However, it does not name specific alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if the current API URL and authentication are valid
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It only states the purpose but does not mention side effects, return values, error conditions, or whether it makes network calls—critical for a tool that checks connection status.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous words. Every word contributes to the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description covers the essential purpose. However, it could be enhanced by mentioning return type or potential errors to fully inform the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters with 100% coverage, so the description need not add parameter details. It meaningfully explains what the tool does (checks URL and auth), providing context beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'check' and the specific resources being checked ('current API URL and authentication'), which differentiates it from sibling tools like authenticate (which sets credentials) or keep-session-alive (which maintains a session).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies using this tool to verify connection validity, but it does not provide explicit guidance on when to use it versus alternatives like authenticate or keep-session-alive, nor does it specify 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 a new category
| Name | Required | Description | Default |
|---|---|---|---|
| description | Yes | Unique name of a category | |
| orgId | Yes | Organization ID | |
| label | No | Alternative text for the category | |
| helpText | No | Help text to describe the category | |
| categoryObjectsPosition | No | Position of category objects panel | |
| cascadeFilters | No | Enable cascading filters |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only states 'create', but does not disclose side effects, authentication requirements, or any behavioral traits beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise, but it may be underspecified for a tool with 6 parameters. While not verbose, it could be more informative without being wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, no output schema, and no annotations, the description is insufficient. It does not explain what a category is, success behavior, or error scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 description adds no additional parameter information beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new category' clearly states the action and resource. It is a specific verb+resource combination, but does not differentiate from sibling tools like 'update-category' or 'get-category', which would clarify unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., update-category). No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a category
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Category ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description lacks disclosure of critical behavioral details: irreversible destruction, what happens to objects in the category, permission requirements, error responses. No annotations are provided to compensate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is extremely brief (one sentence), which is concise but at the expense of completeness. It misses important details like side effects, constraints, or output. Not optimally structured for agent comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description fails to explain return values (e.g., success indicator), error conditions, or irreversible side effects. Incomplete for a potentially destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema provides full coverage for the one parameter (id) with its description 'Category ID'. The tool description adds no additional meaning beyond what the schema already provides. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description 'Delete a category' clearly states verb and resource. It distinguishes from sibling tools like create-category, get-category, update-category by specifying the delete action. However, it lacks scope details like whether it deletes associated objects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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. There is no mention of alternatives (e.g., update-category for modifying instead of deleting) or context like prerequisites (e.g., category must exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a chart
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Chart ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description fails to disclose behavioral traits such as permament deletion, dependencies, or required permissions. For a destructive action, this gap is significant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at three words, but this conciseness comes at the cost of missing valuable context. It could be improved with minimal additions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (one param, no output), the description is partially complete, but lacks behavioral transparency. It does not fully equip an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds no additional meaning beyond the schema's label 'Chart ID'. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a chart, with a specific verb and resource. Sibling tools like delete-category are differentiated by the resource type, making purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or conditions for deletion. The description is silent on context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a chart in various formats
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Chart ID | |
| format | Yes | Export format |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose whether export is destructive, requires authentication, or what happens on error. The agent must infer safety from the name alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence. It avoids unnecessary words but may be too brief to provide full context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about the output format behavior, whether the export triggers a download or returns data inline, and any side effects. Without an output schema, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions, so the description adds no extra semantics. The description does not elaborate on parameter usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'export' and resource 'chart', with 'various formats' indicating output options. It distinguishes from siblings like 'get-chart' or 'delete-chart', though it could be more precise about the available formats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'get-chart' or 'list-charts'. The description does not mention prerequisites or context for export.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a category by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Category ID |
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 fails to disclose what happens if the ID is not found, permission requirements, or side effects. For a read tool, basic behavioral details are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff, front-loaded with the purpose. Conciseness is optimal for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (1 param, no output schema), the description is minimally adequate but lacks context about return value format or error behavior. It does not explain if the tool returns a full object or just an ID.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter 'id' (described as 'Category ID'), so the description adds no additional meaning. Baseline score of 3 applies since schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get a category by ID' clearly states the action (get) and the resource (category), and distinguishes it from sibling tools like list-categories (which returns all) and create/update/delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., list-categories) or when not to use it. The agent receives no context about prerequisites or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a chart by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Chart ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full transparency burden. It only states the action without disclosing behavioral traits such as authentication requirements, read-only status, side effects, or error conditions. Simple retrieval is implied but not confirmed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the verb and resource. Every word is necessary, and there is no superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval operation with a single parameter, the description is mostly complete. However, the lack of an output schema means the description should hint at the return value (e.g., 'returns the chart object') for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (one parameter 'id' described as 'Chart ID'). The description adds no additional meaning beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get a chart by ID' clearly states the verb ('Get'), resource ('chart'), and scope ('by ID'). It distinguishes from sibling tools like 'list-charts' (list) and 'delete-chart' (delete), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific chart ID, but provides no explicit guidance on when to use this tool over alternatives like 'get-category' or 'list-charts'. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the list of attributes that can be used for filtering by examining a sample entity
| Name | Required | Description | Default |
|---|---|---|---|
| entityType | Yes | Type of entity to examine (chart or category) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions 'by examining a sample entity,' implying a read operation, but does not explicitly state that it is read-only, whether it requires authentication, or if it has any side effects. This lack of detail reduces transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the essential information without any superfluous words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description gives the core purpose but does not specify the return format or any behavioral details like error handling. It is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the entityType parameter described. The tool description adds no additional meaning beyond the schema's own description. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a list of attributes usable for filtering, specifying the method (examining a sample entity). This distinguishes it from sibling tools like list-charts or update-category, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 before constructing filter queries or after selecting an entity type. No context on prerequisites or conditions for use is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify and refresh the current authentication token (also used for token-based authentication)
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Optional: Provide a token to use for authentication |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose all behavioral traits. It mentions 'verify' and 'refresh', implying mutation, but lacks details on side effects (e.g., token invalidation), error conditions, or required permissions. This is insufficient for a tool that modifies authentication state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the core purpose without unnecessary words. It is concise and front-loaded, but could be more structured to separate 'verify' and 'refresh' actions or add usage notes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's role in session management, the description is incomplete. It does not explain return values, behavior on expired tokens, or that it should be called periodically. This lack of context forces the agent to infer important behaviors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides a description for the 'token' parameter (optional, for authentication). The tool description adds no additional meaning or context about this parameter. Since schema coverage is 100%, the baseline is 3, and no extra value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool verifies and refreshes the authentication token, which is a specific verb-resource pair. It also mentions its use for token-based authentication, giving context. However, it does not explicitly differentiate from sibling tools like 'authenticate' or 'authenticate-with-credentials', lacking a distinct separation statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 'authenticate' or 'logout'. It only implies a use case for maintaining a session, but does not explicitly state when not to use it or specify prerequisites like having an existing session.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all categories with filtering support
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Filter criteria in the format 'fieldName(operator)=value'. Multiple filters can be combined with & (e.g., 'description(like)=dashboard&orgId(eq)=1'). Available operators: eq, ne, gt, lt, ge, le, like, nlike. Use get-filterable-attributes tool to see available fields. | |
| page | No | Page number for pagination | |
| pageSize | No | Number of items per page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states 'list all categories with filtering support'. It does not disclose pagination behavior (though schema has page/pageSize), the format of the result list, or any side effects. Returns are not described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no fluff. It front-loads the action and resource. However, it could be slightly expanded to include key behavioral notes without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, no annotations, and 3 parameters. The description is minimal and does not explain return format, pagination behavior, or how filtering affects results. For a list tool, more context (e.g., 'returns paginated list of category objects sorted by...') is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explicitly mentioning 'filtering support', which hints at the filter parameter. For a complete schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'categories', and mentions filtering support. It distinguishes from siblings like 'get-category' (single item) and 'create-category' (creation). However, it could be more specific about the scope (e.g., 'all categories with optional filtering') to avoid ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'get-category' for a single category or 'list-charts' for a different resource. The description does not mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all objects for a specific category
| Name | Required | Description | Default |
|---|---|---|---|
| categoryId | Yes | Category ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It describes a read operation but provides no details about pagination, ordering, error handling, or any side effects. Minimal behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. However, it is under-specified for a list operation; a bit more detail could be added without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (1 param, no output schema, no annotations), the description is incomplete. It does not describe the output format, any default behavior, or what 'objects' refers to. A list operation typically needs to mention ordering, pagination, or scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter (categoryId). The description adds 'specific category' context, but the schema already says 'Category ID'. Little additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all objects') and the resource ('for a specific category'). It distinguishes itself from sibling tools like 'list-categories' (which lists categories) and 'list-charts' (which lists charts) by specifying 'objects' and requiring a categoryId.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when one needs objects for a specific category, but it does not explicitly state when to use this tool over alternatives (e.g., list-categories or list-charts). No guidance on prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all charts with filtering support
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Filter criteria in the format 'fieldName(operator)=value'. Multiple filters can be combined with & (e.g., 'description(like)=revenue&categoryId(eq)=5'). Available operators: eq, ne, gt, lt, ge, le, like, nlike. Use get-filterable-attributes tool to see available fields. | |
| page | No | Page number for pagination | |
| pageSize | No | Number of items per page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks any behavioral disclosure beyond the basic operation. No annotations are present, so the description should inform about read-only status, side effects, or auth requirements. It does not, leaving the agent without crucial safety context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it lacks important details such as usage context or behavioral notes. It earns its place minimally but could be more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description should provide more context about return format, pagination behavior, or filtering instructions. It only covers the basic purpose, leaving significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the input schema already documents all three parameters. The description adds no extra meaning about parameter usage or constraints beyond what is in the schema, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and resource 'charts', and implies filtering support. It distinguishes from sibling tools like get-chart (single chart) and export-chart. However, it does not specify scope (e.g., 'all charts in the organization'), leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get-chart or export-chart. The description does not mention prerequisites, authentication needs, or scenarios where filtering or pagination is useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Invalidate the current token and end the session
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions token invalidation and session end, indicating destructive behavior. No annotations provided, so description carries the burden; could be more detailed about effects or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise, and front-loaded with essential information. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters or output schema, the description is adequate. It could mention if authentication is required or the return value, but it's reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters are defined in the schema, so the description does not need to add parameter information. Baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool invalidates the current token and ends the session, which is a specific action. It is distinct from sibling tools like authenticate or keep-session-alive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or alternatives. Context implies it's the opposite of authenticate and keep-session-alive, but no direct statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the API base URL for all requests
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | API base URL (e.g., http://localhost:8224/pi/api/v2) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description implies a global configuration effect but does not disclose persistence, session scope, or side effects. No annotations to supplement behavioral info.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence directly states the tool's function with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter with one required parameter and no output, the description fully addresses the context. No additional complexity requires elaboration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with a clear description including example. Description adds no significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (Set) and resource (API base URL), with global scope implied by 'for all requests'. No sibling tool sets URLs, so it's distinctive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use or not use this tool. No mention of prerequisites, order of operations, or alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the organization ID for subsequent requests
| Name | Required | Description | Default |
|---|---|---|---|
| orgId | Yes | Organization ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only states it sets the organization ID, omitting details like side effects, persistence, or scope of effect (e.g., session lifetime).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that efficiently communicates the tool's purpose with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter with one parameter and no output schema, the description is largely complete, though it could mention behavior like overwriting previous values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for orgId, but the tool description adds no additional meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (set) and specific resource (organization ID), distinguishing it from sibling tools like authentication or data operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for subsequent requests' implies it should be called early, but no explicit guidance on when to use versus alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing category
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Category ID | |
| description | No | Unique name of a category | |
| label | No | Alternative text for the category | |
| helpText | No | Help text to describe the category | |
| categoryObjectsPosition | No | Position of category objects panel | |
| cascadeFilters | No | Enable cascading filters |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral context. It only says 'update an existing category' without mentioning side effects, idempotency, permissions, or validation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded and to the point, but could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters (including an enum), no output schema, and no annotations, the description is too sparse. It does not explain partial updates, required fields behavior, or response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all parameters documented in schema), so baseline is 3. The description adds no further semantic value beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update) and resource (existing category), distinguishing it from siblings like create-category or delete-category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like create-category or get-category, nor any prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0authenticate1 field changedInput schema / additionalPropertiesRemoved value: -falsecheck-connection1 field changedInput schema / additionalPropertiesRemoved value: -falselogout1 field changedInput schema / additionalPropertiesRemoved value: -falseauthenticateauthenticate-with-credentialscheck-connectioncreate-categorydelete-categorydelete-chartexport-chartget-categoryget-chartget-filterable-attributeskeep-session-alivelist-categorieslist-category-objectslist-chartslogoutset-api-urlset-organizationupdate-categoryScored across 18 tools
All 18 tools have clearly distinct purposes. Authentication tools (authenticate, authenticate-with-credentials, check-connection, keep-session-alive, logout) each serve a unique role, and the CRUD tools for categories and charts are well-separated. There is no ambiguity between any pair.
All tool names follow a consistent lowercase-with-hyphens pattern, with verb-noun structure (e.g., create-category, list-charts). Minor exceptions like 'authenticate' (single verb) still fit the pattern, and there is no mixing of conventions.
18 tools is a well-scoped number for a PI API server covering authentication, configuration, category management, and chart operations. It is neither too sparse nor overwhelming, providing a focused yet comprehensive surface.
The tool set includes full CRUD for categories (create, read, update, delete) but only read, delete, and export for charts, missing create and update. This is a notable gap that could hinder agent workflows involving chart lifecycle management.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
