Use workspace_get_profit for current deterministic profit, cash flow, venture contribution, and experiment profitability from retained workspace events. Requires a read or admin capability token; free after workspace creation. Use profit_calculate for stateless data.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | Yes | ||
| capabilityToken | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses authentication requirements ('Requires a read or admin capability token'), cost implications ('free after workspace creation'), and the deterministic nature of the data. While it doesn't detail error handling or output format, the output schema covers return values, making it fairly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences, each serving a clear purpose: stating the tool's output, specifying requirements, and directing to an alternative. No unnecessary information is present.
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 existence of an output schema, the description appropriately does not elaborate on return values. It lists key output concepts (profit, cash flow, venture contribution, experiment profitability) and mentions the source ('retained workspace events'). Missing details like error handling or rate limits are minor, so completeness is strong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% for both parameters. The description adds meaning to the capabilityToken parameter by specifying it must be a 'read or admin capability token', but provides no additional context for workspaceId. This partial compensation places the score at 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 tool returns 'current deterministic profit, cash flow, venture contribution, and experiment profitability from retained workspace events', specifying the resource and context. It distinguishes itself from sibling profit_calculate, ensuring no confusion.
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 explicitly states when to use this tool ('for current deterministic profit...') and when to use an alternative ('Use profit_calculate for stateless data'). It also mentions the requirement of a capability token, providing clear context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Tools are largely distinct, though profit_analyze and profit_calculate have overlapping purposes. Descriptions clarify the difference (findings vs totals), but potential confusion remains for agents.
All tool names follow a consistent verb_noun snake_case pattern (profit_*, workspace_*, report_verify). No mixing of conventions.
8 tools is appropriate for a profit ledger server, covering stateless analysis and persistent workspace workflows without excessive or insufficient tools.
Core CRUD-like operations are covered for both stateless and persistent modes. Minor gaps exist (e.g., no explicit workspace deletion or listing), but the server's purpose is well-served.