The Sharesight MCP Server enables AI assistants to interact with Sharesight portfolio tracking data through 27 tools covering portfolio management, holdings, custom investments, performance analysis, and account settings.
Portfolio Management: List all portfolios with optional filtering or consolidation, get detailed portfolio information, view holdings within portfolios, and manage user display preferences (chart types, grouping, inclusion of sold shares).
Holdings Management: List all holdings across portfolios, retrieve detailed holding information with options for cost base, average purchase price, or historical values, update Dividend Reinvestment Plan (DRP) settings, and delete holdings.
Custom Investments: Create, read, update, and delete custom/unlisted investments (property, bonds, managed funds, etc.) with support for various investment types including ordinary shares and fixed interest instruments. Manage price history with date-specific pricing entries and handle coupon rates for fixed interest investments with full CRUD operations.
Performance Analysis: Generate detailed performance reports with gains analysis, holdings breakdown, and benchmarks. Retrieve performance index chart data for visualizing portfolio performance over time. Filter and group data by date ranges, country, currency, market, sector, industry, or custom groups.
Account Management: List supported countries and their settings, view, apply, and remove promotional coupon codes, and revoke API access to invalidate all associated tokens.
Authentication: Uses OAuth 2.0 with automatic token refresh and secure local token storage.
A Model Context Protocol (MCP) server that provides AI assistants with access to the Sharesight portfolio tracking platform via the v3 API.
You'll need a Client ID and Client Secret from Sharesight to use this server.
How to get credentials:
Contact Sharesight support at support@sharesight.com to request API access
Visit the Sharesight API documentation for more information
API access may require a specific Sharesight plan
npx github:Haizzz/sharesight-mcp authThe CLI will:
Prompt for your Client ID and Client Secret
Display a URL to open in your browser
Ask you to log in to Sharesight and authorize the app
Prompt you to paste the authorization code
Save tokens locally (they refresh automatically)
Add to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"sharesight": {
"command": "npx",
"args": ["-y", "github:Haizzz/sharesight-mcp", "serve"],
"env": {
"SHARESIGHT_CLIENT_ID": "your_client_id",
"SHARESIGHT_CLIENT_SECRET": "your_client_secret"
}
}
}
}Restart Claude Desktop and you're ready to go!
Related MCP server: Kuvera MCP
This MCP server enables Claude and other AI assistants to interact with Sharesight accounts, allowing natural language queries and operations on investment portfolios, holdings, custom investments, and performance reports.
Sharesight is a portfolio tracking platform that helps investors track their stocks, ETFs, mutual funds, and other investments across multiple markets. It provides performance reporting, dividend tracking, and tax reporting features.
The Model Context Protocol is an open standard that enables AI assistants to securely connect to external data sources and tools.
This server exposes 27 tools covering all Sharesight v3 API endpoints:
Tool | Description |
| List all user portfolios with optional consolidated view |
| Get detailed portfolio information by ID |
| List all holdings within a specific portfolio |
| Get user display preferences for a portfolio |
| Update chart type, grouping, and other display settings |
Tool | Description |
| List all holdings across all portfolios |
| Get holding details with optional cost base and historical values |
| Update holding settings (DRP configuration) |
| Remove a holding from a portfolio |
Tool | Description |
| List custom/unlisted investments |
| Get custom investment details |
| Create a new custom investment (property, bonds, etc.) |
| Update custom investment properties |
| Remove a custom investment |
Tool | Description |
| Get price history for a custom investment |
| Add a new price entry |
| Modify an existing price entry |
| Remove a price entry |
Tool | Description |
| List interest rates for fixed interest investments |
| Add a new coupon rate |
| Modify a coupon rate |
| Remove a coupon rate |
Tool | Description |
| Detailed performance breakdown with gains analysis |
| Chart data for visualizing portfolio performance |
Tool | Description |
| Get Sharesight-supported countries and their settings |
| View applied promotional coupon code |
| Apply a promotional coupon code |
| Remove applied coupon code |
| Disconnect API access (invalidates all tokens) |
git clone https://github.com/Haizzz/sharesight-mcp.git
cd sharesight-mcp
npm install
npm run buildThen run auth and configure:
node dist/index.js auth{
"mcpServers": {
"sharesight": {
"command": "node",
"args": ["/path/to/sharesight-mcp/dist/index.js", "serve"],
"env": {
"SHARESIGHT_CLIENT_ID": "your_client_id",
"SHARESIGHT_CLIENT_SECRET": "your_client_secret"
}
}
}
}OAuth tokens are stored at:
Linux/macOS: ~/.sharesight-mcp/tokens.json
Windows: %USERPROFILE%\.sharesight-mcp\tokens.json
Tokens refresh automatically. To re-authorize, delete the tokens file and run sharesight-mcp auth again.
Common errors:
401 - Invalid or expired access token
403 - Token revoked or insufficient permissions
404 - Resource not found
422 - Validation error (check field values)
npm run dev # Watch mode
npm run build # Build for production
npm start # Run the serverMIT
Sharesight Support: support@sharesight.com
API Documentation: https://api.sharesight.com/doc/api/v3
MCP Protocol: https://modelcontextprotocol.io/
Applies a coupon code to the current user
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The coupon code to apply |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'applies a coupon code' which implies a mutation, but doesn't disclose behavioral traits like whether it requires specific permissions, what happens on success/failure (e.g., error messages), rate limits, or if it's idempotent. For a mutation tool with zero annotation coverage, this is inadequate.
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 wasted words. It's front-loaded with the core action and resource, making it efficient and easy to parse. Every word earns its place, achieving optimal 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 this is a mutation tool with no annotations, no output schema, and incomplete behavioral disclosure, the description is insufficient. It doesn't explain what happens after application (e.g., success confirmation, error handling), leaving gaps in understanding the tool's full context and outcomes.
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, with the 'code' parameter documented as 'The coupon code to apply'. The description doesn't add any meaning beyond this (e.g., format examples or validation rules). With high schema coverage, the baseline is 3, and the description doesn't compensate further.
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 ('applies') and the resource ('a coupon code'), specifying it applies to 'the current user'. It distinguishes from siblings like 'create_coupon_rate' or 'show_coupon_code' by focusing on application rather than creation or retrieval. However, it doesn't explicitly differentiate from all siblings (e.g., 'delete_coupon_code'), keeping it at 4 instead of 5.
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 like 'create_coupon_rate' or 'show_coupon_code'. It mentions 'the current user' but doesn't specify prerequisites (e.g., user authentication) or exclusions (e.g., invalid codes). With no explicit when/when-not instructions, it scores 2.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a coupon rate for a custom investment
| Name | Required | Description | Default |
|---|---|---|---|
| instrument_id | Yes | The custom investment instrument ID | |
| interest_rate | Yes | The interest rate as a percentage | |
| date | Yes | The date from which the rate applies YYYY-MM-DD |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the action without behavioral details. It doesn't mention permissions required, whether the operation is idempotent, error conditions, or what happens on success (e.g., returns a coupon rate ID). This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly.
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 annotations and no output schema, the description is insufficient. It doesn't explain what the tool returns, error handling, or side effects, leaving the agent with incomplete operational context despite good schema coverage.
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 schema fully documents all three parameters. The description adds no additional meaning beyond what's in the schema, such as explaining relationships between parameters or constraints not captured in type/format.
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 ('Creates') and resource ('coupon rate for a custom investment'), providing a specific purpose. However, it doesn't differentiate from sibling tools like 'update_coupon_rate' or 'list_coupon_rates', which would require explicit comparison.
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 'update_coupon_rate' or 'list_coupon_rates'. The description lacks context about prerequisites, such as whether the custom investment must exist first, or when this operation is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a new custom investment
| Name | Required | Description | Default |
|---|---|---|---|
| portfolio_id | No | Portfolio ID (optional, links to owner if not provided) | |
| code | Yes | The investment code | |
| name | Yes | The name of the custom investment | |
| country_code | Yes | Country code (e.g., AU, NZ, US) | |
| investment_type | Yes | Type: ORDINARY, WARRANT, SHAREFUND, PROPFUND, PREFERENCE, STAPLEDSEC, OPTIONS, RIGHTS, MANAGED_FUND, FIXED_INTEREST, PIE | |
| face_value | No | Face value per unit (FIXED_INTEREST only) | |
| interest_rate | No | Initial interest rate (FIXED_INTEREST only) | |
| income_type | No | DIVIDEND or INTEREST (FIXED_INTEREST only) | |
| payment_frequency | No | ON_MATURITY, YEARLY, TWICE_YEARLY, QUARTERLY, MONTHLY (FIXED_INTEREST only) | |
| first_payment_date | No | First payment date YYYY-MM-DD (FIXED_INTEREST only) | |
| maturity_date | No | Maturity date YYYY-MM-DD (FIXED_INTEREST only) | |
| auto_calc_income | No | Auto-populate income payments (FIXED_INTEREST only) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'creates' which implies a write operation, but doesn't mention required permissions, whether it's idempotent, what happens on conflicts (e.g., duplicate codes), or the response format. For a 12-parameter creation tool, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste—'Creates a new custom investment' is front-loaded and appropriately sized for its purpose. Every word earns its place, making it easy to parse quickly.
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 complexity (12 parameters, no output schema, no annotations), the description is incomplete. It doesn't explain the tool's behavior, error conditions, or return values, leaving the agent to rely solely on the input schema. For a creation tool with many parameters, more context is needed to ensure 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?
Schema description coverage is 100%, so the schema fully documents all 12 parameters with clear descriptions and constraints (e.g., FIXED_INTEREST-only fields). The description adds no parameter information beyond what's in the schema, meeting the baseline of 3 for high schema coverage without extra value.
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 'Creates a new custom investment' clearly states the verb ('creates') and resource ('custom investment'), but it's vague about what constitutes a 'custom investment' and doesn't differentiate from siblings like 'create_custom_investment_price' or 'update_custom_investment'. It's adequate but lacks specificity about the investment creation scope.
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 like 'update_custom_investment' or 'list_custom_investments'. There's no mention of prerequisites, such as needing a portfolio context, or exclusions, leaving the agent to infer usage from the schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a price entry for a custom investment
| Name | Required | Description | Default |
|---|---|---|---|
| custom_investment_id | Yes | The custom investment ID | |
| last_traded_price | Yes | The price in instrument currency | |
| last_traded_on | Yes | The date YYYY-MM-DD |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'creates,' implying a write operation, but does not address critical aspects like required permissions, whether the operation is idempotent, error handling, or what happens on duplicate entries. This leaves significant gaps in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and efficiently conveys the core action, making it easy to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a creation tool with no annotations and no output schema, the description is insufficient. It lacks details on behavioral traits, error conditions, return values, and how it differs from sibling tools. This leaves the agent with incomplete information for proper invocation and error handling.
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%, meaning the input schema fully documents all three parameters with descriptions. The description does not add any additional meaning or context beyond what the schema provides, such as explaining relationships between parameters or usage examples. This meets the baseline for high schema 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 action ('creates') and the resource ('a price entry for a custom investment'), making the purpose understandable. However, it does not differentiate from sibling tools like 'update_custom_investment_price' or 'list_custom_investment_prices', which would require specifying scope or uniqueness to achieve a perfect score.
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 'update_custom_investment_price' for modifying existing prices or 'list_custom_investment_prices' for viewing them. There are no explicit when/when-not instructions or prerequisites mentioned, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Removes the coupon code from the current user
| 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 full burden for behavioral disclosure. While 'Removes' implies a destructive mutation, it doesn't specify whether this action is reversible, requires specific permissions, has side effects (e.g., affecting user account status), or provides confirmation feedback. For a destructive operation with zero annotation coverage, this is inadequate.
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, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, with every word earning its place in conveying the core functionality.
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 destructive tool with no annotations and no output schema, the description is incomplete. It doesn't address what happens after removal (e.g., success confirmation, error conditions), whether it affects related data, or how it interacts with sibling tools like 'apply_coupon_code'. The minimal description leaves significant gaps for the agent to understand the tool's 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 tool has zero parameters, and schema description coverage is 100% (empty schema). The description doesn't need to explain parameters, and it correctly doesn't mention any. A baseline of 4 is appropriate for parameterless tools when the schema fully covers the absence of 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 clearly states the action ('Removes') and target resource ('the coupon code from the current user'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'delete_coupon_rate' or 'revoke_api_access', which also perform deletion operations on different resources.
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 like 'delete_coupon_rate' or 'show_coupon_code'. It doesn't mention prerequisites (e.g., whether a coupon code must exist first) or contextual constraints, leaving the agent with insufficient usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes a coupon rate
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The coupon rate ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the destructive action ('deletes') but doesn't mention whether this is permanent, requires specific permissions, has side effects, or what happens on success/failure. This is inadequate for a mutation tool with zero annotation coverage.
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, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it immediately scannable and appropriately sized for the tool's complexity.
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 destructive mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'deletes' entails (e.g., permanence, side effects), what the return value might be, or how to handle errors, leaving critical gaps for an AI agent to operate safely.
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 input schema fully documents the single parameter 'id'. The description adds no additional parameter semantics beyond what's in the schema, resulting in the baseline score of 3 for adequate but not enhanced 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 action ('deletes') and resource ('a coupon rate'), making the purpose immediately understandable. It distinguishes from siblings like 'delete_coupon_code' by specifying the resource type, though it doesn't explicitly contrast with 'update_coupon_rate' or 'list_coupon_rates'.
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 'update_coupon_rate' or 'list_coupon_rates'. The description lacks context about prerequisites (e.g., needing an existing coupon rate ID) or consequences, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes a custom investment
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The custom investment ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Deletes' implies a destructive mutation, but the description doesn't specify whether deletion is permanent, requires specific permissions, has side effects (e.g., on related data like prices or holdings), or provides confirmation feedback. This is a significant gap for a destructive tool with zero annotation coverage.
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, efficient sentence with zero waste. It's appropriately sized for a simple tool and front-loaded with the core action, though its brevity contributes to gaps in other dimensions.
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 complexity (a destructive deletion tool), lack of annotations, and no output schema, the description is incomplete. It fails to address critical aspects like behavioral traits (e.g., permanence, side effects), usage context, or return values, leaving the agent under-informed for safe and effective use.
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 description adds no parameter information beyond what the input schema provides. With 100% schema description coverage (the 'id' parameter is fully documented as 'The custom investment ID to delete'), the baseline is 3. The description doesn't compensate with additional context like ID format or sourcing.
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 'Deletes a custom investment' clearly states the verb (deletes) and resource (custom investment), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'delete_coupon_code' or 'delete_holding' beyond the resource name, nor does it specify what constitutes a 'custom investment' in this context.
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. It doesn't mention prerequisites (e.g., needing an existing custom investment), exclusions, or relationships with sibling tools like 'delete_custom_investment_price' or 'get_custom_investment', leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes a price for a custom investment
| Name | Required | Description | Default |
|---|---|---|---|
| price_id | Yes | The price ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action is a deletion, implying a destructive mutation, but fails to mention critical details like whether this operation is irreversible, requires specific permissions, has side effects (e.g., on associated investments), or returns confirmation data. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no unnecessary words, making it highly concise and front-loaded. It efficiently communicates the core action without redundancy or fluff, earning full marks for brevity and clarity in structure.
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 destructive mutation tool with no annotations and no output schema, the description is incomplete. It lacks behavioral details (e.g., irreversibility, permissions), usage context, and information on return values or errors. While concise, it doesn't compensate for the missing structured data, leaving the agent with insufficient guidance for safe and effective use.
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, with the single parameter 'price_id' documented as 'The price ID to delete'. The description adds no additional semantic context beyond this, such as how to obtain a price_id or format requirements. Given the high schema coverage, a baseline score of 3 is appropriate as the schema handles the parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Deletes') and the resource ('a price for a custom investment'), making the purpose specific and understandable. However, it doesn't distinguish this tool from sibling deletion tools like delete_coupon_code or delete_custom_investment, which would require mentioning the specific resource type to achieve full differentiation.
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 doesn't mention prerequisites (e.g., needing an existing price_id), exclusions, or related tools like list_custom_investment_prices for finding IDs or update_custom_investment_price for modifications, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes a holding
| Name | Required | Description | Default |
|---|---|---|---|
| holding_id | Yes | The holding ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Deletes a holding' implies a destructive, irreversible mutation, but it doesn't specify consequences (e.g., whether related data like portfolio holdings are affected), permissions required, error conditions, or what happens on success (e.g., no return value mentioned). This is inadequate for a destructive tool with zero annotation coverage.
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 with just two words ('Deletes a holding'), which is front-loaded and wastes no space. Every word earns its place by conveying the core action and resource without unnecessary elaboration.
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 (destructive deletion with no annotations and no output schema), the description is incomplete. It lacks crucial context such as what 'holding' refers to in this domain, the impact of deletion, error handling, or confirmation requirements, making it insufficient for safe and effective use by an AI 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 1 parameter with 100% description coverage ('The holding ID to delete'), so the schema fully documents the parameter. The description doesn't add any semantic details beyond this, but with 0 parameters needing extra explanation and high schema coverage, the baseline is 4 as it doesn't detract from the schema's clarity.
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 'Deletes a holding' clearly states the action (delete) and resource (holding), which is a specific verb+resource combination. However, it doesn't distinguish this tool from sibling tools like delete_coupon_code, delete_coupon_rate, delete_custom_investment, or delete_custom_investment_price, all of which perform similar deletion operations on different resources.
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. There's no mention of prerequisites (e.g., needing a holding_id from list_holdings or get_holding), when not to use it (e.g., for non-existent holdings), or explicit alternatives like update_holding for modifications instead of deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves a single custom investment by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The custom investment ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states it retrieves by ID. It doesn't disclose behavioral traits like read-only nature (implied but not explicit), error handling, authentication needs, rate limits, or response format, leaving significant gaps for a tool with potential data access implications.
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, efficient sentence with zero waste—'Retrieves a single custom investment by ID'—front-loading the core purpose. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a simple input schema, the description is incomplete. It lacks details on return values, error cases, or behavioral context, which is inadequate for a tool that retrieves data, especially without structured safety or output information.
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 schema fully documents the 'id' parameter. The description adds no additional meaning beyond implying retrieval by ID, which aligns with the schema. Baseline 3 is appropriate as the schema handles parameter documentation 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 clearly states the verb ('retrieves') and resource ('a single custom investment'), specifying it's by ID. It distinguishes from sibling 'list_custom_investments' by focusing on single retrieval, but doesn't explicitly differentiate from 'get_holding' or other get_* tools, keeping it at 4.
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 'list_custom_investments' for multiple items or 'get_holding' for related data. The description lacks context on prerequisites or exclusions, offering minimal usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves details of a specific holding
| Name | Required | Description | Default |
|---|---|---|---|
| holding_id | Yes | The holding ID | |
| average_purchase_price | No | Include average purchase price in response | |
| cost_base | No | Include cost base in response | |
| values_over_time | No | Set to 'true' for values from inception, or a date (YYYY-MM-DD) for start date |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Retrieves details' which implies a read-only operation, but it doesn't mention potential side effects, error conditions, authentication needs, rate limits, or the format of returned details. This leaves significant gaps for an agent to understand how to handle the tool effectively.
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, efficient sentence with no wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly. Every word earns its place by conveying essential information 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?
Given the complexity of a tool with 4 parameters (including boolean flags and a string for time-based data), no annotations, and no output schema, the description is insufficient. It doesn't explain what details are retrieved, how the parameters affect the output, or any behavioral traits. For a tool that likely returns financial data, more context is needed to ensure proper 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 description coverage is 100%, meaning all parameters are documented in the schema itself. The description doesn't add any meaning beyond what the schema provides (e.g., it doesn't explain what a 'holding' is or how parameters interact). Since the schema does the heavy lifting, the 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 action ('Retrieves details') and resource ('of a specific holding'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'get_custom_investment' or 'list_holdings', which would require more specificity about what makes a 'holding' unique in this context.
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 'list_holdings' or 'get_portfolio'. The description implies it's for retrieving details of a specific holding, but it doesn't clarify prerequisites, such as needing a valid holding_id, or contextual constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns performance index chart data points for visualizing portfolio performance over time
| Name | Required | Description | Default |
|---|---|---|---|
| portfolio_id | Yes | The portfolio ID | |
| consolidated | No | True if consolidated view is requested | |
| start_date | No | Start date YYYY-MM-DD (defaults to inception) | |
| end_date | No | End date YYYY-MM-DD (defaults to today) | |
| grouping | No | Group by: country, currency, custom_group, industry_classification, investment_type, market, portfolio, sector_classification, ungrouped | |
| custom_group_id | No | Custom group ID (requires grouping=custom_group) | |
| benchmark_code | No | Benchmark code and market (e.g., SPY.NYSE) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool returns data points for visualization, implying a read-only operation, but doesn't clarify authentication needs, rate limits, error handling, or the format of returned data (e.g., time-series structure). For a tool with 7 parameters and no annotations, this is insufficient.
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, efficient sentence that front-loads the core purpose ('Returns performance index chart data points') and adds context ('for visualizing portfolio performance over time'). Every word earns its place with no redundancy or fluff.
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 minimally adequate. It specifies the tool's purpose and visualization context but lacks details on behavioral traits, usage guidelines, and output format. With no annotations to cover safety or behavior, the description should do more to compensate.
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 schema fully documents all 7 parameters with descriptions and constraints (e.g., date formats, grouping options). The description adds no additional parameter semantics beyond implying the tool returns time-series data for visualization, which is already suggested by the schema. Baseline 3 is appropriate when the schema does the heavy lifting.
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 with a specific verb ('Returns') and resource ('performance index chart data points'), and specifies the visualization context ('for visualizing portfolio performance over time'). However, it doesn't explicitly differentiate from sibling tools like 'get_performance_report' or 'get_portfolio', which might also provide performance-related data.
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 doesn't mention sibling tools like 'get_performance_report' or 'get_portfolio', nor does it specify prerequisites or exclusions. The agent must infer usage from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the performance report for a portfolio with gains, holdings breakdown, and benchmarks
| Name | Required | Description | Default |
|---|---|---|---|
| portfolio_id | Yes | The portfolio ID | |
| start_date | No | Start date YYYY-MM-DD (defaults to portfolio inception) | |
| end_date | No | End date YYYY-MM-DD (defaults to today) | |
| consolidated | No | Set to true for consolidated portfolio views | |
| include_sales | No | Include or exclude sales | |
| report_combined | No | Receive combined totals for same instruments across portfolios | |
| grouping | No | Group by: country, currency, custom_group, industry_classification, investment_type, market, portfolio, sector_classification, ungrouped | |
| custom_group_id | No | Custom group ID (requires grouping=custom_group) | |
| include_limited | No | Include holdings limited by user plan | |
| benchmark_code | No | Benchmark code and market (e.g., SPY.NYSE) |
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 states 'Retrieves' implying a read-only operation, but doesn't disclose behavioral traits such as authentication requirements, rate limits, data freshness, or error handling. For a tool with 10 parameters and no annotations, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose. It avoids unnecessary words, though it could be slightly more structured by explicitly mentioning key parameters or usage scenarios to enhance clarity without adding bulk.
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 (10 parameters, no annotations, no output schema), the description is insufficient. It lacks details on return format, error conditions, performance implications, or how parameters affect the report. For a data retrieval tool with many options, more context is needed to guide effective use.
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%, providing detailed parameter documentation. The description adds minimal value beyond the schema by mentioning report content like 'gains, holdings breakdown, and benchmarks', which loosely relates to parameters like grouping or benchmark_code. However, it doesn't explain parameter interactions or semantics beyond what's in 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 action ('Retrieves') and resource ('performance report for a portfolio'), with specific content details ('gains, holdings breakdown, and benchmarks'). It distinguishes from siblings like get_portfolio or get_holding by focusing on performance metrics, but doesn't explicitly contrast with get_performance_index_chart, which might overlap in 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 like get_performance_index_chart or get_portfolio is provided. The description implies usage for performance data but lacks explicit context, prerequisites, or exclusions, leaving the agent to infer based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves a single portfolio by ID
| Name | Required | Description | Default |
|---|---|---|---|
| portfolio_id | Yes | The portfolio ID | |
| consolidated | No | Set to true if the portfolio is consolidated |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'retrieves' implying a read operation, but doesn't cover aspects like authentication needs, rate limits, error handling, or response format. For a tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is appropriately sized and front-loaded, with zero waste, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what a 'portfolio' entails, the return format, or error cases. For a tool with no structured data beyond the input schema, more context is needed to adequately inform an 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 schema description coverage is 100%, with both parameters ('portfolio_id' and 'consolidated') fully documented in the schema. The description adds no additional meaning beyond the schema, such as explaining the effect of 'consolidated' or providing examples. Baseline 3 is appropriate when the schema does the heavy lifting.
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 ('retrieves') and resource ('a single portfolio by ID'), making the purpose evident. However, it doesn't distinguish this tool from sibling tools like 'list_portfolios' or 'get_holding', which also retrieve portfolio-related data, so it misses full sibling differentiation.
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 'list_portfolios' for multiple portfolios or 'get_holding' for specific holdings. It lacks explicit context, prerequisites, or exclusions, leaving usage unclear relative to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves user settings for a portfolio (chart type, grouping, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| portfolio_id | Yes | The portfolio ID | |
| consolidated | No | Set to true for consolidated portfolio views |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It indicates a read operation ('Retrieves'), but lacks details on permissions, rate limits, error handling, or the format of returned settings. This is a significant gap for a tool with no annotation coverage, making it minimally informative.
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, efficient sentence that front-loads the core purpose and includes helpful examples without unnecessary details. Every word earns its place, making it highly concise and well-structured for quick understanding.
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 annotations and no output schema, the description is incomplete. It does not explain what the returned settings look like, potential errors, or behavioral traits like authentication needs. For a retrieval tool with undefined outputs, this leaves critical gaps in understanding how to use it effectively.
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 schema fully documents both parameters. The description adds no additional meaning beyond implying that settings include 'chart type, grouping, etc.', which does not directly relate to the parameters. This meets the baseline of 3 where the schema handles parameter documentation 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 clearly states the action ('Retrieves') and resource ('user settings for a portfolio'), with specific examples of settings ('chart type, grouping, etc.'). However, it does not explicitly distinguish this tool from sibling tools like 'get_portfolio' or 'update_portfolio_user_setting', which would require more specific differentiation to earn a 5.
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. For example, it does not mention when to use 'get_portfolio' for general portfolio data or 'update_portfolio_user_setting' for modifications, nor does it specify prerequisites or exclusions, leaving usage context implied at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves Sharesight country definitions
| Name | Required | Description | Default |
|---|---|---|---|
| supported | No | Filter by supported status (omit for all) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states the retrieval action without mentioning permissions, rate limits, output format, or whether it's a read-only operation. This is inadequate for a tool with zero annotation coverage.
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, efficient sentence with no wasted words. It's appropriately sized for a simple retrieval tool and front-loads the essential information without unnecessary elaboration.
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 annotations and no output schema, the description is incomplete. It doesn't explain what 'country definitions' include, the return format, or behavioral aspects like pagination. For a tool with minimal structured data, 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?
Schema description coverage is 100%, so the input schema fully documents the single parameter. The description adds no additional parameter information beyond what's in the schema, meeting the baseline for high coverage but not providing extra value.
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 ('Retrieves') and resource ('Sharesight country definitions'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'list_coupon_rates' or 'list_custom_investments' beyond the resource type, missing specific scope distinctions.
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. The description doesn't mention prerequisites, appropriate contexts, or exclusions, leaving the agent without usage direction beyond the basic purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves coupon rates for a fixed interest custom investment
| Name | Required | Description | Default |
|---|---|---|---|
| instrument_id | Yes | The custom investment instrument ID | |
| start_date | No | Start date YYYY-MM-DD | |
| end_date | No | End date YYYY-MM-DD | |
| page | No | Pagination pointer | |
| per_page | No | Items per page (max 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the retrieval action without disclosing behavioral traits like pagination handling, rate limits, authentication needs, or error conditions. It lacks details on what 'coupon rates' entail or how the data is structured, making it insufficient for informed use.
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, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and appropriately sized, making it easy to parse quickly.
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 complexity of a 5-parameter tool with no annotations and no output schema, the description is inadequate. It fails to explain return values, error handling, or behavioral context, leaving significant gaps for an AI agent to understand how to use the tool effectively.
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, clearly documenting all parameters, so the description adds no additional semantic value beyond the schema. It does not explain parameter interactions or provide context like date format nuances, resulting in a baseline score 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 ('Retrieves') and resource ('coupon rates for a fixed interest custom investment'), making the purpose understandable. However, it does not explicitly differentiate from siblings like 'get_custom_investment' or 'list_custom_investments', which might also retrieve related data, so it falls short of a perfect score.
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 'get_custom_investment' for general investment details or 'list_custom_investments' for broader listings. There is no mention of prerequisites, exclusions, or specific contexts, leaving usage ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves prices for a custom investment
| Name | Required | Description | Default |
|---|---|---|---|
| custom_investment_id | Yes | The custom investment ID | |
| start_date | No | Start date YYYY-MM-DD | |
| end_date | No | End date YYYY-MM-DD | |
| page | No | Pagination pointer | |
| per_page | No | Items per page (max 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states 'Retrieves' implying a read-only operation, but doesn't mention pagination behavior (implied by 'page' and 'per_page' parameters), rate limits, authentication needs, or error conditions. For a tool with 5 parameters and no annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for a straightforward retrieval tool and front-loads the core purpose without unnecessary elaboration.
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 annotations and no output schema, the description is incomplete. It doesn't explain what 'prices' means (e.g., historical prices, current prices, price objects), the return format, or how pagination works. For a tool with date-range filtering and pagination parameters, more context is needed to help the agent use it effectively.
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 parameters are well-documented in the schema itself. The description adds no additional meaning beyond implying date-range filtering through 'prices' (which aligns with 'start_date' and 'end_date' parameters). Since the schema does the heavy lifting, the 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 action ('Retrieves') and resource ('prices for a custom investment'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_custom_investment' or 'list_custom_investments', which might retrieve different aspects of custom investments, leaving some ambiguity about when to choose this specific tool.
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. With siblings like 'get_custom_investment' (which might retrieve metadata) and 'list_custom_investments' (which might list investments themselves), there's no indication of context, prerequisites, or exclusions. This leaves the agent to guess based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves a list of custom investments
| Name | Required | Description | Default |
|---|---|---|---|
| portfolio_id | No | Optional portfolio ID to filter by |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure but only states the basic action. It doesn't cover aspects like pagination, sorting, default behavior, error handling, or whether it's a read-only operation, leaving significant gaps for a tool that likely returns multiple items.
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, direct sentence with no wasted words, making it highly concise and front-loaded. It efficiently communicates the core purpose without unnecessary elaboration.
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 annotations and output schema, the description is insufficient for a list retrieval tool. It doesn't explain return format, potential limitations, or how results are structured, leaving the agent with incomplete information to use the tool effectively.
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 description coverage is 100%, with the single parameter 'portfolio_id' documented as optional for filtering. The description adds no additional parameter semantics beyond what the schema provides, so it meets the baseline of 3 without compensating or detracting.
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 ('retrieves') and resource ('list of custom investments'), making the tool's purpose understandable. However, it doesn't differentiate from sibling tools like 'get_custom_investment' (singular) or 'list_custom_investment_prices', which would require more specificity to earn a 5.
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_custom_investment' for a single item or 'list_custom_investment_prices' for related data. The description lacks context about use cases or exclusions, offering minimal direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves a list of all holdings across all portfolios
| 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 the full burden. It states this is a retrieval operation, implying read-only behavior, but doesn't disclose any behavioral traits such as rate limits, authentication requirements, or potential side effects. This leaves significant gaps for safe and effective use.
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 that directly states the tool's function without unnecessary words. It's front-loaded and efficiently communicates the core purpose, making it easy for an agent to parse quickly.
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 simplicity (0 parameters, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks details on usage guidelines, behavioral transparency, and output format, which could hinder an agent's ability to use it correctly in complex 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?
The input schema has 0 parameters with 100% coverage, so no parameter information is needed. The description appropriately doesn't mention parameters, which is efficient. However, it doesn't add any semantic context beyond the schema, but with no parameters, this is acceptable.
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 ('Retrieves') and resource ('list of all holdings across all portfolios'), making the purpose understandable. However, it doesn't explicitly differentiate from the sibling tool 'list_portfolio_holdings', which appears to be a more specific version, leaving some ambiguity about when to use each.
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 'list_portfolio_holdings' or 'get_holding'. The description implies a broad scope ('across all portfolios'), but without explicit instructions, the agent might struggle to choose between similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves all holdings for a specific portfolio
| Name | Required | Description | Default |
|---|---|---|---|
| portfolio_id | Yes | The portfolio ID | |
| consolidated | No | True if a consolidated view is requested |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions retrieval but doesn't specify if this is a read-only operation, what permissions are needed, whether it's paginated, or what the return format looks like. This leaves significant gaps for a tool that likely accesses sensitive financial data.
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, efficient sentence with zero waste. It's front-loaded with the core action and resource, making it easy to parse quickly.
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 complexity of financial data retrieval, no annotations, and no output schema, the description is insufficient. It doesn't explain return values, error conditions, or behavioral traits like rate limits or authentication needs, 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 description coverage is 100%, so the schema already documents both parameters ('portfolio_id' and 'consolidated'). The description adds no additional meaning beyond implying retrieval of holdings, which is already clear from the tool name and purpose. Baseline 3 is appropriate when the schema does the heavy lifting.
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 ('Retrieves') and resource ('holdings for a specific portfolio'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'list_holdings' or 'get_holding', which appear to serve similar functions, preventing a perfect score.
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 like 'list_holdings' or 'get_holding', nor does it mention prerequisites or exclusions. It only states what it does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves a list of the user's portfolios. Optionally filter by consolidated view or instrument.
| Name | Required | Description | Default |
|---|---|---|---|
| consolidated | No | Set to true to see consolidated portfolio views | |
| instrument_id | No | Filter by instrument ID. When set, consolidated defaults to false |
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 mentions retrieval and optional filtering, but fails to disclose critical behaviors such as pagination, rate limits, authentication requirements, error handling, or the format of the returned list. This leaves significant gaps for an agent to understand how to use the tool effectively.
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, efficient sentence that front-loads the core purpose and briefly mentions optional features. There is no redundant information or unnecessary elaboration, making it highly concise and well-structured for quick understanding.
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 annotations and output schema, the description is incomplete. It covers the basic purpose and parameters but omits essential details like return format, error conditions, and behavioral traits (e.g., whether it's read-only, safe to use). For a tool with no structured safety or output information, this leaves the agent under-informed.
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 schema already documents both parameters thoroughly. The description adds minimal value by mentioning the optional filters ('consolidated view or instrument'), but does not provide additional context, examples, or clarifications beyond what the schema specifies, aligning with 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 verb ('Retrieves') and resource ('list of the user's portfolios'), making the purpose evident. However, it does not explicitly differentiate from sibling tools like 'get_portfolio' or 'list_portfolio_holdings', which might retrieve specific portfolio details or holdings instead of a list of portfolios.
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 by mentioning optional filters ('consolidated view or instrument'), suggesting when to use these parameters. However, it lacks explicit guidance on when to choose this tool over alternatives like 'get_portfolio' for single portfolios or 'list_holdings' for holdings, and does not 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.
Disconnects API access for the user. Invalidates ALL access and refresh tokens.
| Name | Required | Description | Default |
|---|---|---|---|
| client_id | Yes | The client application 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 discloses the destructive behavior ('Invalidates ALL access and refresh tokens'), which is critical, but lacks details on permissions required, whether the action is reversible, rate limits, or what happens after revocation (e.g., error responses, confirmation). For a high-impact tool with zero annotation coverage, this is insufficient.
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 zero waste, front-loading the core action ('Disconnects API access for the user') and immediately specifying the scope ('Invalidates ALL access and refresh tokens'). Every word contributes essential information 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?
Given the tool's complexity (destructive, security-critical) and lack of annotations or output schema, the description is incomplete. It misses crucial details like authentication requirements, error handling, and confirmation of success, which are necessary for safe and effective use by an AI 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?
Schema description coverage is 100%, with the single parameter 'client_id' documented as 'The client application ID'. The description does not add any meaning beyond this, such as explaining how to obtain the client_id or its format. Since the schema fully covers the parameter, the 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 specific action ('Disconnects API access for the user') and resource ('API access'), with explicit scope ('Invalidates ALL access and refresh tokens'). It distinguishes itself from sibling tools like 'apply_coupon_code' or 'update_portfolio_user_setting' by focusing on authentication revocation rather than coupon, investment, or portfolio management.
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, prerequisites, or exclusions. It does not mention any specific scenarios (e.g., security incidents, user deactivation) or warn against misuse, leaving the agent to infer context from the tool's name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the coupon code applied to the current user
| 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 the full burden of behavioral disclosure. It states it 'Returns' data, implying a read-only operation, but does not clarify aspects like authentication needs, rate limits, error conditions, or what happens if no coupon is applied. This leaves significant gaps for a tool with no annotation coverage.
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, efficient sentence that directly states the tool's purpose without any redundant or verbose language. It is front-loaded and appropriately sized for its simple function.
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 0 parameters, no annotations, and no output schema, the description is minimally adequate but incomplete. It explains what the tool does but lacks details on return format, error handling, or behavioral context, which are important for a tool interacting with user data.
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 0 parameters with 100% coverage, so no parameter information is needed. The description appropriately does not discuss parameters, earning a baseline score of 4 for not adding unnecessary details beyond what the schema 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 action ('Returns') and the resource ('the coupon code applied to the current user'), making the purpose evident. However, it does not explicitly differentiate from sibling tools like 'apply_coupon_code' or 'delete_coupon_code' in terms of scope or function, which prevents a perfect score.
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 'apply_coupon_code' or 'delete_coupon_code', nor does it mention any prerequisites or context for usage. It lacks explicit when/when-not instructions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates a coupon rate
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The coupon rate ID | |
| interest_rate | Yes | The interest rate as a percentage | |
| date | Yes | The date from which the rate applies YYYY-MM-DD |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but offers no information beyond the basic action. It does not address permissions, side effects, error conditions, rate limits, or what happens upon successful update, making it inadequate for a mutation tool with zero annotation coverage.
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 with a single sentence that directly states the tool's action. It is front-loaded and wastes no words, though this brevity contributes to its informational deficiencies rather than being a strength 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 the tool's complexity as a mutation operation with no annotations and no output schema, the description is severely incomplete. It fails to explain behavioral traits, usage context, or return values, leaving critical gaps for an AI agent to understand and invoke the tool 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%, with clear descriptions for all three parameters (id, interest_rate, date). The description adds no parameter semantics beyond what the schema provides, so it meets the baseline score of 3 for high schema coverage without compensating value.
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 'Updates a coupon rate' is a tautology that restates the tool name without adding meaningful context. It specifies the verb ('Updates') and resource ('a coupon rate') but lacks differentiation from sibling tools like 'create_coupon_rate' or 'delete_coupon_rate', failing to clarify what distinguishes this update operation from creation or deletion.
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 mention prerequisites (e.g., an existing coupon rate ID), exclusions, or contextual cues, leaving the agent without direction on appropriate usage scenarios compared to siblings like 'list_coupon_rates' or 'create_coupon_rate'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates an existing custom investment
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The custom investment ID | |
| code | No | The investment code | |
| name | No | The name of the custom investment | |
| portfolio_id | No | Portfolio ID to associate with | |
| face_value | No | Face value per unit | |
| interest_rate | No | Interest rate | |
| income_type | No | DIVIDEND or INTEREST | |
| payment_frequency | No | Payment frequency | |
| first_payment_date | No | First payment date YYYY-MM-DD | |
| maturity_date | No | Maturity date YYYY-MM-DD | |
| auto_calc_income | No | Auto-populate income payments |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but provides minimal behavioral insight. It states 'Updates' implying mutation but doesn't disclose permission requirements, whether updates are partial or full, side effects, error conditions, or response format. For a mutation tool with 11 parameters, this leaves critical gaps in understanding how the tool behaves.
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 wasted words. It's front-loaded with the core action and resource. For a tool with comprehensive schema coverage, this brevity is appropriate 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 mutation tool with 11 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what 'update' entails (e.g., partial updates, validation rules), required permissions, error handling, or return values. The agent lacks context to use this tool effectively beyond basic parameter passing.
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 all parameters are documented in the schema. The description adds no additional parameter semantics beyond implying 'id' is required for an existing investment. This meets the baseline of 3 where the schema does the heavy lifting, but the description doesn't enhance understanding of parameter relationships or constraints.
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 'Updates an existing custom investment' clearly states the action (update) and resource (custom investment), but it's generic and doesn't differentiate from sibling tools like update_coupon_rate or update_custom_investment_price. It specifies 'existing' which distinguishes from create_custom_investment, but lacks detail about what aspects can be updated.
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. The description doesn't mention prerequisites (e.g., needing an existing custom investment), compare to sibling tools like update_custom_investment_price, or specify use cases. The agent must infer usage from the name and parameters alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates a price for a custom investment
| Name | Required | Description | Default |
|---|---|---|---|
| price_id | Yes | The price ID | |
| last_traded_price | No | The price in instrument currency | |
| last_traded_on | No | The date YYYY-MM-DD |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Updates', implying a mutation, but fails to mention critical details like required permissions, whether the operation is idempotent, error handling for invalid inputs, or side effects on related data. This leaves significant gaps in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no wasted words, efficiently conveying the core action. It is front-loaded and appropriately sized for the tool's complexity, making it easy to parse without unnecessary elaboration.
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 annotations and output schema, and the tool being a mutation operation, the description is insufficient. It does not cover behavioral aspects like success responses, error formats, or impact on system state, leaving the agent with incomplete information for reliable invocation in a production 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 schema description coverage is 100%, with clear parameter descriptions in the schema (e.g., 'price_id' as 'The price ID'). The tool description adds no additional meaning beyond the schema, such as explaining relationships between parameters or usage examples. Since the schema handles documentation adequately, the 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 action ('Updates') and resource ('a price for a custom investment'), making the purpose evident. However, it does not differentiate from sibling tools like 'update_custom_investment' or 'create_custom_investment_price', which handle related but distinct operations on custom investments or their prices, leaving room for ambiguity in tool selection.
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 'create_custom_investment_price' for new prices or 'delete_custom_investment_price' for removal. The description lacks context about prerequisites, error conditions, or typical scenarios, offering minimal assistance in decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates a holding (currently supports DRP settings)
| Name | Required | Description | Default |
|---|---|---|---|
| holding_id | Yes | The holding ID | |
| enable_drp | No | Set to true to enable DRP, false to disable | |
| drp_mode_setting | No | DRP mode: up, down, half, or down_track |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While 'Updates' implies mutation, it doesn't specify whether this requires special permissions, what happens to existing settings not mentioned, whether changes are reversible, or what the response looks like. The mention of 'DRP settings' provides some context about what gets modified, but lacks details about side effects, error conditions, or system 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 extremely concise - a single sentence that efficiently communicates the core functionality. It's front-loaded with the main action and resource, with the parenthetical adding useful scope information. There's zero wasted language or 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?
For a mutation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what a 'holding' is in this context, what DRP stands for, what the expected response format is, or any error conditions. Given the complexity of updating financial holdings and the lack of structured metadata, the description should provide more context about the operation's behavior and outcomes.
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 schema already documents all three parameters thoroughly. The description adds minimal value beyond what's in the schema - it mentions 'DRP settings' which aligns with the 'enable_drp' and 'drp_mode_setting' parameters, but provides no additional semantic context about parameter relationships, constraints, or usage patterns beyond what the schema descriptions already state.
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 ('Updates') and resource ('a holding'), and specifies the scope of current functionality ('currently supports DRP settings'). It distinguishes from siblings like 'delete_holding' by focusing on updates rather than deletion. However, it doesn't explicitly differentiate from other update tools like 'update_coupon_rate' or 'update_custom_investment' beyond the resource name.
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 doesn't mention prerequisites (like needing a holding ID), when not to use it, or how it differs from other update operations. With multiple sibling tools including 'get_holding' and 'list_holdings', there's no indication of when this update tool is appropriate versus those read operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates user settings for a portfolio
| Name | Required | Description | Default |
|---|---|---|---|
| portfolio_id | Yes | The portfolio ID | |
| consolidated | No | Set to true for consolidated portfolio views | |
| portfolio_chart | No | Chart type: VALUE, VALUELINE, GROWTH, BENCHMARK, or HIDE | |
| holding_chart | No | Holding chart type: PRICE, HOLDING_VALUE, BENCHMARK, or HIDE | |
| combined | No | True to combine holdings in consolidated portfolios | |
| grouping | No | Grouping to use (e.g., market, country, currency) | |
| include_sold_shares | No | True to include sold shares in calculations |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Updates', implying a mutation, but does not disclose any behavioral traits like required permissions, whether changes are reversible, rate limits, or what the response looks like. This is a significant gap for a mutation tool with zero annotation coverage.
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, efficient sentence that directly states the tool's purpose without unnecessary words. It is appropriately sized and front-loaded, making it easy to parse quickly.
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 complexity of a mutation tool with 7 parameters, no annotations, and no output schema, the description is incomplete. It lacks crucial information such as behavioral context, usage guidelines, and output details, which are necessary for the agent to use the tool effectively.
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 description coverage is 100%, meaning all parameters are documented in the schema. The description does not add any additional meaning or context beyond what the schema provides, such as explaining interactions between parameters or default behaviors. With high schema coverage, the 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 action ('Updates') and target ('user settings for a portfolio'), making the purpose evident. However, it does not differentiate this tool from sibling tools like 'update_coupon_rate' or 'update_ustom_investment', which also perform updates on different resources, so it lacks sibling distinction.
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. There is no mention of prerequisites, context, or exclusions, such as when to use 'get_portfolio_user_setting' for retrieval instead. This leaves the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes targeting specific resources and actions, such as custom investments, coupon rates, holdings, and portfolios. However, there is some potential overlap between 'list_holdings' (all holdings across portfolios) and 'list_portfolio_holdings' (holdings for a specific portfolio), which could cause minor confusion in selection. Overall, the descriptions help clarify boundaries, keeping ambiguity low.
Tool names follow a highly consistent verb_noun pattern throughout, such as 'create_custom_investment', 'list_coupon_rates', and 'update_holding'. All tools use snake_case with clear action verbs (e.g., apply, create, delete, get, list, update, show, revoke), making them predictable and easy to understand. No deviations or mixed conventions are present.
With 29 tools, the count is borderline high for a portfolio management server, potentially feeling heavy and overwhelming. While the tools cover various aspects like custom investments, coupon codes, holdings, and portfolios, the number might exceed typical well-scoped ranges (3-15 tools), suggesting some consolidation or simplification could improve usability without losing functionality.
The tool set provides comprehensive CRUD and lifecycle coverage for the domain of portfolio and investment management. It includes operations for custom investments, coupon rates, holdings, portfolios, performance data, and user settings, with no obvious gaps. Agents can perform full workflows from creation to deletion and reporting, ensuring no dead ends in typical use cases.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Connect your portfolio to Claude, ChatGPT, or Codex to analyze it and make smarter investments.
Connect AI agents to bank accounts, transactions, balances, and investments.
Personal finance, bank account, and shared memory connector for Claude, ChatGPT, Gemini Spark & more
Portfolio analytics + US-equity market research for AI clients. ChatGPT deep-research compat.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Haizzz/sharesight-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
