Portfolio Copilot

by lodetomasi

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.3.1
Disambiguation2/5
Several tools overlap heavily: screen_stocks and rank_candidates both score/rank a ticker list, and allocate_cash, rebalance_portfolio, capital_auction and generate_order_plan all produce allocation/order suggestions. The long descriptions help, but an agent must read carefully to select the intended tool, and clusters like discovery/analysis and cash allocation blur together.
Naming Consistency3/5
All names are snake_case and readable, but the set mixes verb-first names like analyze_stock and save_thesis with noun-first names like fx_rates, portfolio_risk, capital_auction and company_facts. This is a readable mixed convention rather than a consistent verb_noun pattern.
Tool Count2/5
34 tools is a very large surface and exceeds the 25+ threshold for too many. The broad functionality could be collapsed into fewer consolidated tools (e.g. one cash-allocation/order tool or one stock-ranking tool), reducing agent selection burden.
Completeness4/5
The tool surface covers the full investment-assistant workflow: import/parse exports, fetch market/SEC data, score stocks, build plans, allocate/rebalance, log decisions, check theses, snapshot portfolios and backtest. Minor gaps exist (no delete/update for snapshots or decisions, no config setter), but core workflows have no dead ends and file-based workarounds are reasonable.
Average 3.9/5 across 34 of 34 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 9 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the transparency burden. It usefully discloses the local, git-ignored ledger location and the append-only persistence model, but it does not explain side effects, return values, idempotency, or failure modes for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with no filler; the verb is front-loaded and both sentences contribute useful context. It is concise to a fault given the parameter complexity, but as pure structure it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 17 parameters, no output schema, and no annotations, an agent has little guidance on expected behavior, return value, or how the many optional fields fit together. The description only covers the basic append purpose and leaves the rest to the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 47%, so the description should compensate, but it mentions only the generic concepts 'what was decided' and 'shadow alternative' without detailing any of the 17 parameters. It adds almost no meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Append') and a specific resource ('local decision ledger') plus the purpose of recording decisions for later measurement. It is unambiguous about being a write-only log, but it does not explicitly name or contrast sibling tools like review_decisions or decision_quality, so it stops short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement about when to choose this tool over alternatives or any exclusions. The description implies it is for recording a decision, but it does not mention that review_decisions is for reading or that decision_quality is for scoring, leaving selection entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose one important behavior: it cannot send orders to a broker, so it is a non-executing planning tool. However, it does not state side effects, whether it reads portfolio state, or how it behaves when constraints (e.g., target sum to 1.0) are violated, leaving behavioral transparency incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no wasted words; the core action and the key broker limitation are front-loaded. It is an appropriate length for the information it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters, 3 required, nested objects, no output schema, and no annotations, this description is too sparse. It doesn't explain the return shape, how fees influence the plan, or how targets and current values relate, so an agent would be uncertain about invocation expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (targets and current_values), yet the description adds no parameter-level meaning. The fee parameters (fixed_fee_eur, max_fee_ratio, variable_fee_pct) and cash_eur are left entirely to their names and defaults, which is insufficient compensation for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Return') and object ('suggested manual orders'), making the tool's core function clear. It also adds a critical boundary ('cannot send orders to any broker'), but it doesn't name or differentiate against sibling tools like build_investment_plan or rebalance_portfolio, so it stops short of strong differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool over siblings such as allocate_cash, rebalance_portfolio, or build_investment_plan. The only implicit signal is that it is for planning rather than execution, but no alternatives or conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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. It clearly indicates a read-only summarization action rather than a mutation, but it does not disclose details such as required file format, error behavior, or whether the export must be parsed first. This is adequate but not deeply transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to the core purpose, and it is appropriately sized for a tool with only two parameters and no nested structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, no annotations, and 0% parameter documentation, so the description must provide a fuller picture on its own. It does not explain what the summarized output looks like, how the path should be supplied, what base_currency affects, or how this tool relates to parse_portfolio_export. This leaves notable gaps for an agent trying to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description does not explain either parameter. 'From a local export' gives a slight hint that 'path' points to an export file, but 'base_currency' is entirely unaddressed and the description adds no meaningful semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Summarize') and a concrete resource ('weights, concentration and leveraged exposure') from a 'local export'. This is distinct enough to separate it from live data tools like portfolio_exposure, though it does not explicitly mention siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'from a local export' implies this tool is for offline/exported data rather than live portfolio queries, providing some usage context. However, it does not explicitly state when to prefer this over sibling tools like portfolio_exposure or parse_portfolio_export, nor does it mention any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It discloses that missing price data buckets are reported rather than invented and that this is a past replay, not a forecast. It could also state side effects, rate limits, or output normalizations, but the core non-destructive, non-inventive behavior is well conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the action and expected outputs. Each sentence adds useful information: what it does, how missing data are handled, and a caveat about interpretation. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is an 11-parameter tool with no output schema and no annotations. The description gives a high-level summary and a data-fidelity promise, but it does not cover parameter behavior, return structure, failure modes, or how the plan rules are applied. An agent would still have significant uncertainty when invoking it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 27%, and the description does not compensate. It mentions fee-related outputs but does not explain period, fixed_fee_eur, max_fee_ratio, rebalance_band_abs, contribution_every_months, or price_source semantics. The schema only documents targets, tickers_by_bucket, and price_source, leaving most parameters without meaningful guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: replaying plan rules on past monthly prices, and lists concrete outputs (fees paid, drift, drawdown, final weights). It does not explicitly distinguish itself from sibling backtest_picker, so it falls short of the top score, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when the tool is appropriate: when a historical replay of plan rules is needed, and it explicitly says it is not a forecast. However, it does not name alternatives, exclusions relative to sibling tools, or prerequisite situations, so guidance remains mostly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It reveals a concrete rule: the tool refuses to issue a raise/lower verdict until a group has at least min_sample measured decisions. It also scopes results to 'measured rows', which is useful beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: two sentences with the core distinction front-loaded and the behavioral rule stated efficiently. The phrasing 'evidence threshold raise/lower' is somewhat jargon-heavy, but the entry as a whole is informative without being bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, it does state the main metrics returned and a key guardrail. However, it leaves min_days unexplained and does not clarify behavior when there are no measured decisions for a category. These are material gaps for an agent deciding how to call and interpret the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes min_sample but not min_days, leaving schema coverage at 50%. The description reinforces min_sample's role in the refusal behavior and mentions its default, but it adds no meaning for min_days. Since schema coverage is low, the description should compensate for the missing parameter semantics, and it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's output: the user's own decision track record, consisting of mean decision alpha and hit rate by category/theme. It explicitly contrasts with 'a market study', which helps orient the agent, though it does not name or differentiate specific sibling tools like decision_quality or review_decisions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives contextual guidance by saying this is the user's personal track record rather than a market study, and it points to log_decision's category/theme fields. However, it does not explicitly state when to use this tool versus alternatives such as decision_quality or review_decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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. It reveals the no-selling constraint and mentions fees, but does not state whether this tool executes trades, returns an order plan, or how fees are actually calculated. This leaves significant behavioral ambiguity for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the action and the key constraint. Every word adds meaning, and there is no redundant elaboration or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has 7 parameters, nested objects, no annotations, and no output schema, yet the description only covers the high-level purpose. It omits essential details about return values, side effects, fee handling, and the rebalance band, making it incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 29%, and the description only loosely maps to targets, cash_eur, and generic fees. It does not clarify current_values, rebalance_band_abs, max_fee_ratio, fixed_fee_eur, or variable_fee_pct, leaving several parameters semantically underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Allocate new cash'), a target outcome ('toward target weights'), and a key constraint ('without selling'). It effectively differentiates this from a general rebalance tool that might sell assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'new cash' and 'without selling' provides clear context for when this tool is appropriate. It does not explicitly name alternatives or exclusions, but the described scenario is distinct enough for an agent to choose it over rebalancing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral disclosure burden. It adds meaningful context: the data is audited, annual, from XBRL facts, includes fiscal year and filing date, and the result explicitly reports when ADRs lack facts. It does not mention rate limits or response structure, but the key behavioral constraints are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and packs in the data source, scope, metric list, and an important limitation without wasting words. The core facts are front-loaded, and the caveat is placed at the end. It earns a 4 rather than 5 because the line break and sentence flow could be slightly tighter, but it is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with no output schema, the description covers the main return contents and a key edge case. It explains what data comes back, the filing period context, and the ADR limitation. Minor gaps remain around ticker formatting and units, but the description is largely sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, ticker, has no description in the schema and the description does not explain ticker format, such as whether to use a plain US ticker like AAPL or a suffix like .US. The ADR caveat hints at ticker selection indirectly but does not define accepted formats or normalization behavior. With 0% schema coverage, the description needed to compensate more.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as audited annual fundamentals sourced from SEC EDGAR 10-K XBRL facts. Although it omits an explicit verb like 'retrieves' or 'provides,' the intended operation is unmistakable. The listed metrics (revenue, net income, free cash flow, equity, debt) distinguish it from most sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context by stating this is for US filers only, annual data, and free, and it warns that foreign ADRs usually lack US-GAAP facts. However, it does not explicitly state when to prefer this tool over nearby alternatives like analyze_stock or filing_sections, nor does it describe when not to use it beyond the ADR caveat.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explicitly states a key behavioral trait: it never looks at the outcome. It also enumerates the rubric dimensions and hints at a pairing with the decision/outcome matrix under a certain condition. The pairing statement is vague, but the core behavior is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact at two sentences and is front-loaded with the core purpose. However, the second sentence is jargon-heavy and unclear ('Paired here with the decision/outcome matrix using today's measured alpha...'), and the first sentence is a long run-on list. It is concise but not cleanly structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description provides the score range, the evaluation criteria, the exclusion of outcome, and a hint at a paired matrix. What is missing is the exact return shape and the meaning of the pairing, which an agent would need to correctly interpret the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, decision_id, has no description in the schema beyond its type and title. The description partially compensates by saying 'one logged decision (see log_decision)', which implies decision_id refers to a decision created by log_decision. However, it does not explicitly state the ID format or that it is the return value from log_decision, so the guidance is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool evaluates process quality of one logged decision on a 0-100 scale and lists specific criteria. It references log_decision to clarify the context. However, the second sentence about being 'paired here with the decision/outcome matrix' is ambiguous and slightly muddies the core purpose, so it does not 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context: it applies to one logged decision, focuses on process quality, and explicitly excludes outcome ('Never looks at the outcome'). It also mentions a condition ('when the decision is already priceable'). However, it does not explicitly name alternative tools or state when to prefer this over siblings like review_decisions, so the guidance is mostly implied rather than direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does add useful context: data source (ECB), free availability, and the return format (units per 1 EUR with as_of). However, it does not disclose update frequency, currency coverage, or whether the data is current or historical, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that front-loads the key facts: official, ECB, free, and the rate direction. There is no fluff or repetition, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with no output schema, the description gives the essential details an agent needs to understand what it returns: 'units of currency per 1 EUR' and 'with as_of'. It could be more complete by mentioning historical vs current rates or viable currency codes, but the simplicity of the tool keeps this gap minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and schema coverage is trivially 100%. The baseline for parameterless tools is 4, and the description appropriately does not attempt to explain nonexistent parameters. No additional parameter semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (ECB euro reference rates) and the data format (units per EUR with as_of), which distinguishes it from convert_amount_to_eur and other siblings. It lacks an explicit verb like 'get' or 'retrieve', but the tool name and context make the action unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives such as convert_amount_to_eur. The intended use is implied for fetching exchange rates, but the description provides no exclusions or comparative context to help an agent choose between related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well. It discloses that equity sectors/industries are fetched from a market-data provider, failed lookups are recorded under 'provider_errors' and never guessed, ETFs/certificates/bonds use only exported fields, and the leverage-adjusted equivalent view is not a VaR substitute.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but not bloated: the example clarifies the core concept, the per-asset-class rules are separated cleanly, and the VaR caveat is placed at the end. It is slightly long, but every sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers nuanced behavioral details and failure semantics, but with no output schema or annotations it does not specify the return structure beyond 'provider_errors' and the 'equivalent' view. The parameter ambiguity also prevents the tool from being fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It indirectly hints that 'path' points to a local export/config, but it says nothing about 'base_currency' or the exact expected input format, leaving the parameters largely underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a clear, specific account of the resource and behavior: a hidden-exposure theme/driver rollup for a local export/config, with classification logic for stocks versus ETFs/certificates/bonds. The primary verb is implicit ('rollup' is used as a noun), and it does not explicitly name a sibling tool, so it stops just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies when the tool is useful: hidden-exposure analysis across unrelated sector labels using a local export. It adds a useful 'never a VaR substitute' warning, but it does not give explicit when-to-use conditions or name an alternative tool to use instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It usefully discloses that unknown currencies yield null, which is an important edge case. However, it does not mention output precision, invalid amount handling, or whether the latest ECB rate is always used.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence containing both the core purpose and a key edge case. Every word carries useful information, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two simple scalar parameters and no nested objects, the description covers the main action and one important edge case. Since there is no output schema, it could state the success return format, but the tool's name and purpose make that reasonably inferable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needed to compensate, but it adds no parameter-level detail beyond the obvious names 'amount' and 'currency'. It does not specify currency code format (e.g. ISO 4217) or any constraints on the amount.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('convert'), resource ('amount'), target currency ('EUR'), and rate source ('ECB reference rate'). This clearly differentiates it from sibling fx_rates, which would provide raw rates rather than perform a conversion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied: use this tool when an amount should be converted to EUR using ECB rates. However, it does not explicitly contrast with alternatives like fx_rates or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so well: it discloses the fallback to config/portfolio.example.yaml, the `is_example` flag, the expectation to warn the user, and the rule never to invent numbers. This is exactly the behavioral context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized: three sentences, with the core function front-loaded. The fallback caveat is verbose but necessary; it earns its place because misusing example data would be a serious error.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the source file, fallback behavior, and a critical safety rule, which are the most important runtime aspects. It is incomplete, though, because the `path` parameter is undocumented and no output schema exists to clarify the return shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one optional `path` parameter with 0% description coverage, and the tool description never mentions `path` at all. The agent receives no guidance on what the parameter does, whether it overrides the default file, or what values are acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Load') and points to a concrete resource ('config/portfolio.yaml'), then enumerates exactly what is loaded: targets, fees, risk_limits, and rebalancing rules. This makes the tool's function unmistakable and distinguishes it from the portfolio-analysis siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (whenever these config values are needed) and gives a clear caveat about the example-file fallback. However, it does not name alternative tools or explicitly state when not to use this tool, so usage guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It clearly discloses deterministic behavior, no forecasts, and no execution, which are the main side-effect/safety traits. It does not mention any persistence/errors, but the output contents are enumerated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense sentence, front-loaded with the purpose and followed by a compact list of deliverables plus two short exclusions. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter tool with no output schema and no annotations, the description gives a helpful high-level picture but leaves parameter semantics and selection context under-specified. It is functional but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 10%. The description does not explain most of the 10 parameters; 'fee-aware contribution cadence' hints at fee params but cash_now, start_date, rebalance_band_abs, review_every_months, etc. are left to name inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Turn four rookie answers into a deterministic plan', then enumerates exactly what the plan contains. 'No return forecast' and 'Nothing is executed' sharply delimit it from forecast and execution siblings like backtest_plan and generate_order_plan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies the tool is used after four rookie answers exist and contrasts with execution/forecast tools, but it never explicitly says when to prefer this tool over siblings or names alternatives. The guidance is inferable, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 determinism, data source tiers, the reason for the EU27_2020 unemployment default, and the critical edge case: the regime is 'unknown' when either HICP or the deposit rate is missing, and it is 'never guessed'. This adds meaningful behavioral context beyond a simple summary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose ('Deterministic macro regime read'), followed by necessary data-source details and a clear statement of the unknown condition. Every sentence contributes value with no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description thoroughly explains the regime logic and data inputs, but with no output schema available, it leaves the return structure unspecified. An agent cannot tell whether the tool returns just the regime label or also the underlying HICP, unemployment, and deposit rate values. This gap matters for a data-returning tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds a small amount of extra context, such as why unemployment_geo defaults to EU27_2020 and that geo pertains to HICP, but it doesn't introduce new parameter format or syntax guidance beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Deterministic macro regime read' followed by the exact data inputs (HICP, unemployment, ECB deposit facility rate) and the output classification (restrictive/neutral/accommodative/unknown). This clearly differentiates it from the sibling tools, none of which overlap with macro regime determination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: whenever a macro regime read based on HICP, unemployment, and the deposit rate is needed. However, it does not explicitly state when not to use it or name alternative tools for other macro queries. Usage context is inferable but not explicitly framed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It clearly discloses the key trait that no online broker access occurs, and 'parse and normalize' implies a non-mutating, read-only local operation. It does not cover error handling or return behavior, but the offline guarantee is highly valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. The primary action is front-loaded, and the important offline constraint immediately follows.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple two-parameter parse tool, but with no output schema and no annotations, it leaves gaps around the return shape and the role of base_currency. An agent can make a reasonable call, but not with full certainty about expected output semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: only 'path' is documented, while 'base_currency' has no explanation. The tool description does not mention base_currency or clarify how normalization uses it, so it fails to compensate for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb pair ('Parse and normalize') with a clear resource ('local broker portfolio export'). It also distinguishes itself by explicitly stating it never accesses brokers online, which sets it apart from online data-fetching siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this is for local export files, not live broker access. The explicit 'Never accesses any broker online' acts as an exclusion, though it does not name specific alternative tools for online scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and largely meets it: it discloses that BUY orders are generated via allocate_cash, SELL orders appear only under sell_proposals when allow_sells=True, the BUY-order key is unaffected by allow_sells, and nothing executes a trade. It does not explicitly state whether any state is persisted or whether the function is otherwise side-effect free, but the main behavioral risk is addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The three-sentence description is front-loaded with the most important concept and each sentence carries distinct value: algorithm, policy order, and output behavior. It is dense but still readable, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 8-parameter tool with no output schema and no annotations, the description covers the high-level algorithm, sell behavior, and non-execution, but it does not explain the full return shape, fee calculations, or parameter units. An agent can get a good idea of what the tool does but not every fact needed for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning for allow_sells and the cash/band logic, but schema coverage is only 38% and fee parameters (fixed_fee_eur, variable_fee_pct, max_fee_ratio) and rebalance_band_abs are left mostly to inference from their names. It partially compensates for the low schema coverage but not enough to fully explain all 8 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-plus-resource framing ('Cash-flow-first rebalancer') and explains the exact behavior: new cash buys underweight buckets first, with optional sell proposals. This clearly separates it from nearby siblings like allocate_cash or generate_order_plan and states that no trade is executed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete invocation guidance: use cash first, suspend overweight buys, buy underweights, and only sell as a last resort; it also states when allow_sells=True is needed. It does not explicitly list when to choose an alternative tool, but the CLAUDE.md ordering and allow_sells condition provide clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses determinism, the Yahoo tier B baseline, SEC tier A overrides, the exclusion rule when sources disagree without a tiebreaker, and that provenance/evidence fields capture the reconciliation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with no filler. The core output is front-loaded, and every clause adds a meaningful behavioral rule about data hierarchy, overrides, exclusions, or response contents.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers the tool's data sources, scoring behavior, override logic, and key return fields (score, confidence, provenance, evidence) even without an output schema. Minor gaps remain around explicit parameter usage and edge-case behavior, but the core context needed to invoke the tool sensibly is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions and the description never explicitly mentions 'ticker' or 'cross_check_sec'. The SEC override discussion indirectly hints at cross_check_sec's purpose, but the toggle itself is left undocumented and ticker format/expected values are not clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific deliverable: a deterministic stock score (0-100) plus confidence, derived from public data. This distinguishes it from sibling screening/discovery/ranking tools by focusing on a single-stock scored analysis with a concrete numeric scale.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when a deterministic scored assessment of a stock is needed. However, it does not explicitly name alternatives like screen_stocks, rank_candidates, or discover_stocks, nor does it state when not to use this tool in favor of those siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It explains that the tool uses a fresh Yahoo/SEC snapshot, refuses to invent a thesis by raising, and returns the new check, previous status, and a qualitative delta. It does not mention potential side effects or rate-limit behavior, but the core behavior is well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler: the first states the core action, the second adds a critical failure guardrail, and the third describes the return values. Key information is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives enough to call the tool with the required symbol and understand the main result, but it omits operational details such as acceptable as_of formats, the exact effect of cross_check_sec, and the precise shape of the returned check. Since there is no output schema and no annotations, these gaps make it not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the prose must compensate. It indirectly gives meaning to symbol via save_thesis, to as_of via 'fresh market snapshot', and to cross_check_sec via 'audited SEC facts when available'—but it never explicitly names or maps these parameters, leaving an agent to infer the optional behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: it evaluates a stored thesis's falsifiers against a fresh market snapshot. It differentiates from siblings by referencing save_thesis as the source of the thesis and analyze_stock for SEC facts, so an agent can tell what this tool uniquely does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the prerequisite—a thesis must already have been saved via save_thesis—and warns that the tool raises otherwise. It also points to analyze_stock for the SEC-facts behavior, but it does not explicitly contrast when to choose check_thesis over analyze_stock or other siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does substantial work: it discloses the inputs blended (analyze_stock score/confidence, holdings exposure, saved thesis status), the decision taxonomy, and the fee-aware rotation constraint. It does not explicitly state whether orders are executed or only proposed, but 'Returns ... order(s)' and the tool name imply a proposal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core question, followed by the decision output and a policy caveat. Every sentence carries useful content and there is no filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, no annotations, and no output schema, the description covers the core selection logic and return categories but leaves gaps around side effects, exact semantics of numeric parameters, and when to prefer this over related planning/order tools. It is adequate for invoking with defaults, but not fully complete for this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning for current_symbol, candidate_tickers, holdings, and fee-aware reasoning, which partially compensates for the very low schema coverage. However, it does not explain cash_utility, min_improvement, max_fee_ratio, max_roundtrip_fee_ratio, current_value_eur, or the fee parameters individually, leaving several optional parameters underspecified for an agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific decision question — whether current_symbol still deserves its slot versus candidates or cash — and closes with the concrete outputs HOLD/REPLACE/SELL_TO_CASH plus fee-aware orders. This clearly distinguishes it from broader portfolio tools like rebalance_portfolio or generate_order_plan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use this when evaluating a single current holding against candidate tickers or cash, with utility based on analyze_stock scores, hidden exposure, thesis status, and fees. It does not explicitly name sibling tools or provide when-not-to-use guidance, but the use case is not ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it does so well: it discloses the free pricing provider, the refusal behavior under 10 decisions, and the conditional opportunity section. It does not cover failure modes or data limitations, but the key guardrail and conditional behavior are clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loads the core purpose with 'Shadow portfolio'. Each sentence adds distinct information: the comparison method, the reported metrics and minimum sample guardrail, and the conditional opportunity section. It is slightly dense but every clause contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description usefully summarizes the outputs: mean decision alpha, hit rate, and an opportunity section. It also explains the precondition on candidate-logged decisions. It misses explicit guidance on empty results or price provider failures, but the core calling context is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 0%, the description defines min_days by saying decisions older than min_days are reviewed, which gives the parameter meaningful semantics beyond the bare schema field. It does not specify bounds or edge cases, but for a single integer with a default this is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific operation: compare logged decisions against their recorded alternatives at today's prices, and report decision alpha and hit rate. The 'Shadow portfolio' framing clearly distinguishes it from generic review or quality tools in the sibling list, even though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied rather than explicit: it applies to logged decisions older than min_days and requires at least 10 decisions before drawing conclusions. No alternatives or exclusions are mentioned, so an agent must infer when to choose this over siblings like backtest_plan or decision_quality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides useful behavioral context: it discloses data-dependent coverage, names specific free-data sources, and flags the V1 limitation. It doesn't mention side effects, auth, or rate limits, but the read-only nature is implied by 'analyze/rank'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences and front-loads the main action. The internal method reference ``_enhance_snapshot_with_free_data`` is implementation noise that could be dropped without losing functional guidance, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema covers return values, and the description covers purpose, data dependencies, and a key alternative. However, the min_score parameter is entirely undocumented, so an agent cannot fully utilize the tool's filtering capabilities. It's suitable for basic invocation but not for confident parameter-driven use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero descriptions for both parameters. The description only indirectly explains tickers as a 'ticker universe' or 'ticker list', and it never mentions min_score at all. An agent cannot understand how to use min_score or what filtering it applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('analyze and rank') and resource ('explicit ticker universe'), and explicitly differentiates from discover_stocks by noting that V1 requires a ticker list rather than scraping the whole market. It also clarifies that every ticker is scored, with data-driven caveats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly points to discover_stocks as the alternative when market-wide scraping is desired, and communicates that this tool is for a pre-specified ticker universe. This gives a clear when-to-use versus when-not-to-use distinction, though it doesn't mention other siblings like analyze_stock.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden and does so richly. It explains key behaviors: scoring via analyze_stock, the 0.5 confidence veto, diversification-driven fit calculation, thesis-based utility discounts, and the fact that it only suggests and never executes. This gives an agent a strong mental model of what the tool does and its limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and relatively long, but every sentence adds substantive detail about the algorithm, data sources, or constraints. It front-loads the main purpose before diving into mechanics. It could be tightened, but the complexity of the tool justifies most of the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with no annotations and no output schema, the description is remarkably complete. It covers the ranking logic, input sourcing, candidate scoring, confidence threshold, diversification preference, thesis handling, and safety limitation. The only notable omissions are explicit return format and full parameter details, but the behavioral core is thoroughly specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It clearly explains cash_eur as the new cash to allocate and implies path refers to the local export used for bucket values, but base_currency is never mentioned and candidate_tickers is only indirectly tied to 'candidate stocks.' The description partially clarifies the parameters but leaves meaningful gaps for a 4-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's specific action: ranking every use of new cash and allocating cash_eur to the highest marginal utility winners. It also distinguishes the tool by noting it is suggestion-only and never sends an order, which separates it from execution-oriented sibling tools. This is a specific verb+resource statement with clear scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides substantial context about the tool's internal logic and constraints, implying it is for cash allocation suggestions driven by marginal utility. However, it does not explicitly state when to use this tool versus alternatives like allocate_cash or rank_candidates, and the only exclusion is indirect: 'never sends an order.' This is implied usage guidance rather than explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses a crucial limitation (cannot separate market-move contributions) and requires reading the returned 'note' before interpreting numbers as gain/loss. It does not spell out edge-case behavior like missing snapshots or exact response shape, so a 5 is not warranted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: purpose, output scope, limitation, and a required instruction are all included. The warning is placed at the end but clearly linked to interpretation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description conveys the essential return semantics (total and per-holding/per-bucket change) and flags the critical 'note' field. A little more detail about error/edge cases would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters, including the newer default. The description adds the useful semantic 'value change since older' but does not need to restate parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: 'Diff two stored monthly snapshots,' and names the exact function path portfolio.snapshots.diff_snapshots. It also states the output scope (total and per-holding/per-bucket value change), which distinguishes it from sibling save/list snapshot tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use case is clear: compare two stored monthly snapshots to see value change since an older date. It does not explicitly name alternatives or exclusions, but the sibling set contains only save/list/other analysis tools, so when this tool applies is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. It discloses the data source (data.sec.gov), the free tier A access, the best-effort heading-scan extraction, the guarantee that text is never invented, and the failure mode returning ok=False with a readable reason. This is meaningful behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It front-loads the core purpose and then adds relevant caveats about failure modes and extraction quality in a compact, readable way.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter tool with no output schema and no annotations, the description covers the essential context: what the tool does, where data comes from, what can go wrong, and how failures are signaled. It would be stronger with explicit mention of the success return shape, but the provided information is largely sufficient for an agent to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low at 33%, so the description must compensate. It does add useful meaning by explaining 'form' via examples like 10-K and 20-F and by linking 'ticker' to CIK lookup. However, it does not fully document accepted form values, ticker formatting, or the exact behavior of the items parameter beyond the schema's own minimal description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: extracting item-section text from the most recent SEC filing of a given form for a given ticker. This is a concrete verb+resource pair that distinguishes it from siblings like company_facts or insider_activity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when the tool applies: retrieving specific sections from a ticker's latest SEC filing of a specified form. It gives a concrete edge case with foreign private issuers filing 20-F instead of 10-K and explains the ok=False failure behavior, though it does not explicitly name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description appropriately discloses the mutating nature ('Persist (create or update)') and a key behavioral detail: 'Upserts by uppercased symbol'. It also situates the action in a workflow. It could add what happens to existing thesis history on update, but the core side-effect and normalization behavior are clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences with no filler. The action and subject are front-loaded, followed by the schemas-relevant content and then the timing guidance. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description is largely complete: it defines the data shape, the persistence behavior, the symbol normalization, and the intended workflow context. It does not describe return values or error cases, but these are less critical for a straightforward upsert tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers the single 'thesis' parameter thoroughly, including its nested structure and example fields, so schema coverage is 100%. The description adds some context around 'falsifiers' and symbol uppercasing, but does not need to compensate for missing schema information. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Persist'), names the resource ('a symbol's investment thesis'), and explains exactly what the thesis contains ('claims made at BUY time plus concrete, checkable falsifiers'). It also references check_thesis and mentions the post-BUY workflow, which helps distinguish it from decision-logging and thesis-checking siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'call this right after log_decision on a BUY'. It also explains the purpose of that timing ('so the thesis can later be checked against fresh data'). It does not explicitly state when not to use it or name alternative tools beyond check_thesis, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of revealing behavior. It discloses that snapshots are local-only, git-ignored, stored under data/private/snapshots, and returned oldest first. This is useful context, though it does not explicitly state that the operation has no side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient, front-loaded sentence that covers the resource, scope, storage details, and ordering without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter listing tool, the description is complete: it states what is listed, where the data comes from, and the output ordering. No output schema exists, but the expected content is clear enough for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description has no parameter semantics to add. The baseline of 4 applies because there is nothing for the description to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (stored monthly snapshot dates), the storage location, and the ordering of results. It also implicitly distinguishes this tool from siblings like save_portfolio_snapshot and compare_snapshots by focusing on listing what exists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: to enumerate available snapshot dates. However, it does not explicitly state when not to use it or point to alternatives such as compare_snapshots or save_portfolio_snapshot, so the usage guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers rich detail: the exact matching order, the dependency on two configuration sources, and the edge-case treatment of certificates, leveraged instruments, and single stocks as satellite positions that are never silently dropped. This goes well beyond what a bare schema would convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences with no filler. The core action and matching logic are front-loaded, and each additional clause adds meaningful operational detail such as source configuration, satellite treatment, and downstream integration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the matching algorithm, data sources, edge-case handling, and downstream compatibility, which is substantial for a tool with no annotations and no output schema. The main missing piece is a clearer contract for the parameters, especially base_currency, and more explicit detail about the result structure beyond 'current_values'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters, but it only indirectly references 'path' through 'local export' and never explains 'base_currency' or accepted formats. While the algorithm details are helpful, they do not clarify what values the two parameters actually take.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: mapping every holding in a local export to target allocation buckets. It also specifies the matching strategy ('by ISIN then by name keywords'), which clearly distinguishes it from sibling tools like parse_portfolio_export or rebalance_portfolio that fill different roles in the same workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains how the tool fits into a larger workflow: it uses get_portfolio_config() targets and config/model_portfolios.yaml, and its 'current_values' output plugs directly into rebalance_portfolio/allocate_cash. It does not explicitly state when not to use it or name alternatives, but the downstream integration strongly implies the intended usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses return behavior for misses, guarantees no invented tickers, states that the rate limit is respected, and specifies that persistent HTTP failures raise a ToolError rather than silently returning nothing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and remains readable despite packing in use context and failure behavior. Minor redundancy around 'free/keyless/tier A/no signup' keeps it from being maximally tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a stateless mapping tool with no output schema, the description covers success behavior, miss behavior, rate limiting, and error handling. It could more explicitly state the concrete return structure, but the key invocation concerns are addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only exch_code has a schema-level description, leaving isins under-documented. The description adds general mapping context but does not specify ISIN input format, list constraints, or the exact return container, so it only partially compensates for the 50% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The definition clearly states the tool maps ISINs to tickers via the OpenFIGI API and explains the broker-export use case. It frames the output as a yfinance-style ticker needed by downstream tools, distinguishing it from related portfolio tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit condition for use: when a broker export identifies a holding only by ISIN and another tool needs a ticker. It does not explicitly say when not to use this tool or name alternative ISIN-resolution options, so it has clear context but no exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly: it discloses data sources and tiers, data limitations (US-listed/ADR only, US filers only), methodological caveats (survivorship bias, backfill risk, no transaction costs), missing-data handling, and guaranteed `disclosures` output. This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded with purpose and the critical 'not production' caveat. Every sentence adds value, though it is verbose in places with repeated qualification and could be lightly tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with no output schema and no annotations, the description covers purpose, data pipeline, strategy, limitations, and output disclosures well. However, it does not explain the `years` and `horizon_months` parameters or the full return-value shape beyond `disclosures`, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It gives context for `tickers` ('for each ticker') and `benchmark` ('against `benchmark`'), but `years` and `horizon_months` are not explained at all. The parameter semantics are only partially covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific resource and action: a proxy backtest of the picker's ranking logic via portfolio.picker_backtest. It explicitly differentiates itself from the production scorer (scoring/engine.py), making the tool's purpose clear and distinguishable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the intended question ('would this ranking logic have beaten the benchmark on past data') and explicitly says it is NOT the production scorer. This gives agents clear when-to-use and when-not-to-use guidance, including a reference to the production alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure — and it does so well. It reveals that this is discovery-only, that nothing is excluded by size/index/overlap, that Finviz numbers never enter the score, that later size/sector/overlap tags are informational only, and that it operates on public pages with tier C and no account.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the use case and then compresses the mode distinction, exclusion policy, follow-up requirement, and tag-interpretation rule into a few dense sentences without filler. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, it covers the essential context: user intent, data source (Finviz), modes, inclusion/exclusion behavior, account tier, and required downstream tools. It does not explicitly describe the return format or pagination, but the discovery purpose is clear enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, and the input schema already provides detailed descriptions for mode, sizes, preset, styles, and per_screen. The description adds only minor extra context (e.g. preset being bounded by limit), so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens by framing the tool as the 'Discovery step' for the 'I have no idea what to buy' use case, which is a specific and identifiable purpose. It clearly distinguishes itself from scoring/analysis siblings by stating that every candidate 'must be re-scored with rank_candidates/screen_stocks/analyze_stock' and that Finviz numbers never enter the score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states when to use this tool (initial discovery when the user has no idea what to buy), explains the two modes ('universe' vs 'preset'), and gives follow-up alternatives. It does not explicitly spell out when not to use it, but the discovery-only framing and direction to re-score provide strong contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden, and it handles it well: it discloses the data source (SEC EDGAR), the free/tier A nature, the limitation that shares/price/direction are unavailable, and that the limitation is surfaced in the result. It does not describe request/response mechanics, but the key behavioral trap is fully exposed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense sentence that front-loads the core behavior and includes only high-value caveats. Every clause earns its place: source, cost tier, scope, and the critical limitation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter count tool with no output schema, the description covers what is computed, the input semantics, and the main limitation. It could add an explicit return-shape line, but nothing essential to selecting and invoking the tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema gives only names, types, and a default, while the description adds the essential semantics: 'days' is a trailing window and 'ticker' is the symbol being queried. It does not describe ticker formatting or valid day ranges, but it provides enough context for a correct first call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific operation and resource: counts of Form 4/4-A filings in a trailing days window for a ticker. It also explicitly distinguishes the tool from a buy/sell tally, so an agent cannot confuse it with transaction-level insider tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description frames the tool as an 'insider-paperwork activity signal' and explicitly warns that transaction XML is not parsed, giving a clear when-not use case. It stops short of naming alternative sibling tools for buy/sell detail, so routing guidance is good but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so well. It discloses constraints up front: respects robots.txt, never logs in, never executes JavaScript, and never bypasses a paywall. This gives an agent accurate expectations about limitations and safety without relying on structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences front-load the core operation and then list the key constraints. There is no filler, and every clause adds a distinct fact (source, Tier A scope, robots/paywall restrictions).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter, no-output-schema tool, the description is nearly complete: it covers source, scope, and behavioral limits, and implies the returned classification categories. It does not explicitly describe the return shape or failure behavior, but that is not necessary for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required string parameter 'ticker' with 0% description coverage, and the description does not add ticker-format or source-exchange detail. The parameter is nonetheless self-explanatory in context (the tool resolves it via yfinance), so the omission is a minor gap rather than a serious one.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise operation ('Find and classify a company's investor-relations page'), specifies the source ('its public website (yfinance's `info.website`)'), and enumerates the content categories covered (annual/quarterly reports, earnings releases, guidance, presentations, press releases). The 'Tier A: the company's own site' qualifier separates it from filing- or data-tool siblings without requiring the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for when to use it: for a company's own-site IR page sourced from yfinance's website field, and only within Tier A scope. It does not explicitly name alternatives or state 'use this instead of...', so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to lean on, the description carries the full transparency burden and succeeds: it discloses that size/sector/index overlap never filters, that top_n only limits returned ideas while summary stats include all scored tickers, that min_confidence only adds a tag, and that `path` is never used to filter. It also flags that screening errors are reported separately in `screening_errors`. This is unusually thorough behavioral disclosure for a ranking tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded, opening with the core action and then layering constraints. Every sentence contributes: scope, non-filtering behavior, risk-cap context, and top_n semantics. It is longer than average, with repeated 'never' emphasis and internal references like 'portfolio.picker.annotate' and 'portfolio.exposure,' but these earn their place by preventing common misuse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description covers the essential context: input source, parameter roles, ranking scope, returned `ranked` ideas, `screening_errors`, summary stats, and portfolio-tag behavior. It does not detail the ranking formula or exact output structure, but it gives enough for an agent to invoke and interpret the tool correctly. The main gap is that it never confirms whether the operation is purely read-only, though the language strongly implies it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: `path` and `min_confidence` have schema descriptions, while `tickers` and `top_n` do not. The description compensates by explaining that tickers are the screen_stocks list and that top_n bounds only how many ranked ideas are returned in `ranked` rather than affecting the ranking or summary stats. It adds meaningful semantics beyond the bare schema, though it could have been even more explicit about tickers' format and top_n's range.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource pair: 'Score every ticker in `tickers` and rank the WHOLE set by potential.' It also explicitly differentiates itself from filtering tools by stating that nothing is excluded for size, sector, or index overlap, and it references its input source (screen_stocks). An agent can clearly tell what this tool does and how it is distinct from sibling screening/filtering tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it operates on tickers from screen_stocks, uses `path` only for portfolio-exposure tagging, and notes that a later red-team pass or the caller's risk caps are the intended downstream limits. However, it never explicitly names alternative tools or states when this tool should not be used, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description fully discloses key behaviors: the snapshot is stored under portfolio.snapshots/data/private/snapshots, is git-ignored, uses a specific mapping and target preference, and refuses to overwrite without force=True. This gives the agent a solid understanding of side effects and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every clause adds value: purpose, storage location, mapping behavior, target preference, and overwrite protection. It is front-loaded with the core purpose and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write-side snapshot tool with no output schema, the description covers the essential aspects needed to select and invoke it: what it does, where data goes, how mapping behaves, and how overwriting is handled. It is sufficiently complete for an agent to act correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3 and the schema documents all three parameters. The description adds limited parameter-specific meaning beyond the schema, mostly clarifying behavioral details rather than the parameters themselves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: freezing a local export into a dated monthly snapshot at a specific location. It also distinguishes itself from related siblings by noting it maps holdings the same way as map_holdings_to_targets and prefers investment_plan.json targets over get_portfolio_config's.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys when to use the tool: before a later check-in to measure what actually changed rather than re-deriving unrecorded history. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to infer the appropriate use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![portfolio-copilot MCP server](https://glama.ai/mcp/servers/lodetomasi/portfolio-copilot/badges/card.svg)](https://glama.ai/mcp/servers/lodetomasi/portfolio-copilot)

Score Badge

Copy to your README.md:

[![portfolio-copilot MCP server](https://glama.ai/mcp/servers/lodetomasi/portfolio-copilot/badges/score.svg)](https://glama.ai/mcp/servers/lodetomasi/portfolio-copilot)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lodetomasi/portfolio-copilot'

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