Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Pocketsmith MCP Server How much have I spent on groceries so far this month?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A comprehensive Model Context Protocol (MCP) server for the Pocketsmith personal finance API. Transform your AI assistant into a powerful financial management tool with access to accounts, budgets, transactions, and more.
Personal project — not published to PyPI. Install from source (see below).
View all account balances (checking, savings, credit cards, investments)
Get detailed account information with transaction history
Track net worth across multiple accounts
Get budget summaries for any time period
Analyze per-category spending vs. budgets
View spending trends across categories
Compare actual vs. forecasted amounts
List, search, and filter transactions
Create new transactions (log cash purchases, manual entries)
Update transaction details (categorize, add notes, set labels)
Delete duplicate or incorrect transactions
Filter by account, category, date range, or review status
List all categories with hierarchical structure
Create new categories and subcategories
Set up automatic categorization rules
Organize spending into custom categories
View upcoming bills and recurring expenses
Create recurring events (rent, subscriptions, paychecks)
Forecast future cash flow
Manage budget scenarios
List and manage transaction labels
Tag transactions for easy filtering
Track tax-deductible expenses, business spending, etc.
Related MCP server: YNAB Assistant
git clone https://github.com/dannyshaw/pocketsmith-mcp.git
cd pocketsmith-mcp
pip install -e .Or run directly with uv from the source directory (no install needed) — configure your MCP client to invoke:
uv --directory /path/to/pocketsmith-mcp run pocketsmith-mcpLog in to Pocketsmith
Go to Settings → API & Developers
Click Generate New API Key
Copy your API key
⚠️ Security: Treat your API key like a password. It has full access to your financial data.
export POCKETSMITH_API_KEY=your_api_key_hereOr create a .env file:
echo "POCKETSMITH_API_KEY=your_api_key_here" > .envAdd to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"pocketsmith": {
"command": "uvx",
"args": ["pocketsmith-mcp"],
"env": {
"POCKETSMITH_API_KEY": "your_api_key_here"
}
}
}
}Add to ~/.claude/claude_desktop_config.json:
{
"mcpServers": {
"pocketsmith": {
"command": "pocketsmith-mcp",
"env": {
"POCKETSMITH_API_KEY": "your_api_key_here"
}
}
}
}Run the server directly:
pocketsmith-mcpOnce configured, you can ask your AI assistant:
"What are my account balances?"
"Show me my credit card balance"
"Am I over budget this month?"
"What's my spending trend for groceries over the last 3 months?"
"List transactions from my checking account this week"
"Log a $50 cash purchase at the grocery store"
"Categorize that Amazon transaction as Household"
"Delete transaction #12345"
"What bills are coming up this month?"
"Create a recurring monthly rent payment of $2000"
"Show me all my subscriptions"
"Create a new category called 'Pet Expenses'"
"Show me all transactions in the Dining Out category"
"Set up a rule to auto-categorize Starbucks as Coffee"
Tool | Description |
| List all accounts with balances |
| Get detailed account information |
| List transaction accounts with details |
Tool | Description |
| Get budget summary for a date range |
| Per-category budget analysis |
| Spending trends across categories |
Tool | Description |
| List transactions with filters |
| Filter transactions by account |
| Filter transactions by category |
| Get transaction details |
| Create new transaction |
| Update transaction details |
| Delete a transaction |
| Search by keyword |
| Quick categorization |
Tool | Description |
| List all categories |
| Create new category |
| List auto-categorization rules |
| Create categorization rule |
Tool | Description |
| List recurring transactions |
| Create recurring transaction |
Tool | Description |
| List all transaction labels |
| Check connection status |
✅ Read all your financial data (transactions, accounts, balances)
✅ Create, update, and delete transactions
✅ Modify categories and create rules
✅ Access budget and forecast data
✅ Store API keys in environment variables (never in code)
✅ Use different API keys for development vs. production
✅ Rotate API keys periodically
✅ Only use with trusted AI assistants on secure machines
❌ Never commit API keys to version control
❌ Never share API keys publicly
See SECURITY.md for detailed security information.
20 out of 44 Pocketsmith API endpoints (45%)
Focused on the most useful endpoints for personal finance management:
✅ User & account management
✅ Transaction CRUD operations
✅ Budget & trend analysis
✅ Category management
✅ Recurring events/bills
✅ Labels & organization
# Clone repository
git clone https://github.com/dannyshaw/pocketsmith-mcp.git
cd pocketsmith-mcp
# Install dependencies
uv sync
# Run tests
pytest
# Run tests with coverage
pytest --cov=src/pocketsmith_mcp
# Lint and format
ruff check .
ruff format .
# Type check
mypy src# Run all tests
pytest -v
# Run specific test file
pytest tests/test_client.py -v
# Run with coverage report
pytest --cov=src/pocketsmith_mcp --cov-report=htmlpocketsmith-mcp/
├── src/pocketsmith_mcp/
│ ├── __init__.py # Package initialization
│ ├── client.py # Pocketsmith API client
│ ├── config.py # Configuration settings
│ └── server.py # MCP server implementation
├── tests/
│ ├── conftest.py # Test fixtures
│ └── test_client.py # Client tests
├── pyproject.toml # Project configuration
├── README.md # This file
└── SECURITY.md # Security documentationContributions are welcome! Please:
Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Write tests for your changes
Ensure all tests pass (pytest)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
See CONTRIBUTING.md for detailed guidelines.
MIT License - see LICENSE for details.
Built with the Model Context Protocol
Powered by the Pocketsmith API
Designed for use with Claude
Issues: GitHub Issues
Security: See SECURITY.md
Discussions: GitHub Discussions
Future enhancements:
Attachment management
Institution connections management
Budget calendar export
Spending analytics and insights
Multi-currency support enhancements
Batch transaction operations
Made with ❤️ for personal finance management
Categorize a transaction by setting its category. This is a convenience wrapper around update_transaction.
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes | The transaction ID to categorize | |
| category_id | Yes | The category ID to assign | |
| note | No | Optional note explaining the categorization | |
| mark_reviewed | No | Whether to mark the transaction as reviewed (default true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It states it is a convenience wrapper, implying no unexpected side effects, but it does not detail defaults (e.g., mark_reviewed defaults to true) or clarify if any permissions are needed. Adequate but not thorough.
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: two sentences that convey purpose and relationship to sibling. No redundant or extraneous 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?
Given the lack of output schema and annotations, the description provides sufficient context for a simple wrapper tool. It explains the purpose and references update_transaction, giving the agent enough to understand its role among many siblings. Missing some behavioral details but overall 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?
The input schema has 100% coverage with descriptions for all parameters. The description adds no additional semantics beyond the schema, which is acceptable per guidelines. 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 clearly states the tool's purpose: 'Categorize a transaction by setting its category.' It distinguishes itself from siblings by explicitly noting it is a convenience wrapper around update_transaction, making its specific use case obvious.
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 indicates when to use this tool (for categorization) by positioning it as a wrapper for update_transaction. However, it does not provide explicit guidance on when not to use it or mention alternatives beyond the implied update_transaction.
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 |
|---|---|---|---|
| title | Yes | The category title | |
| colour | No | The category color in hex format (e.g., #FF0000) | |
| parent_id | No | Parent category ID for creating a subcategory | |
| is_transfer | No | Whether this category represents a transfer | |
| is_bill | No | Whether this category represents a bill | |
| roll_up | No | Whether to roll up child categories | |
| refund_behaviour | No | How refunds should be handled |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for disclosing behavioral traits. It only states 'Create a new category' without any details on side effects, authentication needs, idempotency, or error behavior. This is a significant gap.
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 (one sentence), but this brevity sacrifices necessary information. It is under-specified for a tool with multiple parameters and no annotations, making it insufficient rather than appropriately concise.
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 complexity (7 parameters, no output schema, no annotations), the description is severely lacking. It omits return values, error scenarios, and behavioral constraints, leaving the agent with minimal context for correct usage.
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 of its 7 parameters with descriptions. The description adds no additional meaning beyond the schema, so the baseline score of 3 applies. No extra context is provided for parameter usage.
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 verb (create) and resource (category). It is straightforward and adequately conveys the main action, though it does not differentiate from sibling tools like 'pocketsmith_create_category_rule'.
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 'pocketsmith_list_categories' or 'pocketsmith_create_category_rule'. There is no mention of prerequisites, context, 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 rule to automatically categorize future transactions matching a payee pattern
| Name | Required | Description | Default |
|---|---|---|---|
| category_id | Yes | The category ID to assign when rule matches | |
| payee_matches | Yes | Keyword pattern to match in payee field | |
| apply_to_uncategorised | No | Apply this rule to existing uncategorised transactions | |
| apply_to_all | No | Apply this rule to ALL existing transactions (re-categorizes) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It states the rule applies to 'future transactions' but the schema includes parameters 'apply_to_uncategorised' and 'apply_to_all' that affect existing transactions, creating a potentially misleading omission. The description fails to disclose the destructive impact of re-categorizing existing transactions.
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 filler. Every word contributes to the core purpose, making it highly scannable for an AI agent.
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 has 4 parameters (2 required) and no output schema, the description is insufficient. It does not explain what a category rule is, how the matching works, or the implications of the apply_to parameters. With siblings like 'list_category_rules', the description should provide more context about the rule lifecycle.
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 baseline is 3. The description adds minimal value beyond the schema, only clarifying 'future transactions' which is not entirely accurate given the apply_to parameters. No additional parameter details or usage examples are 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 verb 'Create', the resource 'category rule', and the purpose 'automatically categorize future transactions matching a payee pattern'. It effectively distinguishes from sibling tools like 'categorize_transaction' (one-time) and other creation 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 description implies use when setting up recurring categorization but provides no explicit guidance on when to use versus alternatives, nor does it offer exclusion criteria or mention prerequisites. It is adequate but lacks directive clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new event (recurring transaction)
| Name | Required | Description | Default |
|---|---|---|---|
| scenario_id | Yes | The scenario ID (get from account details) | |
| category_id | Yes | The category ID to assign | |
| date | Yes | The event date (YYYY-MM-DD) | |
| amount | Yes | The event amount (negative for expenses, positive for income) | |
| repeat_type | Yes | How often the event repeats | |
| repeat_interval | No | The repeat interval (default: 1) | |
| note | No | Note for the event |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as whether the event automatically generates transactions, any side effects, permission requirements, or what happens upon creation. The single sentence lacks depth beyond the action itself.
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. However, it sacrifices completeness; a slightly longer description could improve clarity 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 tool creates events (recurring transactions) and has no output schema or annotations, the description is incomplete. It does not explain what the tool returns, how events are used, or any prerequisites (e.g., scenario must exist). More context is needed for effective agent usage.
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 inline descriptions for all 7 parameters. The description adds no additional meaning or context beyond what the schema provides. Baseline of 3 is appropriate as the schema handles semantics adequately.
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 event (recurring transaction)' uses a specific verb (create) and resource (event), and immediately clarifies that events represent recurring transactions. This distinguishes it from siblings like pocketsmith_create_transaction, making purpose clear.
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 that this tool is for creating recurring transactions, but it provides no explicit guidance on when to use this versus alternatives (e.g., when to use create_transaction for one-off transactions or list_events for viewing). The context is inferential but not directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new transaction
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_account_id | Yes | The transaction account ID | |
| payee | Yes | The payee name | |
| amount | Yes | The transaction amount (negative for debit, positive for credit) | |
| date | Yes | The transaction date (YYYY-MM-DD) | |
| is_transfer | No | Whether this is a transfer between accounts | |
| labels | No | Labels to assign to the transaction | |
| category_id | No | Category ID to assign | |
| note | No | Note for the transaction | |
| memo | No | Memo for the transaction | |
| needs_review | No | Whether the transaction needs review |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description fails to disclose behavioral traits like mutation effects, idempotency, or confirmation steps, leaving the agent without crucial safety information.
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 concise with a single, clear sentence, but could benefit from a brief structure like listing key intended use cases 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 tool has 10 parameters and no output schema, the description is too sparse, failing to explain return behavior, constraints, or post-creation effects, which are necessary for 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?
The input schema has 100% parameter description coverage, so the description adds no additional meaning. Baseline score of 3 is appropriate as the schema already provides detailed parameter semantics.
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 transaction' clearly states the verb (create) and resource (transaction), but lacks differentiation from sibling tools like 'pocketsmith_update_transaction' or 'pocketsmith_categorize_transaction'.
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 when a transaction should be created vs updated or categorized.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a transaction by ID
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes | The transaction ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the sole source of behavioral information. It states the action is deletion, implying mutation and destruction, but does not disclose potential consequences (e.g., irreversibility, cascading effects) or required authentication/authorization 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, concise sentence with no extraneous information, making it highly efficient for an agent to process.
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 mutation tool with no output schema and no annotations, the description is insufficient. It does not mention return values (e.g., success indicator, deleted object), error conditions (e.g., transaction not found), or any post-deletion state, leaving the agent with incomplete context.
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 parameter description already explaining its role. The description adds 'by ID' which reinforces the parameter's function but does not provide 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 'Delete a transaction by ID' clearly states the verb (delete), resource (transaction), and identification method (by ID). It effectively distinguishes from sibling tools like create, update, or categorize.
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. It does not specify prerequisites, such as transaction existence or user permissions, nor does it mention any context where deletion is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific account by ID
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | Yes | The account ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose behavior such as read-only nature, error handling, or any side effects.
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, efficiently conveys core purpose without redundancy.
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 no output schema, description could detail expected return data or behavior, but for a simple retrieval tool 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% and schema already documents the parameter; description adds no additional meaning beyond confirming it's used for identification.
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 details of a specific account by ID, distinguishing it from listing tools like pocketsmith_list_accounts.
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, nor any preconditions or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get budget summary for a period and date range
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | The period for the budget summary (default: months) | |
| interval | No | The interval for the period (default: 1) | |
| start_date | Yes | Start date for the budget summary (YYYY-MM-DD) | |
| end_date | Yes | End date for the budget summary (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral transparency. It does not disclose whether the operation is read-only, any authentication requirements, error conditions, or the nature of the response.
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 that is front-loaded with the key action and resource. Every word serves a purpose, though it could benefit from more structure (e.g., bullet points).
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 lacks an output schema and annotations, and the description does not explain what the summary contains, how it is aggregated, or any pagination. Given sibling tools, the description is insufficient for an agent to understand the full context.
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% description coverage for all four parameters, including enums and date format hints. The description adds no additional semantic value 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 tool retrieves a budget summary for a period and date range, using a specific verb and resource. However, it does not differentiate from sibling tools like pocketsmith_list_budget, which may serve a similar function.
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 pocketsmith_list_budget or pocketsmith_get_trend_analysis. There is no mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get connection status and authenticated user info
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description should disclose behavioral traits. It only states what the tool gets, but does not mention that it is read-only, requires authentication, or any side effects. The description fails to add value beyond the purpose.
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, clear sentence with no unnecessary words. It is appropriately sized for the tool's simplicity.
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, yet the description does not describe the return format or fields. It only mentions 'connection status and authenticated user info' without elaboration. Given the low complexity, the description is incomplete.
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?
There are no parameters, so the schema coverage is 100% trivial. The description does not need to explain parameters. Baseline for 0 params 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's action ('get') and the resource ('connection status and authenticated user info'). It is specific and distinct from sibling tools, which are all about specific operations like categorize, create, list, etc.
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 others, or any preconditions. For a simple status check, the usage might be obvious, but the description lacks any contextual hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific transaction by ID
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes | The transaction ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the full burden. It only states 'Get details' (a read operation) but omits any behavioral traits such as rate limits, authentication requirements, error handling (e.g., behavior for invalid/missing ID), or what 'details' precisely includes.
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 short sentence with no extraneous words. It is concise but could slightly expand on the output format 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 no output schema, the description should indicate what 'details' are returned (e.g., full transaction object, specific fields). It lacks this information, making the tool incomplete for an agent to understand the return structure.
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% and the parameter description is minimal ('The transaction ID'). The tool description adds no additional meaning beyond the schema, meeting the baseline of 3.
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 ('Get details') and the target resource ('a specific transaction by ID'). It effectively distinguishes this tool from siblings like 'pocketsmith_list_transactions' and 'pocketsmith_search_transactions' by specifying retrieval by individual ID.
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 listing or searching. It implicitly assumes the agent already has a transaction ID but does not explain the prerequisite or contrast with bulk operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get trend analysis across categories and scenarios
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | The period for trend analysis (default: months) | |
| interval | No | The interval for the period (default: 1) | |
| start_date | Yes | Start date for trend analysis (YYYY-MM-DD) | |
| end_date | Yes | End date for trend analysis (YYYY-MM-DD) | |
| categories | No | Category IDs to filter by | |
| scenarios | No | Scenario IDs to filter by |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose behavioral traits (e.g., read-only, data aggregation method, or limits), leaving agents uninformed about side effects or constraints.
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 and front-loaded, but could be expanded with minimal context without sacrificing brevity.
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?
No output schema and no annotations; description fails to explain return format, aggregation logic, or usage context, leaving significant gaps for effective tool invocation.
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 all 6 parameters with descriptions; the tool description adds no extra meaning beyond the schema, meeting the baseline for high coverage.
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 trend analysis across categories and scenarios, distinguishing it from sibling tools focused on transactions, accounts, and budgets.
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 list_transactions or budget_summary; lacks context for preferred use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all accounts with balances and details
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description does not disclose any behavioral traits such as read-only nature, authentication requirements, rate limits, or response structure. The lack of transparency leaves the agent uncertain about side effects or limitations.
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 purpose with no extra words. It is appropriately front-loaded.
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 that there is no output schema and no annotations, the description could provide more context such as the scope of 'all accounts' (organization-wide?), whether it includes closed accounts, or any limitations. However, for a simple list with no parameters, the description 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?
The input schema has zero parameters, so schema coverage is 100%. The description does not need to add parameter information since there are none. This 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 uses a specific verb 'List' and clearly states the resource 'accounts', specifying it includes 'balances and details'. Among sibling tools, there is no other tool dedicated to listing all accounts, so this tool is clearly distinguished.
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 usage guidelines are provided. There is no indication of when to use this tool versus alternatives like get_account or list_transaction_accounts. The description does not mention 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.
List per-category budget analysis
| Name | Required | Description | Default |
|---|---|---|---|
| roll_up | No | Whether to roll up child categories into parent categories |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behaviors. It does not state whether the tool returns only categories with budgets, the format of the analysis (e.g., spent vs budgeted), or any limitations. The description is too minimal.
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 extraneous words. It is appropriately sized 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?
With no output schema and no annotations, the description should provide more context about what the tool returns. It lacks details on the structure of the analysis, which is critical for an AI agent to interpret results.
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%, and the single parameter 'roll_up' is already described in the schema. The description adds no additional meaning beyond the schema, so 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 'List per-category budget analysis' clearly states the action and resource. It distinguishes from sibling 'pocketsmith_get_budget_summary' which implies a summary view. However, 'budget analysis' is somewhat vague and could be more specific.
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 'pocketsmith_get_budget_summary' or others. The description does not mention prerequisites or context, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all categories. Returns a flat list with full category paths for easy lookup.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only mentions the return format (flat list with paths) but does not disclose whether the operation is read-only, requires authentication, or has any side effects. Minimal behavioral 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 consists of two concise sentences. The first sentence states the action ('List all categories') and the second adds return value detail. No extraneous words, front-loaded with the core 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 list-all tool with no parameters and no output schema, the description is complete: it states what it does and what it returns. It may not mention edge cases or permissions, but given the simplicity, it provides sufficient context for 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?
The tool has zero parameters, and the input schema is empty with 100% coverage. The description does not need to explain parameters. According to guidelines, baseline for 0 params is 4, and the description adds no param info, so a 4 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 uses specific verb 'List' and resource 'categories', and clarifies it returns 'all categories' with 'full category paths'. This clearly distinguishes from sibling tools like pocketsmith_create_category or pocketsmith_list_category_rules.
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 for retrieving all categories but provides no explicit guidance on when to use this tool vs alternatives, such as when to use pocketsmith_list_category_rules or pocketsmith_get_category. 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.
List all category rules (automatic categorization rules)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description provides only the basic behavior (lists all rules) and adds context about automatic categorization. Lacks disclosure on read-only nature, permissions, or rate limits, but sufficient for a simple list operation.
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 front-loads the purpose with no extraneous text. 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?
For a zero-parameter list tool with no output schema, description adequately explains the resource. Could mention that no filtering is available, but overall complete enough for the tool's simplicity.
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 exist; schema coverage is trivially 100%. Description adds meaning by defining what 'category rules' are (automatic categorization rules), satisfying the baseline of 4 for zero-parameter tools.
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 uses specific verb 'List' and resource 'category rules' with parenthetical clarification 'automatic categorization rules', clearly distinguishing it from siblings like list_categories which list categories themselves.
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 such as list_categories, list_events, etc. Agent must infer based solely on the name, which may be ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List events (recurring transactions) for a date range
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | Start date for events (YYYY-MM-DD) | |
| end_date | Yes | End date for events (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description gives only the read action (list) without additional behavioral details such as pagination, ordering, permissions, or side effects.
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 that includes both verb and resource with clarification. 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?
No output schema and no annotations; description does not explain return format, pagination, or expected response, leaving the agent without sufficient context for a read 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?
Schema coverage is 100% with clear parameter descriptions. Description adds no extra meaning beyond schema, so 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?
Description clearly states verb 'list' and resource 'events' with parenthetical clarification 'recurring transactions', distinct from sibling tools like pocketsmith_list_transactions.
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 siblings like pocketsmith_list_transactions or pocketsmith_list_accounts. The description simply states functionality without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all labels used in transactions
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description lacks behavioral traits such as read-only safety, pagination, or permissions. Minimal disclosure for a simple list operation.
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 redundancy, front-loaded verb and resource. 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?
Adequate for a 0-param, no-output-schema tool. Could mention scope (e.g., 'all labels from all transactions') but current wording is sufficient.
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, so schema coverage is 100%. Baseline 4 per rule; description adds no param info, but not required.
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?
Specifies verb 'List' and resource 'labels used in transactions'. Clearly distinguishes from siblings like list_accounts and list_categories by focusing on labels.
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 vs alternatives (e.g., list_categories). Does not mention prerequisites or context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all transaction accounts with balances and details
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states 'list' suggesting non-destructive, but lacks details on pagination, rate limits, or behavior when no accounts exist.
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, front-loaded, no filler. Every word adds value.
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?
No output schema or annotations. Description is minimal for a list tool; 'details' is vague. Adequate but leaves agent wondering what fields are returned.
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 exist; schema coverage is 100%. Baseline for zero parameters is 4, and description adds no parameter info because none needed.
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 clearly states specific verb 'List' and resource 'transaction accounts' with scope 'all' and expected content 'balances and details'. It effectively distinguishes from sibling tools like pocketsmith_list_accounts which likely lists all account types.
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 vs. alternatives. The description implies a read operation but does not state when not to use or provide comparisons to similar list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List transactions from Pocketsmith with optional filters. Transfers excluded by default.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | Filter transactions on or after this date (YYYY-MM-DD) | |
| end_date | No | Filter transactions on or before this date (YYYY-MM-DD) | |
| needs_review | No | Filter to transactions that need review | |
| uncategorised | No | Filter to uncategorised transactions | |
| search | No | Search string to match against payee, category, notes, etc. | |
| transaction_type | No | Filter by transaction type | |
| limit | No | Maximum number of transactions to return (default 100) | |
| exclude_transfers | No | Exclude transfer transactions (default true) | |
| exclude_zero | No | Exclude zero-amount transactions (default true) | |
| exclude_category_ids | No | Category IDs to exclude from results |
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 only states the basic function and a default behavior (excluding transfers) but does not disclose any other behavioral traits such as rate limits, idempotency, or output format expectations.
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 two sentences, concise and front-loaded with the main purpose. Every sentence adds value; there is no unnecessary text.
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 parameter count (10, all optional), the lack of an output schema, and the simplicity of the tool, the description provides adequate context for an agent to understand the basic functionality. However, more details about default behaviors or how the filters interact could be beneficial.
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 each parameter described in the schema. The description adds no additional semantics beyond the schema, so a 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 clearly states it lists transactions with optional filters and notes the default exclusion of transfers, providing a clear purpose. However, it does not explicitly differentiate from sibling tools like 'pocketsmith_list_transactions_by_account' or 'pocketsmith_search_transactions'.
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 for fetching transaction data with filters, but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., by account, by category, or search). No exclusions or contexts are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List transactions for a specific account with optional filters. Transfers excluded by default.
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | Yes | The account ID to filter by | |
| start_date | No | Filter transactions on or after this date (YYYY-MM-DD) | |
| end_date | No | Filter transactions on or before this date (YYYY-MM-DD) | |
| needs_review | No | Filter to transactions that need review | |
| uncategorised | No | Filter to uncategorised transactions | |
| search | No | Search string to match against transaction fields | |
| transaction_type | No | Filter by transaction type | |
| exclude_transfers | No | Exclude transfer transactions (default true) | |
| exclude_zero | No | Exclude zero-amount transactions (default true) | |
| exclude_category_ids | No | Category IDs to exclude from results |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description reveals that transfers are excluded by default and filters are available, but lacks details on pagination, result ordering, or read-only nature.
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 two concise sentences with no unnecessary words, front-loading the core action and key behavioral note.
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 10 parameters, no output schema, and no annotations, the description covers the basic filter options and default behavior but omits important context like pagination, error handling, or result 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?
All 10 parameters have schema descriptions (100% coverage), so the description adds little beyond highlighting the default exclusion of transfers; no additional syntactic or semantic detail 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 verb 'List' and the resource 'transactions for a specific account', and distinguishes from siblings by specifying account-level filtering and default transfer exclusion.
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 indicates the tool is for listing transactions for a specific account, but it does not provide explicit guidance on when to use this tool over alternatives like pocketsmith_list_transactions_by_category or pocketsmith_search_transactions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List transactions for one or more categories. Transfers excluded by default.
| Name | Required | Description | Default |
|---|---|---|---|
| category_ids | Yes | Category IDs to filter by | |
| start_date | No | Filter transactions on or after this date (YYYY-MM-DD) | |
| end_date | No | Filter transactions on or before this date (YYYY-MM-DD) | |
| needs_review | No | Filter to transactions that need review | |
| uncategorised | No | Filter to uncategorised transactions | |
| search | No | Search string to match against transaction fields | |
| transaction_type | No | Filter by transaction type | |
| exclude_transfers | No | Exclude transfer transactions (default true) | |
| exclude_zero | No | Exclude zero-amount transactions (default true) | |
| exclude_category_ids | No | Category IDs to exclude from results |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that transfers are excluded by default, but lacks details on pagination, rate limits, authorization, or what happens with no results. No annotations exist to compensate, so description carries the burden and falls short.
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?
Two sentences efficiently convey the core purpose and a key default. No wasted words, though a bit more context could be added without harming 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?
For a tool with 10 parameters and many sibling tools, the description is too sparse. It does not explain the response format, the interplay of filters, or how it differs from other list/search tools. Lacks completeness for effective selection.
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% with all parameters described. The tool description adds no additional meaning beyond the schema, so 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?
Clearly states 'List transactions for one or more categories' with a specific verb and resource, and notes a default behavior (transfers excluded). Distinguished from sibling tools like pocketsmith_list_transactions and pocketsmith_list_transactions_by_account.
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?
Implies usage for category-based filtering but provides no explicit guidance on when to use this tool versus alternatives like pocketsmith_search_transactions or pocketsmith_list_transactions_by_account. No exclusions or mentions of 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.
Search transactions by keyword (payee, category, notes). Transfers excluded by default.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query to match against transaction fields | |
| limit | No | Maximum number of transactions to return (default 50) | |
| exclude_transfers | No | Exclude transfer transactions (default true) | |
| exclude_zero | No | Exclude zero-amount transactions (default true) | |
| exclude_category_ids | No | Category IDs to exclude from results |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It mentions default exclusions but lacks details on pagination, read-only nature, search semantics (case sensitivity, fuzzy matching), or rate limits.
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?
Two concise sentences, front-loaded with purpose. Every word adds value without redundancy.
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 5 parameters, no output schema, and no annotations, the description covers search scope and defaults but omits return format, pagination details, and search behavior nuances (e.g., case sensitivity). Adequate but not thorough.
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 good parameter descriptions. The tool description adds context by specifying which fields are searched (payee, category, notes) and default behavior for exclusions, enhancing understanding 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 tool searches transactions by keyword across specific fields (payee, category, notes) and notes default exclusion of transfers, distinguishing it from list-only or mutation 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 description implies usage (searching) but does not explicitly state when to use vs. alternatives like pocketsmith_list_transactions, nor does it mention when transfers are excluded or how to include them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a transaction's category, payee, note, labels, or review status
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes | The transaction ID to update | |
| category_id | No | New category ID to assign | |
| payee | No | New payee name | |
| note | No | New note/memo for the transaction | |
| labels | No | New labels to assign | |
| needs_review | No | Set whether transaction needs review |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for disclosing behavior. It states 'Update' but does not specify whether this is a partial update or full replacement, whether it returns the updated transaction, if it requires special permissions, or if the operation is reversible.
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 lists the key fields. It is concise and front-loaded, though it could be slightly more structured (e.g., bullet points) but remains 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?
Given 6 parameters, no output schema, and no annotations, the description is incomplete. It does not explain the update behavior (partial vs full), return format, or potential side effects. The agent is left guessing about important operational details.
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% description coverage, so the baseline is 3. The description enumerates the parameters but adds no extra meaning beyond the schema descriptions; it does not clarify format constraints or relationships between parameters.
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 uses the specific verb 'Update' and resource 'transaction', and lists the exact fields that can be modified (category, payee, note, labels, review status). This clearly differentiates it from siblings like 'pocketsmith_categorize_transaction' which likely only changes the 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 such as 'pocketsmith_categorize_transaction' or 'pocketsmith_delete_transaction'. There is no mention of prerequisites, side effects, or scenarios where updating is appropriate.
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.
pocketsmith_list_transactions3 fields changedInput schema / properties / exclude_category_idsAdded value: +{
+ "description": "Category IDs to exclude from results",
+ "items": {
+ "type": "integer"
+ },
+ "type": "array"
+}Input schema / properties / exclude_transfersAdded value: +{
+ "description": "Exclude transfer transactions (default true)",
+ "type": "boolean"
+}Input schema / properties / exclude_zeroAdded value: +{
+ "description": "Exclude zero-amount transactions (default true)",
+ "type": "boolean"
+}pocketsmith_list_transactions_by_account3 fields changedInput schema / properties / exclude_category_idsAdded value: +{
+ "description": "Category IDs to exclude from results",
+ "items": {
+ "type": "integer"
+ },
+ "type": "array"
+}Input schema / properties / exclude_transfersAdded value: +{
+ "description": "Exclude transfer transactions (default true)",
+ "type": "boolean"
+}Input schema / properties / exclude_zeroAdded value: +{
+ "description": "Exclude zero-amount transactions (default true)",
+ "type": "boolean"
+}pocketsmith_list_transactions_by_category3 fields changedInput schema / properties / exclude_category_idsAdded value: +{
+ "description": "Category IDs to exclude from results",
+ "items": {
+ "type": "integer"
+ },
+ "type": "array"
+}Input schema / properties / exclude_transfersAdded value: +{
+ "description": "Exclude transfer transactions (default true)",
+ "type": "boolean"
+}Input schema / properties / exclude_zeroAdded value: +{
+ "description": "Exclude zero-amount transactions (default true)",
+ "type": "boolean"
+}pocketsmith_search_transactions3 fields changedInput schema / properties / exclude_category_idsAdded value: +{
+ "description": "Category IDs to exclude from results",
+ "items": {
+ "type": "integer"
+ },
+ "type": "array"
+}Input schema / properties / exclude_transfersAdded value: +{
+ "description": "Exclude transfer transactions (default true)",
+ "type": "boolean"
+}Input schema / properties / exclude_zeroAdded value: +{
+ "description": "Exclude zero-amount transactions (default true)",
+ "type": "boolean"
+}v0.1.0pocketsmith_categorize_transactionpocketsmith_create_categorypocketsmith_create_category_rulepocketsmith_create_eventpocketsmith_create_transactionpocketsmith_delete_transactionpocketsmith_get_accountpocketsmith_get_budget_summarypocketsmith_get_statuspocketsmith_get_transactionpocketsmith_get_trend_analysispocketsmith_list_accountspocketsmith_list_budgetpocketsmith_list_categoriespocketsmith_list_category_rulespocketsmith_list_eventspocketsmith_list_labelspocketsmith_list_transaction_accountspocketsmith_list_transactionspocketsmith_list_transactions_by_accountpocketsmith_list_transactions_by_categorypocketsmith_search_transactionspocketsmith_update_transactionScored across 23 tools
Each tool targets a specific resource and action (e.g., get, list, create, update, search) with no overlapping purposes. Even similar tools like list_transactions and list_transactions_by_account are clearly distinguished by scope.
All tools follow a consistent 'pocketsmith_verb_noun' pattern in snake_case, with verbs like get, list, create, update, delete, search, categorize. No mixing of styles.
23 tools is well-scoped for a personal finance management server covering accounts, transactions, categories, budgets, events, labels, trends, and status. Each tool serves a distinct purpose without redundancy.
The tool set covers core CRUD operations for transactions and basic operations for categories, events, and accounts. However, missing update/delete for categories and events are minor gaps that agents can work around.
Personal finance for AI agents: accounts, budgets, goals, 9-strategy debt payoff, reports. OAuth 2.1
Personal finance, bank account, and shared memory connector for Claude, ChatGPT, Gemini Spark & more
Personal-finance workspace for AI agents: accounts, spending, budgets, goals, and investments.
Personal finance ledger for AI agents — query spending, track bills, forecast cash flow.
