Skip to main content
Glama

Santiment

by io.github.santiment

Server Details

Crypto market intelligence: social sentiment, on-chain, trending narratives & analyst insights.

Ownership verified
Status
Healthy
Last Tested
Transport
Streamable HTTP
URL

Available Tools

8 tools
assets_by_metric_toolScreen Assets by MetricA
Read-only
Inspect

A powerful metrics-based project filtering and sorting tool that works with cryptocurrency assets based on their metrics and allows for ordered, paginated results.

The tool allows for filtering assets by a metric and sorting them according to that same metric in ascending or descending metric, or just to sort the assets by a metric without filtering.

This tool allows you to discover projects that meet specific criteria by analyzing their metrics over time periods. You can filter projects by absolute values (greater_than/less_than thresholds) or by percentage changes, or just sort projects by some metric.

When to use vs other metric tools

This tool scans the whole asset universe and returns one aggregated value per matching asset — use it for "which assets satisfy X" and "top N by X". It never returns a timeseries: for the values of a metric over time for already-known slugs use fetch_metric_data_tool. To check that a metric exists (or fix a mistyped metric/slug) use metrics_and_assets_discovery_tool.

Use Cases

  • Get top 10 assets by marketcap, sorted in descending order

  • Get top 50 assets with highest dev_activity_1d

  • Find assets with price more than $10

  • Discover tokens whose price increased by more than 50% in the last 30 days

  • Screen for projects with market cap less than $100M

  • Identify assets that have dev_activity_1d decline by more than 20% in the past month

Examples

  • Get projects that have a price_usd in the last 24 hours and it's greater_than $500. Get the first 20 ordered by price_usd in descending order {metric: "price_usd", operator: :greater_than, threshold: 500.0, from: "utc_now-24h", to: "utc_now", sort: "desc, page: 1, page_size: 20}

  • Find projects whose price_usd today is 25% higher than 7 days ago, sorted by the highest percent increase in descending order. Get the first 100. {metric: "price_usd", operator: :percent_up, threshold: 25.0, from: "utc_now-7d", to: "utc_now", sort: "desc", page: 1, page_size: 100}

  • Projects with current market cap less_than $50M. Get 100 such projects, ordered by marketcap in descending order. {metric: "marketcap_usd", operator: :less_than, threshold: 50000000.0, from: "utc_now-1d", to: "utc_now", sort: "desc", page: 1, page_size: 100}

