The Chart Library MCP Server gives AI agents access to 25M+ historical chart pattern embeddings across 19K+ stocks (drawn from 800M+ minute bars), enabling retrieval of empirical forward-return distributions — not predictions.
Core capabilities:
Search for similar chart patterns (search_charts): Find historically similar charts for a given ticker and date, with match scores and similarity distances.
Get forward return analysis (get_follow_through): See what actually happened 1, 3, 5, and 10 days after historical matches, including percentage returns and cumulative paths.
All-in-one pattern analysis (analyze_pattern): Combine search, forward-return statistics, outcome distributions, and an AI-generated summary in a single call.
AI-written pattern summaries (get_pattern_summary): Plain-English summaries of pattern search results, including match count and forward return statistics.
Daily top picks (get_discover_picks): Retrieve the most interesting patterns from a nightly scan, ranked by interest score with confidence scores and predicted returns.
Batch search (search_batch): Search for patterns across up to 20 symbols simultaneously, with forward return statistics for each.
Refined analysis with filters: Apply market regime, sector, liquidity, or event-based filters to refine results; get anomaly detection, volume profile analysis, crowding assessment, correlation shifts, earnings reaction analysis, and pattern degradation insights.
Portfolio-level analysis: Understand aggregate conditional return distributions across holdings and identify tail risk contributors.
Situational market data: Access ticker metadata, current market regime, sector rotation insights, and point-in-time regime data.
Database status (get_status): Check total embeddings, coverage, date range, and symbol count.
Feedback reporting: Submit feedback or suggest improvements.
Legacy tools are supported for backward compatibility, mapped to the canonical toolset.
Enables GitHub Copilot to retrieve historical stock chart patterns and forward return statistics via @mcp commands, supporting tools for search, cohort analysis, and scenario testing.
Works with: Claude Desktop | Claude Code | ChatGPT | GitHub Copilot | Cursor | VS Code | Any MCP client
Cohort intelligence engine for stock chart patterns — give your AI agent the cohort of historical analogs, the full forward-return distribution, and the features that separated winners from losers. Calibrated, methodology-honest, no overstated confidence.
📖 What is cohort intelligence? · 🛠️ Full MCP setup guide · 🤖 Build an AI trading agent with Claude
25M+ pattern embeddings. 10 years of history. 19K+ stocks. One tool call.
> "What does NVDA's chart on 2024-08-05 1h look like historically?"
NVDA · 2024-08-05 · 1h — cohort of 500 historical analogs
(485 with realized 5-day returns)
Distribution at 5 days forward:
median: −1.3%
p10 ·· p90: −11.3% ·· +6.8% (80% empirical band)
win rate: 44%
cohort_score: 0.31 (modest)
Features that separated winners from losers:
+ credit_spread_state = tight
+ macro_state = bullish
+ pct_off_52w_low (further off)
− vol_regime = low
Summary: NVDA's 1-hour pattern on 2024-08-05 has 500 historical
analogs. The cohort's 5-day distribution is bearish-leaning
(median −1.3%, win rate 44%) — the historical record does NOT
show this pattern typically resolving bullish. Conditioning on
tight credit spreads and a bullish macro state would have
separated the outperformers within the cohort.A retrieval, not a forecast. No hallucinated predictions. No cherry-picking. Just the empirical record your agent can cite.
pip install chartlibrary-mcpDownload the chart-library-6.1.0.mcpb extension file and open it with Claude Desktop for automatic installation.
claude mcp add chart-library -- chartlibrary-mcpAdd to claude_desktop_config.json:
{
"mcpServers": {
"chart-library": {
"command": "chartlibrary-mcp",
"env": {
"CHART_LIBRARY_API_KEY": "cl_your_key"
}
}
}
}Add to .cursor/mcp.json or VS Code MCP settings:
{
"servers": {
"chart-library": {
"command": "chartlibrary-mcp",
"env": {
"CHART_LIBRARY_API_KEY": "cl_your_key"
}
}
}
}Add to .vscode/mcp.json in your project (this file is already included in the chart-library repos):
{
"servers": {
"chart-library": {
"command": "chartlibrary-mcp",
"env": {
"CHART_LIBRARY_API_KEY": "cl_your_key"
}
}
}
}Copilot Chat will auto-detect the MCP server when you open the project. Use @mcp in Copilot Chat to invoke tools.
ChatGPT connects to MCP servers via remote HTTP endpoints. To set up:
Enable Developer Mode: Go to ChatGPT Settings > Apps > Advanced settings > Developer mode (requires Pro, Plus, Business, Enterprise, or Education plan)
Create a connector: In Settings > Connectors, click Create and enter:
Name: Chart Library
Description: Historical chart pattern search engine — 25M+ patterns across 19K+ stocks, 10 years of data
URL: https://chartlibrary.io/mcp
Authentication: No Authentication (or OAuth if using an API key)
Use in conversations: Select "Developer mode" from the Plus menu, choose the Chart Library app, and ask questions like "What does NVDA's chart look like historically?"
Note: The remote endpoint at
https://chartlibrary.io/mcpuses Streamable HTTP transport. If you need SSE fallback, usehttps://chartlibrary.io/mcp/sse.
For any MCP client that supports remote HTTP connections:
https://chartlibrary.io/mcpThis endpoint supports both Streamable HTTP and SSE transports, no local installation required.
Free tier: 200 calls/day, no credit card required. Get an API key at chartlibrary.io/developers or use basic search without one.
Related MCP server: TickerAPI
> search(query="TSLA") → cohort_id
> explain(cohort_id=..., style="position_guidance")
Signal: HOLD
Of the historical analogs to this setup, those that exited early
avoided a drawdown 3/10 of the time; those that held gained a
further +2.1% median over the next 5 days. No exit signal triggered
— the cohort's record leans toward continuation, not reversal.> context(target="market")
Sector relative strength (30-day):
Leaders: XLK Technology +4.2% · XLY Cons. Disc. +3.1% · XLC Comm. +2.8%
Laggards: XLU Utilities −1.4% · XLP Cons. Staples −2.1% · XLRE Real Estate −3.3%
Regime: Risk-On (growth > defensives), SPY above 20d, VIX mid-band.> search(query="AMD 2024-06-18") → cohort_id
> cohort_groupby(cohort_id=..., by="ctx_spy_trend_20d")
AMD's cohort, split by the SPY trend at each analog's date:
SPY weak (bottom quartile): median 5d −5.2% · p10/p90 −11.4%/+1.1% · 18% positive
SPY strong (top quartile): median 5d +2.6% · p10/p90 −3.1%/+8.4% · 61% positive
A distribution conditioned on the tape — historical analogs, not a beta forecast.Chart Library v6 exposes the same granular surface as the remote server at chartlibrary.io/mcp — so the pip package, the Claude connector, and the REST API all use the same tool names. The core loop is search → pull_comps → cohort_introspect. Chain tools via the comp_set_id / cohort_id handle for sub-second refinement without re-running kNN.
Tool | What it does |
| Entry point. Find similar historical patterns for an anchor; returns a comp-set handle you can chain. |
| The flagship. Pull the comp set for a subject |
| Same engine as |
| Slice/probe a stored comp set by ANY attribute (macro · technical · event) and get per-subset stats vs the full-cohort baseline. No kNN re-run. "Of the 300 analogs, how do the post-earnings-week ones do?" |
| Within-cohort winner/loser attribution — which member traits separated the forward-return tail from the rest, each with a by-date cluster-bootstrap CI and a false-discovery decision. Descriptive, never causal. |
| Historical predicted-vs-realized coverage of our calibrated bands (a track record, not a forecast). The nominal 80% band held 80.8% across 302,880 prior cases. |
| Layer 5 memory — per-symbol feature reliability + achieved calibration across prior analyses. Ground a read in whether a feature has historically been reliable for this ticker. |
| Analytic metrics. |
| Situational data. |
| Narrative + rankings derived from a cohort. |
| Multi-holding weighted conditional distribution. Runs per-holding cohorts in parallel, weight-averages the distributions, ranks tail contributors. |
| File an error or improvement suggestion back to the project. |
Full-cohort handover — hand the raw cohort back so you can bucket/sort by your objective, not our default lens:
Tool | What it does |
| The full cohort, one record per analog, with rich per-member metadata (forward outcomes, regime, anchor fundamentals, news, chart events). Slice and bucket it yourself. |
| Partition the cohort by one dimension ( |
| Reorder the cohort by a weighted composite of member fields you name (e.g. |
These tools replace hallucinated "on average this pattern returns X%" with real conditional base rates. The full distinction — what they do and how to read responses — is documented at /concepts/cohort-intelligence and /concepts/reading-a-cohort-response.
1. search(query="NVDA 2024-06-18") → comp_set_id
2. pull_comps(symbol="NVDA", date="2024-06-18",
filters={"vol_regime": ["high"]})
→ comp set: distribution + drivers
3. cohort_introspect(cohort_id=...,
where={"events.days_since_earnings": {"max": 5}})
→ how the post-earnings subset did
4. cohort_groupby(cohort_id=..., by="sector_etf") → outcome split by sectorv6 converges on the granular naming the live remote/connector surface already used. The v5 umbrella tools — cohort (depth=), discover (mode=), narrative (mode=), and decision_brief — are now deprecated but still callable, so existing code keeps working. cohort(depth="full") forwards to cohort_analyze. New agents should reach for the canonical tools above.
v5 umbrella call (deprecated) | v6 canonical |
|
|
|
|
|
|
|
|
`discover(mode="picks" | "daily_setups")` |
`narrative(mode="pulse" | "alerts")` |
The v4-era granular aliases (cohort_compare, decompose, clusters, live_search, similar_cohorts, anchor_fetch, narrative_pulse, narrative_alerts, discover_picks, get_daily_setups) remain deprecated-but-callable and forward to the canonical surface.
The v3-era tools (search_charts, get_cohort_distribution, analyze_pattern, etc.) were removed in v5. If your code still calls them, pin chartlibrary-mcp<5.0.0 until you migrate. The mapping:
Legacy (removed in v5) | Replacement |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Chart Library indexes a large library of historical chart patterns and exposes them behind a conditional-distribution API. Every query returns sample sizes, percentiles, and calibrated forward-return bands — never a point forecast.
When your agent calls search("NVDA") and chains cohort_analyze, the server:
Resolves NVDA's current chart state to a stored embedding
Retrieves the cohort of historically similar patterns
Looks up what happened over the following 1, 3, 5, and 10 days
Returns the calibrated distribution + a plain-English summary via Claude Haiku
The result: factual, citation-ready statements like "out of N similar historical patterns, the median 5-day return was X% (80% band [p10, p90])" that your agent can present without hallucinating or hedging.
Tier | Calls/day | Price |
Sandbox | 200 | Free |
Builder | 5,000 | $29/mo |
Scale | 50,000 | $99/mo |
Get your key at chartlibrary.io/developers.
export CHART_LIBRARY_API_KEY=cl_your_keyChart Library's privacy policy is published at chartlibrary.io/privacy and covers:
What we collect: account info (email when you create an account), usage data (search queries, features used), and device information (browser, OS, IP). API queries are stored for service operation and analytics.
How we use it: providing and improving the service, processing your searches, communicating about your account, and analyzing usage patterns.
Data sharing: we do not sell personal data. Operational service providers (hosting, analytics, payment processing) receive only what's necessary to provide the service.
Third-party services: queries may be processed by upstream providers (Polygon.io for market data, Anthropic for narrative summaries) under their own privacy policies.
Retention: account info while your account is active; usage data is anonymized or deleted periodically. You can request deletion at any time.
Security: encryption in transit and at rest. No method of transmission is 100% secure.
California rights (CCPA): right to know, right to delete, right to opt-out, non-discrimination.
Contact: support@chartlibrary.io for any privacy inquiry.
The MCP server itself sends only the arguments of your tool calls to chartlibrary.io (no local file or directory contents, no clipboard, no browser history). Your CHART_LIBRARY_API_KEY is sent only as a Bearer header to authenticate with the chart-library API.
Transport: all calls to the remote API are HTTPS (TLS 1.2+).
Authentication: optional API key passed as a Bearer header; the free Sandbox tier requires no key.
No write access to your environment, files, or other accounts. The single MCP tool that performs a write (report_feedback) only writes back to chart-library's own feedback inbox and never touches your system.
Report security issues to support@chartlibrary.io.
MIT. See LICENSE.
Chart Library provides historical pattern data for informational purposes. Not financial advice.
Analytic metrics on a cohort or (symbol, date) anchor.
metric values:
- "anomaly" — is the pattern unusual vs the symbol's
own history? (needs symbol)
- "volume_profile" — intraday volume vs historical norms
(needs symbol)
- "crowding" — cross-symbol crowding indicator
(market-wide; no symbol needed)
- "correlation_shift" — rolling correlation breakdowns
(extra_args: lookback, window, symbols)
- "earnings_reaction" — historical earnings gap reactions
(needs symbol; extra_args: min_gap)
- "pattern_degradation" — are signals losing edge vs historical
accuracy? (market-wide)
- "regime_accuracy" — win rates filtered by current regime
(needs symbol)
- "decompose" — find slice conditions that separated
winners from losers within a cohort
(needs cohort_id; horizon, max_slices,
explain_slices apply)
- "clusters" — cluster a cohort into k forward-return
groups (needs cohort_id; horizon, k)
Supply cohort_id (preferred, anchor inherited) OR explicit
symbol+date for the symbol-needing metrics.
Args:
metric: see list above
cohort_id: handle from `search` or `cohort` (required for
decompose, clusters; preferred for symbol-needing metrics)
symbol, date: explicit anchor when no cohort_id available
extra_args: per-metric optional kwargs (see metric list)
horizon: forward horizon in trading days (decompose, clusters,
regime_accuracy)
max_slices: max returned slice conditions (decompose)
explain_slices: include Haiku narrative tying slices together
(decompose)
k: cluster count override (clusters; default chosen automatically)
| Name | Required | Description | Default |
|---|---|---|---|
| metric | Yes | ||
| cohort_id | No | ||
| symbol | No | ||
| date | No | ||
| extra_args | No | ||
| horizon | No | ||
| max_slices | No | ||
| explain_slices | No | ||
| k | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, non-destructive, idempotent, and open-world hints. The description adds valuable behavioral context, such as the preferred use of cohort_id and the per-metric parameter needs. It does not mention output format (handled by output schema) or edge cases, but overall sufficiently complements the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear opening sentence, a bullet-list of metrics with needs, and a clean argument list. Every sentence adds value, and critical information is front-loaded. For a tool with 9 parameters and many metrics, this is an appropriate length with no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, various metrics, optional extra_args) and the presence of an output schema, the description is complete. It covers all metrics' prerequisites, parameter meanings, and the anchor vs cohort distinction. The output schema handles return format, so no further explanation needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description carries full burden. It explains every parameter in detail, especially the metric values (which are effectively enums but not in schema), the role of cohort_id versus symbol/date, extra_args per metric, and special parameters for decompose and clusters. This adds substantial meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides analytic metrics on a cohort or anchor, and enumerates all specific metrics with their requirements. This differentiates it from sibling tools that are more specialized, though the description doesn't explicitly compare. The verb+resource combination is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use cohort_id vs symbol+date, and which metrics need which parameters. It provides clear context but does not explicitly contrast with sibling tools like 'clusters' or 'decompose' that cover the same metrics. The guidance is thorough for the tool itself but lacks comparative direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[DEPRECATED in v5 — use context(target={"symbol": ..., "date": ...})]
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | ||
| date | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description does not need to repeat safety info. It adds the deprecation status, which is behavioral context, but does not disclose any other behaviors beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded with the deprecation notice, which is critical information. However, it lacks additional content that would be expected for a complete tool description, though it is appropriately sized for a deprecated tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and simple parameters, the description fails to explain the tool's purpose, parameter meanings, or return value. It only provides deprecation info, making it inadequate for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions in the schema. The description does not explain what 'symbol' or 'date' represent or how they affect the output. This leaves the agent with no semantic understanding of the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title mentions 'Anchor Metadata' and the description states it is deprecated, implying the tool fetches anchor metadata. However, it does not explain what anchor metadata is or how it differs from sibling tools, making it vague and indistinguishable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'DEPRECATED in v5 — use context(target={...})' and provides the alternative tool and its parameters. This gives clear guidance not to use this tool and directs to the correct replacement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[DEPRECATED in v5 — use analyze(metric="clusters", cohort_id=...)]
| Name | Required | Description | Default |
|---|---|---|---|
| cohort_id | Yes | ||
| horizon | No | ||
| k | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, nondestructive. The description adds deprecation status and redirection, which are critical behavioral traits not covered by annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, focused sentence that front-loads deprecation and provides the alternative. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deprecated tool, the description adequately redirects. Output schema exists for return values. However, it assumes knowledge of analyze and doesn't explain the deprecation reasoning or migration steps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It only hints at cohort_id via the alternative call, but ignores horizon and k entirely. Minimal value added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title 'Cluster Cohort' suggests clustering, and the description clearly states deprecation and redirects to analyze(metric='clusters'). It communicates the purpose effectively for a deprecated tool, though it doesn't explain what clustering does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states not to use this tool and provides the exact alternative: 'use analyze(metric="clusters", cohort_id=...)'. This is excellent guidance for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Conditional-distribution analysis — the Chart Library core primitive.
Three depth modes:
depth="basic" (default, fast ~50ms):
Returns kNN cohort + outcome distribution (p10/p25/p50/p75/p90,
win rate, MAE, MFE) + survivorship. Supply cohort_id (refine
prior cohort) OR query OR symbol+date.
depth="full" (Layer 3, ~280ms, paid tier):
Returns the basic outputs PLUS feature importance (which Layer 2
features separated winners from losers within this cohort),
regime stratification (outcomes sliced by vol/macro), risk
profile (drawdown / runup percentiles), cohort tightness
score, AND a deterministic `summary` block of classification
flags (verdict_class, edge_class, regime_alignment,
sample_quality, conviction, swing_factors with framings,
caveat_flags). Read `summary` first — paraphrase the framings
in your own voice rather than narrating the raw stats; cite
numbers in parentheses for support. `summary` is included
when `include_anchor_metadata=True` (the regime classification
needs the anchor's metadata). Requires symbol+date+timeframe
(cohort_id alone isn't enough — the Layer 3 analyzer needs
the full anchor).
depth="compare" (~400ms):
Compare TWO anchors' cohorts side-by-side. Pass symbol+date for
the primary AND compare_with={"symbol":..., "date":..., "timeframe":...} for the secondary. Returns both cohorts'
distributions plus a delta summary.
Filters (Layer 2 metadata constraints):
vol_regime: list of "low"/"mid"/"high"
macro_state: list of "bullish"/"neutral"/"bearish"
has_news: bool
days_since_earnings / days_since_ath / sector_rs /
realized_vol / relative_volume: dict with "min" / "max"
Empirical-distribution analysis only. Does NOT predict a single
point return; surfaces what historical analogs did and which features
separated them.
Args:
symbol, date, timeframe: anchor (default timeframe "1h")
query: alt to symbol+date, "SYMBOL YYYY-MM-DD"
cohort_id: refine a stored cohort (basic mode only)
depth: "basic" | "full" | "compare"
filters: Layer 2 constraints
horizons: forward horizons in trading days (default [5, 10] for
basic, [1, 5, 10] for full)
cohort_size: target K (10-2000)
compare_with: secondary anchor for depth="compare"
include_feature_importance, include_regime_stratification,
include_risk_profile: full-mode toggles
include_modes: full-mode only — when True, returns a `modes`
array clustering the cohort into K outcome playbooks (e.g.
"smooth uptrend +4.2%", "sharp downtrend -8.1%"). Each
entry has mode_id, label, n, median_return, win_rate,
std_return, p25/p75_return, and centroid_cum_returns
(sparkline-ready trajectory). Sorted ASC by median_return
so mode_id=0 is the worst realized cluster. Use for
"playbook" framing — the cohort isn't one outcome, it's
K distinct historical paths.
n_modes: number of modes to cluster into (2-6, default 4).
Adaptive: degrades to fewer modes if cohort_size is small.
exclude_same_symbol_days: drop same-symbol analogs within N
calendar days of the anchor (autocorrelation control;
default 10)
include_path_stats: include MAE/MFE/realized-vol (basic mode)
fields: full-mode only — optional allowlist of top-level
response keys to return. None (default) = full payload.
Valid: outcome_distribution, feature_importance,
regime_stratification, risk_profile, cohort_tightness_score,
cohort_score, combined_conviction, pulse_boost,
narrative_pulse, cohort_anchors, anchor_metadata. Use to
slim the JSON when you only need a subset (e.g.
fields=["outcome_distribution"] drops 97% of bytes).
anchor, cohort_size_actual, elapsed_ms, warnings are
always returned.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | No | ||
| date | No | ||
| timeframe | No | 1h | |
| query | No | ||
| cohort_id | No | ||
| depth | No | basic | |
| filters | No | ||
| horizons | No | ||
| cohort_size | No | ||
| compare_with | No | ||
| include_feature_importance | No | ||
| include_regime_stratification | No | ||
| include_risk_profile | No | ||
| include_modes | No | ||
| n_modes | No | ||
| exclude_same_symbol_days | No | ||
| include_path_stats | No | ||
| fields | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant context beyond the annotations (readOnlyHint, idempotentHint, etc.). It explicitly states the tool does NOT predict a single point return, but surfaces historical analogs. It details each mode's output, including the summary block and how to use it. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with headings for depth modes, filters, and args, and it front-loads the core purpose. While it is lengthy, every section provides necessary context for a complex tool. Minor redundancy could be trimmed, but overall it earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (18 parameters, 3 depth modes, optional features), the description is remarkably complete. It covers all modes, filters, optional toggles, and even explains how to use the summary block. The output schema exists, so it appropriately avoids explaining return values in depth.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates. It explains each parameter's purpose, defaults, dependencies, and constraints (e.g., query as alternative to symbol+date, compare_with structure, fields allowlist). The args section is structured and comprehensive, adding immense value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs 'conditional-distribution analysis' and is the 'Chart Library core primitive'. It explains three depth modes with specific outputs. The verb-resource combination is precise, and while it doesn't explicitly distinguish from sibling tools like cohort_analyze or cohort_compare, the detailed mode explanations effectively define its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each depth mode, including constraints for 'full' mode (requires symbol+date+timeframe) and 'compare' mode (requires compare_with). It also explains when cohort_id is appropriate. However, it does not directly compare with sibling tools, leaving some ambiguity about when to choose this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[DEPRECATED in v5 — use cohort(depth="full", ...)]
Layer 3 cohort intelligence. Forwarded to cohort(depth="full").
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | ||
| date | Yes | ||
| timeframe | No | 1h | |
| cohort_size | No | ||
| filters | No | ||
| horizons | No | ||
| include_feature_importance | No | ||
| include_regime_stratification | No | ||
| include_risk_profile | No | ||
| exclude_same_symbol_days | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true. Description adds that it forwards to cohort, which is a useful behavioral trait, but does not explain other behavioral aspects such as what happens with parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) and front-loads the deprecation warning. It is concise, but lacks detail about the tool's functionality, which is acceptable for a deprecated tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is deprecated and forwarded, the description provides enough context to avoid using it. However, it does not explain the tool's original purpose or how to invoke it if needed, which is incomplete for a non-deprecated context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no information about any of the 10 parameters, leaving their meaning entirely to the schema which lacks descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it is deprecated and forwards to cohort, but does not explain what 'Layer 3 cohort intelligence' means. The verb 'analyze' is present but no concrete action or resource is described, making it vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says deprecated and directs to use cohort(depth='full') instead. Clear when-not-to-use and alternative tool, providing excellent guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[DEPRECATED in v5 — use cohort(depth="compare", compare_with=...)]
| Name | Required | Description | Default |
|---|---|---|---|
| symbol_a | Yes | ||
| date_a | Yes | ||
| symbol_b | Yes | ||
| date_b | Yes | ||
| timeframe | No | 1h | |
| cohort_size | No | ||
| horizons | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds a deprecation warning, which is useful but does not provide additional behavioral context beyond what annotations offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short but at the cost of omitting essential information. While it is front-loaded with the deprecation notice, it does not earn its brevity because it leaves the agent without functional guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, 0% schema coverage, and an output schema, the description is completely inadequate. It only provides a deprecation directive and does not explain the tool's behavior, return values, or how to use the parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description provides no parameter information whatsoever. It only mentions the deprecation and alternative, failing to add meaning to any of the 7 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description does not state what the tool does; it only provides a deprecation notice directing to 'cohort(depth="compare")'. The purpose is implied by the tool name 'Cohort Compare', but the description fails to explicitly state the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent to use 'cohort(depth="compare", compare_with=...)' instead, which is a clear alternative. This provides excellent when-not-to-use guidance and a direct replacement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Situational data about a target.
target accepts four shapes:
- "market" (default): SPY/QQQ regime + sector rotation +
breadth + macro
- "SYMBOL" (e.g. "NVDA"): ticker metadata + sector + market cap
- {"symbol": "NVDA", "date": "2024-08-05"}: anchor metadata —
sector, cap, point-in-time regime, news, days_since_earnings,
etc. Lightweight; no kNN.
- "system": DB coverage stats (embedding count, daily bar count,
date range)
Args:
target: "market" | "SYMBOL" | {symbol, date} | "system"
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | market |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and no destructive behavior. The description adds meaningful behavioral detail: states returned data categories per shape, notes 'Lightweight; no kNN' for the object form, and clarifies data freshness constraints implicitly. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Structure is clear with a heading and bullet-like list, but the description is verbose, especially for the 'object' shape. Some redundancy exists in listing 'sector' and 'cap' across shapes. Could be tighter without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter with no schema description and an output schema (not shown), the description covers input usage exhaustively. It defines all four target variants and their implications. Missing a brief note on output format, but output schema handles that. Adequate for the complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has zero description coverage for the single 'target' parameter, leaving it completely opaque. The description fully compensates by explaining the four accepted shapes, their structure, and example values, making the parameter semantics crystal clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it provides 'Situational data about a target' and enumerates four distinct shapes (market, SYMBOL, object, system) each returning specific domain data. Differentiates from sibling tools like symbol_intelligence by focusing on market regime and anchor metadata rather than just ticker fundamentals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use each target shape and what each returns (e.g., 'market' for sector rotation, 'SYMBOL' for ticker metadata). Provides context for selection but does not explicitly exclude alternatives or contrast with siblings like 'symbol_intelligence' or 'anchor_fetch'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One-call decision-grade orchestrator. Use this as your DEFAULT first call for any (symbol, date) anchor question.
Composes cohort_analyze (depth=full) + anchor metadata + Layer 5 memory
(symbol_intelligence) + narrative pulse into a single structured brief.
── HOW TO TURN THIS INTO A GOOD ANSWER ──────────────────────────
Read `summary` first. It contains deterministic classification flags:
verdict_class: bullish | lean_bull | coin_flip | lean_bear | bearish | broken
edge_class: trivial | small | meaningful | large
regime_alignment: tailwind | neutral | headwind
sample_quality: thin | ok | strong
conviction: low | med | high
swing_factors: [ { factor, direction, framing } ]
caveat_flags: [ thin_in_regime_sample, regime_was_derived, ... ]
Paraphrase the `framing` strings in your OWN voice — do not quote them
verbatim. Cite the raw numbers in parentheses, don't enumerate every
structured field. Lead with the verdict, then the context, then the
swing factors as things to watch, then conviction.
Example (your voice may differ):
"Honestly, this NVDA setup is a coin flip. In-regime cohort (n=21)
printed +0.09% median over 5d (52% wins) — basically identical to
other regimes (+0.27%, 52%). Sector is lagging hard (-10.4 RS),
which is muting reads. Soft sample size — directional, not thesis."
── RESPONSE STRUCTURE ───────────────────────────────────────────
summary (read this first — see above)
current_regime (anchor's regime label + features)
cohort_total (all analogs, all regimes)
in_current_regime (subset matching the anchor's regime)
outside_current_regime (rest, weighted average)
conditional_edge (median_lift_pp + win_rate_lift_pp)
thesis_invalidation_triggers (top 5 features, narrative-ready with
interpretation strings — quote these
when explaining what would flip the read)
feature_importance (top 20 features ranked by within-cohort
importance, compact shape — use this
when the user asks about a specific
feature or you need depth beyond the
top 5. Mirrors the full attribution
view the /intelligence UI shows.)
n_features_total (count of all features computed; if
greater than 20 the rest are available
via /api/v1/cohort_analyze directly)
memory_context (Layer 5 prior observations)
narrative_context (news pulse)
conviction (legacy — same as summary.conviction)
When to use this vs the primitives:
- decision_brief: agents asking "what should I know about this anchor?"
- cohort (depth='full'): when you need full feature_importance / raw stats
- analyze (metric=...): single metric drill-downs
Args:
symbol, date, timeframe: anchor (timeframe default "1h" — current; "1d" lags ~3 days)
cohort_size: target K (default 300)
horizon_days: forward horizon for the headline read (default 5)
include_memory: include Layer 5 prior-observations context (default True)
include_narrative: include news pulse / narrative-change context (default True)
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | ||
| date | Yes | ||
| timeframe | No | 1h | |
| cohort_size | No | ||
| horizon_days | No | ||
| include_memory | No | ||
| include_narrative | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as readOnly, idempotent, and non-destructive. The description adds value by disclosing the internal composition (cohort_analyze, memory, narrative) and the structured output format. It also explains the trade-off between detail and primitives, which aids understanding beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with clear sections (HOW TO TURN THIS INTO A GOOD ANSWER, RESPONSE STRUCTURE, When to use, Args). Every major section earns its place by providing necessary guidance. Minor redundancy could be trimmed, but overall it is efficiently organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 params, composite behavior, rich output), the description is remarkably complete. It covers what the tool does, how to use it, what the output fields mean (including field-by-field interpretation), when to choose alternatives, and parameter details. An output schema exists (not shown), but the description already explains the return value thoroughly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description coverage, so the description fully carries the burden. All 7 parameters are explained in the 'Args:' block, including defaults, behaviors (e.g., timeframe default '1h' meaning current, '1d' lagging ~3 days), and the role of each boolean (include_memory, include_narrative). This compensates fully for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'One-call decision-grade orchestrator' and the 'DEFAULT first call for any (symbol, date) anchor question.' It explicitly lists the components it composes and distinguishes from sibling tools by providing specific guidance on when to use decision_brief vs cohort vs analyze.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides extensive usage guidance: it names this as the default first call, includes a dedicated 'When to use this vs the primitives' section detailing alternatives, and gives step-by-step instructions on how to interpret the output (e.g., read summary first, paraphrase frames, cite numbers). This fully supports correct tool selection and invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[DEPRECATED in v5 — use analyze(metric="decompose", cohort_id=...)]
| Name | Required | Description | Default |
|---|---|---|---|
| cohort_id | Yes | ||
| horizon | No | ||
| max_slices | No | ||
| explain | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, not destructive, idempotent. The description adds deprecation context but no additional behavioral details. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise line, perfectly efficient for its purpose of deprecation notification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deprecated tool with a clear alternative, the description is adequate. However, it lacks explanation of what the tool originally did, which could be helpful for understanding the replacement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no information about any of the four parameters. The agent gets only names and types from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states deprecation and directs to 'analyze(metric="decompose")', implying the purpose of decomposing a cohort. It's explicit enough for an agent to understand the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'DEPRECATED' and provides the exact alternative call, giving clear when-not-to-use and alternative tool information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What's interesting across the market today.
Three modes:
mode="picks" (default):
Top picks ranked by cohort score. Default limit 20, lookback 3
days, horizon 5.
mode="daily_setups":
Tomorrow's brief — top picks pre-enriched with full-cohort
statistics, top-3 features, and yesterday's calibration recap,
all in one response. Replaces the multi-call discovery dance.
Default top=3, timeframe="1d".
mode="risk_adjusted":
Today's picks ranked by Sharpe-like score. Default min_sharpe
0.3.
Args:
mode: "picks" | "daily_setups" | "risk_adjusted"
limit: max picks returned (mode="picks")
lookback_days: scan window in days (mode="picks")
horizon: forward horizon for ranking (mode="picks")
top: number of pre-enriched setups (mode="daily_setups")
timeframe: cohort timeframe (mode="daily_setups")
date: ISO date override (mode="risk_adjusted"; default today)
min_sharpe: minimum Sharpe threshold (mode="risk_adjusted")
fields: daily_setups only — optional allowlist of top-level
response keys. Valid: setups, yesterday_recap. as_of_date
and cohort_timeframe are always returned. Use to drop
yesterday_recap when you only need today's picks.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | picks | |
| limit | No | ||
| lookback_days | No | ||
| horizon | No | ||
| top | No | ||
| timeframe | No | 1d | |
| date | No | ||
| min_sharpe | No | ||
| fields | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds behavioral details like mode-specific defaults, the fields parameter behavior (allowlist, always returned fields), and mode response content. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with mode headings and parameter lists. Every sentence adds value, defaults are clearly stated, and the fields parameter is explained with valid keys. No repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all modes, parameters, and the special fields behavior. It mentions always-returned fields. Output schema exists to supplement return value details. Could clarify output for other modes, but overall complete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description fully compensates by explaining each parameter's applicable mode, default values, and special behavior (e.g., fields parameter only for daily_setups, enumerated valid values for mode). Adds meaning far beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides market interesting items across three modes with explicit names and defaults. It distinguishes from sibling tools like discover_picks and get_daily_setups by integrating their functionalities into a single tool with mode selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each mode (e.g., daily_setups for pre-enriched setups). It does not explicitly state when not to use the tool or mention alternatives, but the mode descriptions provide clear context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[DEPRECATED in v5 — use discover(mode="picks", ...)]
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| lookback_days | No | ||
| horizon | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, etc. The description adds no behavioral context beyond the deprecation. With annotations present, this is adequate but not enhanced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, conveying the essential deprecation and redirection in a single line. It is well-structured for its limited purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deprecated tool with an output schema, the description is minimally sufficient to redirect users. However, it lacks details about behavior or parameters for any agent that might still invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% parameter description coverage, and the description provides no explanation of the three parameters (limit, lookback_days, horizon), leaving the agent without guidance on their meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description does not state what the tool does; it only provides a deprecation notice and redirects to another tool. Without any explanation of functionality, the purpose is vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells users to use 'discover(mode="picks", ...)' as an alternative, which is clear guidance. However, it does not elaborate on when to use this deprecated tool itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Narrative + rankings derived from a stored cohort.
style values:
- "filter_ranking" — rank candidate filters by how much each
one shifts the distribution at the given
horizon. Use to discover conditional
structure before calling `cohort` with the
winning filter.
- "prose" — plain-English summary of the cohort
outcome (Claude Haiku).
- "position_guidance" — exit-signal recommendation for an open
position. Derives symbol+entry_date from
the cohort anchor.
- "risk_ranking" — today's risk-adjusted picks (Sharpe-like)
from forward tests.
Args:
cohort_id: handle from `search` or `cohort`
style: see list above (default "filter_ranking")
horizon: forward horizon in trading days (default 5)
| Name | Required | Description | Default |
|---|---|---|---|
| cohort_id | Yes | ||
| style | No | filter_ranking | |
| horizon | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, nondestructive, idempotent, openWorld. The description adds rich behavioral details: explains each style's purpose, how filter_ranking works (ranking by distribution shift), prose style (plain-English summary), etc., going far beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with a clear one-line summary, followed by a structured list of styles with concise explanations, then parameter details. No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an explain tool with 3 parameters and an output schema (present but not shown), the description covers all necessary input semantics and behavioral context. It references sibling tool for one style, aiding contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates: explains `cohort_id` as a handle from search/cohort, `style` with a list of options and their meanings, `horizon` as forward trading days, and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Narrative + rankings derived from a stored cohort' and lists specific styles, establishing a specific verb+resource. It references sibling tool `cohort` for one style, but does not comprehensively distinguish from all siblings like analyze or cohort_analyze.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance for each style, e.g., 'Use to discover conditional structure before calling `cohort` with the winning filter.' However, it lacks when-not-to-use guidance and clear differentiation from similar sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[DEPRECATED in v5 — use discover(mode="daily_setups", ...)]
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| timeframe | No | 1d |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, destructiveHint, idempotentHint, openWorldHint. The description adds deprecation context, which is helpful but basic.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, but it under-specifies the tool's functionality and parameters. It could provide more context in a similarly concise manner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is deprecated and has an output schema, a minimal description might suffice, but the lack of parameter explanations and behavioral details leaves gaps for any user still needing to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters (top, timeframe), leaving their meaning and usage completely undefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description does not state what the tool does, only that it is deprecated and suggests using discover. Without any verb or resource, the purpose is unclear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells users to use discover(mode='daily_setups') instead, providing a clear alternative for when to use this deprecated tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[DEPRECATED in v5 — use search(mode="live_bars", bars=...)]
| Name | Required | Description | Default |
|---|---|---|---|
| bars | Yes | ||
| scale | No | 1h | |
| top_k | No | ||
| cross_timeframe | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide behavioral hints (readOnlyHint=true, etc.), and the description adds only deprecation context. It does not contradict annotations. The description adds minimal additional behavior information beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that effectively communicates the deprecation and alternative. No wasted words; it is appropriately concise for this purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is deprecated and has an output schema, the description minimally conveys the tool's purpose. However, it lacks guidance on parameter usage and expected behavior beyond the alternative. Acceptable for a deprecated tool but incomplete for full usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters (bars, scale, top_k, cross_timeframe). Only 'bars' is mentioned in the alternative call. The description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is for 'Live Bar Search' and explicitly provides the alternative 'use search(mode="live_bars")'. This distinguishes it from sibling tools like 'search' and indicates its function despite deprecation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the tool is deprecated and directs users to use 'search(mode="live_bars")' instead, providing clear guidance on when not to use this tool and what alternative to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
News intelligence — narrative-change signals layered on price.
Two modes:
mode="pulse" (default):
Single-symbol narrative pulse — frequency anomaly, tone shift,
sentiment-price misalignment (priced-in vs narrative-change),
FinBERT sentiment composite. Surfaces catalysts that price
hasn't yet reflected. Needs symbol.
mode="alerts":
Market-wide narrative anomalies — top tickers right now where
sentiment and price are most divergent. Default min_pulse 0.30,
limit 30.
Args:
mode: "pulse" | "alerts"
symbol: ticker (mode="pulse" only)
min_pulse: minimum narrative_change_score threshold
(mode="alerts")
limit: max alerts returned (mode="alerts")
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | pulse | |
| symbol | No | ||
| min_pulse | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, idempotent), the description discloses that the tool surfaces catalysts price hasn't reflected, involves frequency anomaly, tone shift, sentiment-price misalignment, and FinBERT. This enriches agent understanding of what the tool outputs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is structured with clear mode headings and bullet-like parameter assignments. Each sentence serves a purpose, no redundancy, and front-loads the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description focuses on inputs and behavior, which is sufficient. It covers all parameters and explains the output signals without needing to detail return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description explains all four parameters: mode with two values, symbol for pulse, min_pulse and limit for alerts, including defaults. This adds meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it provides narrative-change signals layered on price, with two distinct modes: 'pulse' for single-symbol and 'alerts' for market-wide anomalies. This distinguishes it from sibling tools like narrative_pulse and narrative_alerts by offering both functionalities in one tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use each mode: 'pulse' requires a symbol, 'alerts' uses min_pulse and limit with defaults. It does not mention when not to use this tool versus the specialized siblings, but the context is clear for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[DEPRECATED in v5 — use narrative(mode="alerts", ...)]
| Name | Required | Description | Default |
|---|---|---|---|
| min_pulse | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and other safety hints, but the description adds zero behavioral context beyond deprecation. It does not mention what happens on invocation or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (one line), but this under-specification is not effective conciseness. It fails to earn its place by providing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two optional parameters and an output schema, the description is completely inadequate. It does not explain the return format, behavior, or any usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no information about the two parameters (min_pulse, limit). The agent cannot infer their meaning or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description only indicates deprecation and suggests an alternative tool. It does not state what the tool does, lacking a verb or resource. The name 'narrative_alerts' hints at functionality but the description is missing purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description informs users to use narrative(mode='alerts') instead, but provides no guidance on when to use this deprecated tool or any conditions. It implies avoidance but lacks explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[DEPRECATED in v5 — use narrative(mode="pulse", symbol=...)]
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds the deprecation context, which is a behavioral trait. No contradictions with annotations, but no additional behavioral details beyond the deprecation notice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loads the deprecation warning. It is concise, though it lacks structured formatting.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the deprecation and available annotations and output schema, the description sufficiently guides an agent to not use the tool and to migrate to the alternative. Original functionality details are omitted, which is acceptable for a deprecated tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'symbol' parameter. It only hints that the replacement uses the same parameter, but does not add meaning for the original tool's parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is deprecated and directs to its replacement, narrative(mode='pulse'). While it doesn't describe the original functionality, the deprecation message makes the purpose clear: this tool should not be used.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the tool is deprecated and provides the exact replacement call with parameters, leaving no ambiguity about when to avoid this tool and which alternative to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Portfolio-level analysis OR per-symbol track-record + Layer 5 memory.
Two modes:
mode="basic" (default):
Multi-holding conditional distribution. Runs per-holding cohorts
in parallel, weight-averages the distributions, ranks tail
contributors (weight × p10, most negative first). PM-agent
primitive. Pass holdings=[{symbol, weight, date}].
mode="symbol_intel":
Per-symbol track record + Layer 5 memory — what does Chart
Library know about this single symbol across all prior
analyses? Returns prior cohort_observations, feature_reliability
learned for the symbol, and the symbol's per-pattern accuracy
history. Pass symbol=X, lookback_days=N.
Args:
holdings: list of {symbol, weight, date} (mode="basic")
symbol: ticker (mode="symbol_intel")
mode: "basic" | "symbol_intel"
horizons: forward horizons (mode="basic"; default [5, 10])
top_k_per_holding: cohort size per holding (mode="basic")
include_path_stats: include MAE/MFE (mode="basic"; slower)
lookback_days: history window (mode="symbol_intel"; default 365)
| Name | Required | Description | Default |
|---|---|---|---|
| holdings | No | ||
| symbol | No | ||
| mode | No | basic | |
| horizons | No | ||
| top_k_per_holding | No | ||
| include_path_stats | No | ||
| lookback_days | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, which indicate safe, non-destructive, repeatable behavior. The description adds significant behavioral details: basic mode runs per-holding cohorts in parallel, weight-averages distributions, and ranks tail contributors; symbol_intel returns prior observations, feature reliability, and accuracy history. It also notes that include_path_stats makes it slower. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for modes, bullet points for arguments, and front-loaded purpose. However, it is somewhat verbose, especially the argument list which could be streamlined. Still, every sentence adds value and the structure aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters with 0% schema coverage, the description provides complete coverage of all inputs. Output schema exists (not shown), but the description clearly states what each mode returns. The tool has moderate complexity, and the description is fully adequate for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. It explains each parameter: holdings (list of dicts for basic mode), symbol (for symbol_intel), mode (basic/symbol_intel), horizons (forward horizons for basic), top_k_per_holding (cohort size), include_path_stats (enables MAE/MFE, slower), and lookback_days (history window). It specifies which parameters apply to which mode, adding meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states two distinct modes with specific purposes: 'Portfolio-level analysis' for basic mode and 'per-symbol track-record + Layer 5 memory' for symbol_intel. It uses a specific verb-resource combination, and the two modes are easily differentiated, helping the agent select the correct mode. It also distinguishes itself from sibling tools like 'cohort' or 'symbol_intelligence' by combining both concepts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context for each mode: basic is a 'PM-agent primitive' for multi-holding distributions, and symbol_intel is for per-symbol memory. However, it does not explicitly state when not to use the tool or compare it to alternatives like 'cohort' or 'symbol_intelligence'. It gives clear context but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
File an error or improvement suggestion to Chart Library.
Use this when something looks wrong (unexpected response shape,
surprising statistics, an error you can describe), or when you
spot a missing capability that would have unblocked you. Reports
land in Graham's inbox and feed the roadmap.
Args:
message: free-text description (required)
endpoint: which API endpoint, if any (e.g. "cohort_analyze")
symbol: associated ticker, if any
severity: "low" | "medium" | "high"
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | ||
| endpoint | No | ||
| symbol | No | ||
| severity | No | low |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent and non-destructive behavior. Description adds context: reports land in Graham's inbox and feed roadmap. Could mention if a confirmation response is returned, but overall transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise: purpose first, then usage guidelines, then parameter list. No wasted words. Efficient for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple 4-param tool with annotations covering safety and output schema, description provides complete context: what it does, when to use, where feedback goes. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions in schema). Description includes a docstring with Args section explaining each parameter, adding meaning beyond type/defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool files feedback (error or improvement) to Chart Library. It distinguishes from sibling tools which are analytical or data retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: when something looks wrong or missing capability. Implies alternatives are other tools. Mentions feedback destination and roadmap impact.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Entry point: find similar historical patterns and return a cohort_id.
Three modes:
- mode="text" (default): pattern search by query string or
symbol+date+timeframe. Cheap, fast, ~50ms.
Examples:
search(query="NVDA 2024-08-05 1h")
search(symbol="NVDA", date="2024-08-05", timeframe="1h")
- mode="live_bars": find historical analogs of a raw bar sequence
the agent constructed (not yet stored in our DB). Pass `bars`
as a list of {open, high, low, close, volume, timestamp}.
- mode="similar": find cohorts most similar to a given (symbol,
date) anchor at the cohort level, not the chart-pattern level.
Useful for "what other setups historically clustered with this
one?"
Returns: {status, data: {cohort_id, anchor, n_matches, top_matches,
survivorship}, meta}. The cohort_id can be chained into `cohort`,
`analyze`, or `explain` to compose richer responses without re-running
kNN.
Args:
query: 'SYMBOL YYYY-MM-DD [timeframe]' (alt to symbol+date)
symbol, date, timeframe: anchor components (alt to query)
top_k: cohort size (10-2000)
mode: "text" | "live_bars" | "similar"
bars: list of OHLCV dicts (mode="live_bars" only)
cross_timeframe: search across timeframes (mode="live_bars" only)
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| symbol | No | ||
| date | No | ||
| timeframe | No | ||
| top_k | No | ||
| mode | No | text | |
| bars | No | ||
| cross_timeframe | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, and idempotent behavior. The description adds context about speed/cost (~50ms for text mode) and return structure (status, data, meta), disclosing that the cohort_id can be chained into other tools. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear headings (Three modes, Returns, Args). It front-loads the core purpose and then details modes, return, and parameters. While comprehensive, it could be slightly streamlined (e.g., the examples could be more terse). Still, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, 3 modes, chaining to other tools), the description covers all aspects: mode selection, parameter constraints (e.g., bars only for live_bars), return structure, and chaining behavior. The existence of an output schema (though not shown) is supplemented by the described return fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the tool description fully compensates by explaining each parameter: query, symbol, date, timeframe, top_k, mode, bars, cross_timeframe. It provides examples and clarifies that query is an alternative to symbol+date+timeframe, and that bars are only for live_bars mode.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'find similar historical patterns and return a cohort_id.' It distinguishes three modes (text, live_bars, similar) with specific use cases and examples, setting it apart from sibling tools like 'similar_cohorts' or 'explain'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each mode, with examples and performance characteristics (~50ms for text mode). It suggests chaining to 'cohort', 'analyze', or 'explain' for richer responses, though it does not explicitly state when not to use this tool vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[DEPRECATED in v5 — use search(mode="similar", symbol=..., date=...)]
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | ||
| date | Yes | ||
| timeframe | No | 1h | |
| top_k | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnlyHint, idempotentHint). The description adds deprecation status, which is beyond annotations and provides behavioral context without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise, single-sentence description that front-loads deprecation and replacement, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of 4 parameters and an output schema, the description lacks detail on how the tool actually works, focusing only on deprecation. It is complete for its notification role but incomplete for usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not describe any parameters, and schema coverage is 0%. It only mentions symbolic usage in the alternative, leaving parameter semantics entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is deprecated and points to an alternative (search(mode='similar')), making the purpose unambiguous despite not detailing the original functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs not to use this tool and provides the correct replacement, satisfying the 'when-not' and 'alternatives' criteria perfectly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[DEPRECATED in v5 — use portfolio(mode="symbol_intel", symbol=...)]
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | ||
| lookback_days | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description does not contradict them and the deprecation notice is behavioral context, but no additional behavioral details are added.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one line), which is acceptable for a deprecated tool, but it could still include parameter explanations without becoming overly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deprecated tool, the description is minimally complete by providing the replacement. However, it fails to explain parameters or behavior, and the presence of an output schema does not compensate for the lack of input guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no parameter details. The only parameter mention is in the replacement hint but lacks semantics or constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title and description explicitly label the tool as deprecated and provide the exact replacement syntax, making the purpose and lifecycle status immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description directly states that this tool is deprecated and instructs the user to use portfolio(mode='symbol_intel', symbol=...), offering a clear alternative and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Many tools have overlapping purposes (analyze vs cohort, decision_brief vs cohort+context) and deprecated tools (11 of 22) with similar names (cohort_analyze vs cohort) cause confusion. Descriptions help but an agent could easily misselect between analyze and cohort for metrics.
Active tools use a mix of single-word verbs (analyze, discover) and nouns (cohort, context), but the deprecated tools (e.g., clusters, decompose) break the pattern. The naming is not completely chaotic but lacks a strict verb_noun convention.
22 tools is too many for a focused API, especially with 11 deprecated ones that are essentially dead weight. The active set (~11 tools) would be appropriate, but the server includes all deprecated tools, making it noisy and heavy.
The non-deprecated tools cover the key operations: pattern search, cohort analysis, metrics, narratives, portfolio analysis, and feedback. Minor gaps (e.g., direct bar fetching) but the core domain of chart-based decision support is well covered.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Real SEC, 13F, insider, congress & macro data your AI agent can cite. Hosted MCP, 24 tools.
US stock market data for AI agents: SEC filings, financials, insider trades, 13F, options, macro.
Screen 11,000+ stocks using natural language and detect chart patterns via MCP.
AI stock intelligence: prices, fundamentals, technicals, news, macro regime, and sector signals.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/grahammccain/chart-library-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