Here is how the filtering works:

  • For absolute value operators - greater_than and less_than - fetch the metric for each asset in the interval from-to, aggregting it using the specified aggregation method (defaulting to the metric's default).

  • For percent change operators - percent_up and percent_down - fetch the metric for each asset in the interval from-to, as well as in the same length interval immediately before from`. The two resulting values are compared to calculate the percentage change.

Some metrics like price_usd and marketcap_usd are aggregated with LAST aggregation by default, meaning that the last known value in the queried interval is used. For percent change, this means that the tool compares the last known price immediately before from and the last known price before to. Other metrics like transaction_volume_usd and social_volume_total (and most other volume metrics) are aggregated by default with SUM aggregation, meaning that the total combined sum in the queried interval is used. For these metrics length of the time window is vital. A common mistake is to try to check if the social_total_total for the last 5 minutes is greater_than some threshold. Five minutes is not enough for social volume to accumulate enough. In such scenarios use a longer time window like 1 day or more.

ParametersJSON Schema
NameRequiredDescriptionDefault
toYesEnd date/time for the analysis period. Defines the end of the time window for metric aggregation. Accepts ISO 8601 datetime strings (e.g., "2024-12-31T23:59:59Z") or relative time expressions (e.g., "utc_now" for current time, "utc_now-1d" for yesterday). Defaults to current time if not specified. Must be after the 'from' date. Used with percentage operators to calculate change over the specified period.
fromYesStart date/time for the analysis period. Defines the beginning of the time window for metric aggregation. Accepts ISO 8601 datetime strings (e.g., "2024-01-01T00:00:00Z") or relative time expressions (e.g., "utc_now-30d" for 30 days ago, "utc_now-1h" for 1 hour ago) Defaults to 30 days ago if not specified. Used with percentage operators to calculate change over time.
pageYesPage number for paginated results. Used to retrieve specific pages when the result set is large. Starts from 1 (first page). Combine with page_size to control how many results are returned per page. Useful when only the top 10, 20, 100, etc. assets are needed.
sortYesSort order for the filtered results based on the aggregated metric values. - "asc" - Ascending order (lowest values first, e.g., cheapest prices first) - "desc" - Descending order (highest values first, e.g., most expensive prices first) Particularly useful when combined with pagination to get the top/bottom performers. Example: sort="desc" with price_usd shows highest-priced projects first.
metricYesThe metric to use for screening projects. This determines what aspect of each project will be analyzed. Common metrics include: 'price_usd', 'marketcap_usd', 'volume_usd', 'dev_activity', 'social_volume', 'active_addresses'. Use the data catalog to discover all available metrics for comprehensive screening options. Discover the supported metrics with the metrics_and_assets_discovery_tool.
operatorNoComparison operator that determines how projects are filtered based on the metric and threshold. Absolute value operators (compare current values): - `greater_than` - Include projects where the aggregated metric value is greater than the threshold - `less_than` - Include projects where the aggregated metric value is less than the threshold Percentage change operators (compare change from 'from' to 'to' period): - `percent_up` - Include projects where the metric increased by more than the threshold percentage - `percent_down` - Include projects where the metric decreased by more than the threshold percentage If this parameter is not provided, the threshold parameter also must not be provided. If they are not provided, the tool will simply sort the assets and will do no filtering. Example: operator=percent_up, threshold=25.0 finds projects that gained more than 25%.
page_sizeYesNumber of projects to return per page (max 100). Controls the size of each paginated response.
thresholdNoThe numeric threshold value used for filtering projects. The meaning depends on the operator: For absolute operators (:greater_than, :less_than): - The actual metric value to compare against (e.g., 10.5 for price_usd greater_than $10.50) - Units match the metric (USD for price/market cap, count for addresses, etc.) For percentage operators (:percent_up, :percent_down): - The percentage change threshold (e.g., 25.0 for 25% change) - Always expressed as a positive number regardless of direction If this parameter is not provided, the operator parameter also must not be provided. If they are not provided, the tool will simply sort the assets and will do no filtering. Examples: threshold=50000000.0 with :less_than finds projects with market cap under $50M
aggregationNoMethod for aggregating metric data over the specified time period. Determines how multiple data points within the time window are combined into a single value for comparison. Common aggregation methods: - "avg" - Average value over the period (default for most metrics) - "sum" - Total sum of values (useful for volume, transaction counts) - "max" - Maximum value in the period (highest price, peak activity) - "min" - Minimum value in the period (lowest price, minimum activity) - "last" - Most recent value in the period - "first" - Earliest value in the period If not specified, uses the metric's default aggregation, whichi is carefully selected based on the metric type. Some aggregations do not make sense for certain metrics (e.g., summing prices). If not specifically required, using the metric's default aggregation method is recommended.

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint=true and destructiveHint=false; the description adds substantial behavioral detail: aggregation mechanics for absolute vs percent operators, default LAST vs SUM aggregations, and a warning about time-window sufficiency for volume metrics. It discloses the operational semantics without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with clear headings (When to use, Use Cases, Examples, How filtering works). Minor fluff like 'powerful' and some repetition (e.g., sorting behavior repeated) prevent a 5, but every major section earns its place for a 9-param tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the full task scope: what it returns (one aggregated value per asset), pagination behavior, filtering operators, aggregation defaults, and sibling-tool distinctions. Without an output schema, it still tells the agent the essential return shape and common usage patterns, making it complete for agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema already covers all 9 parameters (100% coverage); description adds real value by explaining filtering mechanics with worked examples, clarifying percent operator comparisons across two intervals, and noting 'metric's default aggregation' behavior. Threshold/operator coupling is also explained in schema, but the description's use cases and time-window advice go beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States it is a 'metrics-based project filtering and sorting tool' that 'scans the whole asset universe' and returns 'one aggregated value per matching asset.' It explicitly differentiates from siblings by noting it 'never returns a timeseries' and directing to fetch_metric_data_tool for timeseries and metrics_and_assets_discovery_tool for metric discovery.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'When to use vs other metric tools' section explicitly says to use this for 'which assets satisfy X' and 'top N by X', and directs to fetch_metric_data_tool for timeseries over known slugs and metrics_and_assets_discovery_tool for validating metrics. This gives clear affirmative and exclusionary guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fetch_insights_toolFetch InsightsA
Read-only
Inspect

Fetch full text content for specific santiment crypto insights IDs

ParametersJSON Schema
NameRequiredDescriptionDefault
insight_idsYesArray of santiment crypto insights IDs to fetch full content for (max 10)

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark the tool as readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the 'full text content' behavior, but does not disclose potential batch limits beyond the schema, error conditions, or return format. With annotations doing heavy lifting, this is adequate but not enriched.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence with no filler. It front-loads the core action and object, and every word contributes to understanding the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema) and the annotations, the description provides sufficient context to invoke it correctly. It does not describe response structure, but that is less critical for a retrieval tool, and the schema covers the input. The only minor gap is lack of guidance about how to obtain IDs, which would push it to a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description covers the parameter well, stating it takes santiment crypto insights IDs with a max of 10. The tool description adds no further semantic detail. The schema's oneOf allowing a string is ambiguous (comma-separated? JSON-encoded?), and neither the description nor schema clarifies it, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Fetch full text content') and resource ('specific santiment crypto insights IDs'), distinguishing it from sibling tools like insight_discovery_tool which likely handle discovery rather than retrieval by ID. 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.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description establishes a clear usage context: this tool is for retrieving full content for already-known insight IDs. It does not explicitly mention that insight_discovery_tool should be used first to find IDs, nor does it list exclusion criteria, but the intent is clear enough for an agent to select it appropriately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fetch_metric_data_toolFetch Metric DataA
Read-only
Inspect

Fetch metric timeseries for one metric and one or many slugs.

Defaults: last 30 days (time_period="30d"), interval="1d".

Use this when the assets are already known and the values over time matter. For the opposite direction — "which assets satisfy X" / "top N by X", one aggregated value per asset across the whole universe — use assets_by_metric_tool. To confirm a metric exists for a slug first, use metrics_and_assets_discovery_tool; to draw the result, use show_chart.

ParametersJSON Schema
NameRequiredDescriptionDefault
slugsYesList of slug identifiers (e.g., ["bitcoin"], ["bitcoin", "ethereum"], etc.). Accepts at most 10 slugs at a time. Only metrics that have `supports_many_slugs: true` can accept more than one slug. Check the `supports_many_slugs` field in the metrics_and_assets_discovery_tool response before passing multiple slugs. Financial and on-chain metrics generally support multiple slugs; social, sentiment, and derivatives metrics generally do not. The tool returns data for one metric and one or many slugs.
metricYesMetric name to fetch (e.g., 'price_usd'). IMPORTANT: Before fetching data, verify metric names by calling the metrics_and_assets_discovery_tool first. Only metrics listed there are supported. Do not guess or infer metric names — they may differ from what you expect.
intervalNoThe interval between two data points in the timeseries data (e.g., '5m', '1h', '1d'). The format is: <number><suffix>, where: - <number> is an integer - <suffix> is one of: - m (minutes) - h (hours) - d (days) - w (weeks) - y (years) For example, 5m means that the data returned will have a 5 minute interval between two data points. Each metric has predefined `min_interval`. It describes the lowest possible interval for which data is available. If the metric has `min_interval=1d` it means that Santiment has one data point per day for that metric. For these metrics `interval="5m"` won't work as 5 minutes is less than 1 day.
time_periodNoHow far back in time to fetch the data for (e.g., '7d', '30d', '90d'). This parameter defines the range of metric data to fetch - from <time_period> time ago up until now. Defaults to 30d.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only/non-destructive behavior, lowering the bar. The description adds meaningful context: default time range (30d) and interval (1d), and clarifies this returns per-asset time series rather than a single aggregated value. It does not mention response format or pagination, but that is a minor gap given the annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: the first sentence states the core action, followed by defaults, then usage guidance and sibling references. Every sentence earns its place with no repetition or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter read-only tool with rich schemas, the description covers purpose, defaults, when-to-use, alternatives, prerequisites, and next steps. However, since there is no output schema, it omits the return shape or pagination details, which would further aid invocation confidence.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed descriptions for all four parameters, so the baseline is 3. The description adds default values for `time_period` and `interval`, but otherwise does not go beyond the schema's already-rich parameter explanations.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Fetch metric timeseries for one metric and one or many slugs' — a specific verb, resource, and clear scope. It also distinguishes itself from siblings by explicitly contrasting with `assets_by_metric_tool`'s aggregated, universe-level use case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use: 'Use this when the assets are already known and the values over time matter.' It names the exact alternative for the opposite direction (`assets_by_metric_tool`), and provides a prerequisite (`metrics_and_assets_discovery_tool`) and follow-up (`show_chart`) tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

insight_discovery_toolDiscover InsightsA
Read-only
Inspect

List Santiment insights (analyst-written crypto articles) published in a lookback window. Returns metadata only — id, title, tags, author, link, published_at, prediction — never the article body.

When to use

  • The user asks what Santiment analysts have written or published recently.

  • As step 1 of a two-step read: discover ids here, then pass them to fetch_insights_tool for the full text.

When not to use

  • Full text of an insight — use fetch_insights_tool (it needs ids, so call this tool first).

  • What the market is talking about right now — use trending_stories_tool (stories only) or combined_trends_tool (stories + trending words). Insights are human-authored articles, not live social signal.

  • Numeric metric timeseries for an asset — use fetch_metric_data_tool.

  • Ranking or screening assets by a metric — use assets_by_metric_tool.

Parameters

  • time_period (optional, default "30d") — lookback window as <integer><unit>, unit one of s, m, h, d, w, y (e.g. "12h", "7d", "90d", "1y"). The window is always now - time_period .. now; absolute dates and future ranges are not supported. An unparsable value returns an error, not a default.

There is no tag, author, asset or full-text filter — filter the returned list yourself.

Behavior

  • Read-only: no writes, no state change, nothing destructive.

  • Requires an authenticated Santiment account (API key or OAuth token); every call counts against the account plan's MCP rate limits.

  • Returns only published, moderator-approved insights, newest first, hard capped at 100 per call. A wide time_period can hit that cap and silently omit the oldest insights — if total_count is 100, narrow the window and call again.

Response

JSON object:

{
  "insights": [
    {
      "id": 1234,                          // integer, feed to fetch_insights_tool
      "title": "...",
      "tags": ["BTC", "bitcoin"],          // asset tickers/slugs and topics
      "link": "https://app.santiment.net/insights/read/1234",
      "published_at": "2025-01-30T10:00:00Z",
      "author": "username",                // "Anonymous" when unset
      "prediction": "semi_bullish"         // heavy_bullish | semi_bullish |
                                           // semi_bearish | heavy_bearish |
                                           // none | unspecified | null
    }
  ],
  "time_period": "30d",
  "total_count": 1,
  "period_start": "2024-12-31T10:00:00Z",
  "period_end": "2025-01-30T10:00:00Z"
}

An empty insights list with total_count: 0 means nothing was published in the window — a valid result, not an error.

ParametersJSON Schema
NameRequiredDescriptionDefault
time_periodNoLookback window as <integer><unit>, unit one of s, m, h, d, w, y (e.g. '12h', '7d', '30d', '90d', '1y'). Insights published in `now - time_period` .. `now` are returned. Absolute dates and future ranges are not supported. Defaults to '30d'.

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already include readOnlyHint=true and destructiveHint=false. The description further discloses authentication requirements, rate limiting, pagination cap of 100, silent omission behavior, and response validity conditions. This goes 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

While long, the description uses clear headings and every section serves a distinct purpose: usage, parameters, behavior, and response. It is appropriately sized for the tool's complexity, with no redundant content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description provides a complete response format with field types and semantics, plus edge cases (like empty results). It covers all necessary context for correct invocation and result handling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter, but the description adds substantial meaning: concrete examples, unit constraints, exact window semantics, no absolute dates, and error behavior. This is a model of enriching schema information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with a specific verb and resource: 'List Santiment insights (analyst-written crypto articles) published in a lookback window. Returns metadata only'. It explicitly distinguishes from siblings by naming alternatives like fetch_insights_tool and trending_stories_tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'When to use' and 'When not to use' sections provide explicit guidance, including exact scenarios and named alternative tools. This fully covers when to use this tool versus alternatives, making it exemplary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

metrics_and_assets_discovery_toolMetrics and Assets DiscoveryA
Read-only
Inspect

Catalog lookup: which metrics and which crypto assets (slugs) Santiment supports, and whether a given metric exists for a given asset. Returns names and metadata only — it never returns metric values or timeseries.

When to use

  • Resolve a name before any data call: turn "Ethereum" into the slug ethereum, or "active addresses" into the metric daily_active_addresses.

  • Check availability before calling fetch_metric_data_tool, assets_by_metric_tool or show_chart, so a bad slug/metric does not waste a data call.

  • Recover from a "metric/slug not supported" error from any other tool.

When not to use

  • Actual metric values over time — use fetch_metric_data_tool.

  • Ranking, filtering or screening assets by a metric value — use assets_by_metric_tool.

  • Rendering a chart — use show_chart.

  • Trending words/stories or insights — use combined_trends_tool or insight_discovery_tool. Those data sets are not in this catalog.

Parameters

Both parameters are optional and the four combinations do four different things:

Arguments

Returns

{}

Every supported metric and every supported asset

{"slug": ...}

All metrics available for that one asset

{"metric": ...}

All assets that support that one metric

{"slug":..., "metric":...}

Whether that exact pair is available (validation)

  • slug — lowercase, hyphen-separated asset id: "bitcoin", "ethereum", "avalanche". Not a ticker: use "bitcoin", not "BTC". One slug per call; lists are not accepted.

  • metric — lowercase snake_case metric id: "price_usd", "marketcap_usd", "daily_active_addresses". One metric per call.

Examples:

{}
{"slug": "ethereum"}
{"metric": "price_usd"}
{"slug": "bitcoin", "metric": "daily_active_addresses"}

Behavior

  • Read-only: no writes, no state change, nothing destructive.

  • Requires an authenticated Santiment account (API key or OAuth token); every call counts against the account plan's MCP rate limits.

  • Results are cached server-side, so the catalog can lag a newly listed asset by a few minutes.

  • Large responses (notably {}, which covers ~500 assets) are truncated to stay under the client token limit. When that happens the response carries "truncated": true plus "truncation_notice", and the counts are adjusted to what was actually returned — pass slug or metric to get a complete answer instead of a truncated one.

Response

Always a JSON object. Its shape depends on the arguments.

{} — full catalog:

{
  "metrics": [{"name": "price_usd", "description": "...", "unit": "USD",
               "supports_many_slugs": true, "min_interval": "1m",
               "default_aggregation": "last",
               "documentation_urls": [{"url": "..."}]}],
  "assets": [{"name": "Bitcoin", "slug": "bitcoin", "ticker": "BTC"}],
  "metrics_count": 120, "assets_count": 500, "description": "..."
}

{"slug": ...} — {"slug", "metrics" (same metric objects as above), "metrics_count", "description"}.

{"metric": ...} — {"metric", "assets" (same asset objects as above), "assets_count", "description"}.

{"slug": ..., "metric": ...} — on success {"slug", "metric": <metric object>, "available": true, "description"}.

Unsupported input is reported inside a successful response, not as a tool error: an unknown slug yields {"error": "...", "available_assets": [...]}, an unknown metric yields {"error": "...", "available_metrics": [...]}. There is no "available": false — read error. Error messages include a fuzzy suggestion for near-miss metric names (price_uds -> price_usd), so retry with the suggested name.

ParametersJSON Schema
NameRequiredDescriptionDefault
slugNoSantiment slug of one crypto asset: lowercase, hyphen-separated, e.g. 'bitcoin', 'ethereum', 'avalanche'. Not a ticker - use 'bitcoin', not 'BTC'. One slug per call; lists are not accepted. Alone: returns all metrics available for this asset. With `metric`: checks only whether that metric exists for this asset. Omit both to list the whole catalog.
metricNoSantiment id of one metric: lowercase snake_case, e.g. 'price_usd', 'marketcap_usd', 'daily_active_addresses'. One metric per call; lists are not accepted. Alone: returns all assets that support this metric. With `slug`: checks only whether this metric exists for that asset. Omit both to list the whole catalog.

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description richly discloses behaviors beyond annotations: read-only confirmation, auth/API key requirements, server-side caching with lag, response truncation for large payloads (with 'truncated': true and counts adjusted), and error handling via a successful response with an 'error' field plus fuzzy suggestions. This goes far beyond the readOnlyHint/destructiveHint annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with clear headers (When to use, When not to use, Parameters, Behavior, Response) and a table for combinations. Every section contributes essential information for a tool with four distinct modes. It is not overly verbose given the complexity, though a couple of examples could be trimmed without loss.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully explains return shapes for all four argument combinations, including the full catalog JSON, per-slug/metric results, and error responses. It also covers truncation, caching, rate limits, and auth. No critical aspect of behavior or return format is left undocumented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers 100% of parameter semantics with examples and combination behavior. The description adds value with a four-row table showing the exact output for each argument combination, plus concrete examples and clarification that lists are not accepted. It reinforces but does not significantly extend the schema's detailed parameter descriptions, earning slightly above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise, resource-specific statement: 'Catalog lookup: which metrics and which crypto assets (slugs) Santiment supports, and whether a given metric exists for a given asset.' It explicitly says it returns names and metadata only, never metric values or timeseries, which immediately distinguishes it from data-fetching siblings like fetch_metric_data_tool and assets_by_metric_tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Dedicated 'When to use' and 'When not to use' sections provide explicit guidance. They name alternatives directly: use fetch_metric_data_tool for values, assets_by_metric_tool for screening, show_chart for charts, and combined_trends_tool/insight_discovery_tool for trends. It also covers error-recovery use cases, such as resolving 'metric/slug not supported' errors.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

show_chartShow ChartA
Read-only
Inspect

Render a Santiment chart with an asset's price (OHLC) plus an optional overlay metric in a second pane. The widget that consumes this tool is built on the Santiment chart library (lightweight-charts under the hood), so the response is render-ready — the client just feeds each series entry into the chart unchanged.

Parameters

  • slug — asset slug (e.g. bitcoin, ethereum). Defaults to bitcoin.

  • primary — what goes into the main pane.

    • "price" (default) — OHLC candlestick.

    • any metric name from the catalog — line/area instead of candles.

  • overlay — optional metric name to render in a second pane. Allowed values are listed below.

  • range — 24h, 7d, 30d, 90d, 1y. Defaults to 30d.

Available overlay metrics (catalog)

social_volume_total, social_dominance_total, sentiment_balance_total, sentiment_weighted_total, daily_active_addresses, network_growth, transaction_volume_usd, velocity, mvrv_usd, nvt, realized_value_usd, mvrv_long_short_diff_usd, exchange_balance, whale_transaction_count_100k_usd_to_inf, top_holders_held_supply_percent, dev_activity, github_activity, volume_usd, marketcap_usd, funding_rate_perp.

ParametersJSON Schema
NameRequiredDescriptionDefault
slugNoAsset slug (e.g. 'bitcoin', 'ethereum'). Defaults to 'bitcoin'.
rangeNoTime range. One of: 24h, 7d, 30d, 90d, 1y. Defaults to 30d.
overlayNoOptional metric to overlay in a second pane. Must be one of the catalog names (see tool description).
primaryNoPrimary series — 'price' for candlestick OHLC, or a metric name from the catalog. Defaults to 'price'.

TDQS

A4.2/5.0
Behavior4/5

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 meaningful behavior beyond that: it explains the response is 'render-ready' for the widget, and that the client feeds each `series` entry unchanged. This gives the agent useful context about output consumption without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is properly structured with a clear intro, parameter breakdown, and overlay list. It is slightly long but every section serves a purpose—the catalog list is necessary for valid overlay selections. Front-loading the core purpose makes it easy to grasp quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema, the description partially covers return behavior by noting the response is 'render-ready' and contains `series` entries. It does not detail the exact shape of each series entry, but for a charting tool with clear parameter semantics and annotations, this is adequate. The main gap is a more explicit return format, which keeps it from a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

While schema coverage is 100%, the description significantly enriches parameter understanding: it lists allowed values for `range`, enumerates the full catalog of overlay metrics, and explains the semantic difference between `primary='price'` (candlesticks) vs a metric (line/area). Defaults are also restated and clarified. This goes well beyond the schema's basic descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Render a Santiment chart with an asset's price (OHLC) plus an optional overlay metric in a second pane.' This clearly distinguishes the tool as a chart-rendering utility compared to sibling tools like fetch_metric_data_tool, which retrieve raw data. The purpose is unambiguous and immediately front-loaded.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than explicitly stated. The description explains what the tool does and details parameters, but does not explicitly say when to prefer this over alternatives or provide when-not-to-use guidance. There is no direct contrast with sibling tools such as combined_trends_tool or fetch_metric_data_tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Frequently Asked Questions

Discussions

No comments yet. Be the first to start the discussion!

Login with GitHub to comment

Related MCP Connectors

Related MCP Servers

Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: screening assets vs fetching timeseries vs catalog discovery vs charting vs insights discovery/fetch vs trending stories vs combined trends. The overlapping trending tools are explicitly differentiated through a superset relationship with usage guidance.

Naming Consistency3/5

All names are snake_case and most end in '_tool', but the pattern is mixed: some start with verbs (fetch_*, show_*) while others are noun phrases (assets_by_metric_tool, combined_trends_tool, insight_discovery_tool). This is readable but not a consistent verb_noun convention.

Tool Count5/5

8 tools is well-scoped for a crypto analytics server, covering discovery, data retrieval, screening, charting, and content access without bloat or thinness. Each tool earns its place in the workflow.

Completeness4/5

The toolset covers the core workflows: catalog discovery, metric timeseries, asset screening, chart rendering, insights list/fetch, and trending data. Minor gaps include no multi-metric timeseries fetch and a limited set of chart overlay options, but agents can work around these.

Resources