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

Annotations already cover the read-only, idempotent, non-destructive profile, and the description adds substantial value beyond them: the 1-credit-per-call cost, the raw-metrics-not-reputation nuance with the signal in the ratios, and the full deprecation lifecycle with a concrete removal date and migration path. This is exactly the behavioral context an agent needs to decide whether to rely on this tool.

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

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

The description is front-loaded with purpose, then cost, usage, return interpretation, and lifecycle in logical order, and each sentence carries non-redundant information. The legacy sentence is slightly wordy — 'it still works today and keeps working until...' repeats the same idea — but the overall density-to-length ratio is strong.

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 single-parameter, read-only tool with a documented output schema, the description covers everything needed to call it correctly: cost, safety (via annotations), usage context, return semantics, deprecation status, and a migration alternative. Nothing an agent needs to decide or invoke correctly is missing.

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 100%, and the schema fully documents the single username parameter including the with-or-without-@ format, so the description need not repeat it. The description's mention of 'an X account' reinforces the parameter's role but adds no format or semantics beyond the schema, matching the baseline of 3 for high schema coverage.

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

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

The description opens with a specific verb-resource pair — 'follower and engagement stats for an X account' — and clarifies the output is raw metrics rather than a reputation score. It also differentiates from the closest sibling by directing new work to mentions with mode=search, which returns posting accounts alongside engagement metrics, so an agent can classify this tool without opening its schema.

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?

Explicit usage context is given: 'use it to judge whether an account's reach is real before weighting what it posts.' The description also states when NOT to use it — it is legacy, removed on 28 October 2026, and not being extended — and names the exact alternative (mentions with mode=search), leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new context: the call is 'Free' (no credit cost), it is a reachability probe, and it is the first diagnostic to run on auth/credit failures. It doesn't describe latency or failure modes, keeping it below 5.

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?

Three tight sentences, front-loaded with the core purpose, then cost, then the trigger condition. The trailing historyFrom sentence is useful plan context but is the least essential and is slightly ambiguous in a zero-parameter 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?

An output schema exists so return values need not be explained. Given a parameterless, read-only diagnostic, the description covers purpose, cost, trigger, and the plan-scoped data limits an agent needs to interpret the result.

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

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

The tool takes zero parameters, so the baseline is 4 and the schema (empty object, 100% coverage) carries the full burden. The mention of historyFrom is not a parameter but a plan-limit detail, which adds context about what the returned tier implies, though it reads slightly as if it were an input.

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?

States a specific verb with three named resources: checks API key tier, credit usage/remaining requests, and reachability. This is unmistakably a diagnostics tool and cannot be confused with any sibling such as market, calls, or events.

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?

Gives an explicit trigger: 'Call this first when a request fails with an auth or credit error.' That is a clear usage condition. It lacks any when-not guidance (e.g., don't call it alongside every request), so it falls just short of the top bar.

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

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

Adds real behavior beyond the annotations: cost (1 credit plus LLM usage), the fact that no monitoring starts until activation, and the coverage limitation for tweet conditions on non-Elfa accounts. Annotations already declare readOnlyHint/openWorldHint, so the incremental disclosure is the cost and the non-execution guarantee; return format is left to the output schema.

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

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

Purpose is front-loaded in the first clause, followed by cost, non-execution, input guidance, and the account-coverage caveat. Every sentence carries distinct, load-bearing information with no repetition of structured fields.

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?

With an output schema present, return values need not be described. The description covers purpose, cost, activation path, required input content, and the coverage boundary — everything an agent needs to invoke it correctly rather than a sibling.

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 100%, so the baseline is 3, but the description meaningfully enriches the 'message' parameter by telling the agent what content to include (target, threshold, firing action). It does not address speed or sessionId, which remain schema-only.

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?

States a specific verb and resource: 'Turn a plain-language monitoring request into an EQL query.' It clearly separates drafting from running ('This only drafts the query, nothing starts running'), which distinguishes it from siblings auto_query_write and auto_validate.

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 routes the agent: activate with auto_query_write after drafting, and for X accounts outside Elfa's real-time set, 'write the condition yourself and check it with auto_validate.' It names both alternatives and the conditions that select them, plus what input to supply ('what to watch, the threshold, and what should happen when it fires').

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

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

Annotations already provide destructiveHint=true and readOnlyHint=false, but the description adds critical behavioral nuance: drafts are non-evaluating, non-firing, and free except for method=convert which activates and incurs cost. This goes well beyond the annotations and materially informs invocation decisions.

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?

Three sentences deliver purpose, behavioral rules, and usage guidance with no filler. The most important information is front-loaded, and every sentence earns its place.

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

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

The tool has 9 parameters, nested objects, and an output schema; the description covers the essential decision-making points (what a draft is, when to use it, cost caveat). The rich schema handles parameter details, and the output schema covers return values, leaving only the need for a bit more explicit workflow guidance (e.g., 'build and validate first') which the schema itself hints at via query description.

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

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

Schema description coverage is 100%, so all parameters have descriptions. The tool description adds a cost implication for method=convert but does not otherwise elaborate on parameter relationships or formats. With full schema coverage, a baseline of 3 is appropriate.

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

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

The description opens with 'Park an Auto query without activating it,' a specific verb+resource that clearly states the tool's core function. It further distinguishes itself from live query tools by noting 'Drafts never evaluate and never fire,' making the purpose unmistakable and distinct from siblings like auto_query.

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 gives explicit usage context: 'Use drafts when the user is still deciding.' This tells the agent when to choose drafts over live queries, though it does not explicitly name alternative tools. The cost caveat for method=convert also serves as a conditional usage warning.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description adds genuinely non-obvious behavior: the endpoint is free, there is no push/subscription channel so the agent must poll, and get surfaces a failure plus a recorded reason when a query failed. It stops short of stating rate limits or pagination semantics beyond pollAfterSeconds.

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?

Dense but nearly waste-free: every clause conveys method behavior (list/get/executions/sessions) or operational guidance (no push, poll, pollAfterSeconds). It is one long run-on sentence rather than cleanly front-loaded bullets, which slightly hurts scannability but not information density.

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?

An output schema exists, so return shapes need not be described. The description covers all six methods, the polling model, cost, and failure surfacing, which is close to complete for a 9-parameter dispatch tool. It omits any mention of auth requirements or what 'Free' implies about rate limits.

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

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

Schema description coverage is 100% (baseline 3), and the description rises above it by giving meaning to each method enum value rather than leaving 'Which read to perform.' It explains what the outputs of the different reads represent and confirms which identifier goes with which method, adding real value over the terse 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?

It states a specific verb+resource ('Read side of Auto') and then enumerates exactly what each read does: list browses queries, get polls one query's latest evaluation, executions show what fired, sessions return the attached LLM analysis. This lets an agent distinguish it from the write-side sibling (auto_query_write) and from the other Auto tools without opening a schema.

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?

It gives clear selection guidance: use method=get to poll and respect pollAfterSeconds because there is no push channel, and it clarifies condition-specific methods (execution requires executionId, session requires sessionId). It never explicitly names the write alternative, but the 'read side' framing plus 'no push channel' tells the agent what to do instead of waiting.

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

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

Annotations already declare destructiveHint=true and non-idempotent, but the description adds material context they cannot: the 5-credit + LLM cost of create versus free cancel/delete, and the crucial fact that an activated query fires unattended without re-confirmation. That is exactly the kind of behavior an agent needs before a destructive write.

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?

Two sentences, zero waste. The what-it-does clause is front-loaded, followed by cost and the safety precondition in priority order.

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 five-parameter write tool with an output schema and full annotation coverage, nothing an agent needs to call it correctly is missing: action scope, cost, validation path, and the unattended-firing warning are all present.

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

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

Schema description coverage is 100% and the method enum's own description already explains create/cancel/delete semantics, so the schema carries the parameter burden. The description adds cost context tied to the create path but no syntax or format detail beyond what is already documented.

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?

States specific verbs (activate/cancel/delete) against a specific resource (an Auto query), which maps cleanly onto the three-valued method enum. It is clearly distinguishable from siblings auto_build (construct), auto_validate (check), and auto_query (read).

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 names the prerequisite alternative (auto_validate) and the required pre-call human confirmation of both cost and action. It also flags the per-post X account cost dimension, giving the agent a concrete gate before invoking a write.

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

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

Annotations already cover safety (readOnly/idempotent/non-destructive), yet the description adds substantial context: it is free, it returns a cost estimate, and it details the per_post billing nuance (accounts cost creditsPerPost for every matched-or-not post while the query runs, on top of estimatedCredits). That is exactly the added-value context annotations cannot supply.

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 core instruction and cost-warning are front-loaded, and even the dense tweetAccounts/billing sentence is deliberately included because the agent must relay cost to the user. It is longer than ideal and slightly tangential, but each sentence carries actionable content.

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?

An output schema exists, so return values need no prose, and the description still covers both operating modes, input source options, the sequencing requirement, and the cost-reporting duty. Nothing an agent needs to invoke it correctly is missing.

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 100%, so the baseline is 3; the description goes further by clarifying the mutual-exclusivity of query vs draftId and the query/symbol method split and their prerequisites (exchange and symbol for method=symbol). It adds real routing meaning beyond the field descriptions, though the billing detail is not parameter syntax.

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?

States a specific verb+resource ('Check EQL syntax and get a cost estimate') and distinguishes it from the write sibling via 'before anything is activated'. It also separates the two modes (method=query vs method=symbol), so an agent can tell exactly what this tool 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?

Explicit sequencing ('Always run this before auto_query_write, and show the estimated cost to the user') plus input routing ('Pass either an inline query or a draftId') and the alternative mode ('method=symbol instead checks that a symbol has market data ... before you build price or ta conditions around it'). When-to-use and alternatives are both covered.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered; the description adds value beyond them by scoping what is returned ('Not returned: post text or a recommendation') and by stating plan/access gating ('Free on Pay-as-you-go and Grow plans until 31 October 2026'). It says nothing about pagination limits or result volume, which the schema hints at but the description does not reinforce.

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 dense and front-loaded with the resource definition and level breakdown, each sentence doing distinct work. The pricing/plan sentence is time-limited promotional detail of marginal utility to an agent and is the one piece that does not clearly earn its place.

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 13-parameter, no-required-parameter read tool with an output schema, the description covers the primary mode selector, the composite open-positions query, and the exclusion of post text, so an agent can call it correctly. It stops short of full completeness because it does not tie the many optional filters (assetClass, direction, ids, entityId) back into the level story.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns above that by supplying the real semantics for the level enum, which the schema only labels 'Which level to read', and by spelling out the status=open + from composite query. It adds no meaning for handle, cursor, entityIds or direction beyond the already-complete schema text.

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 names a concrete resource and scope — 'What accounts are doing: positions taken in posts on X and Telegram' — and then decomposes the three data shapes it can return (level=calls, level=episodes, level=positioning). That is far more specific than the bare tool name 'calls' and lets an agent distinguish it from siblings like mentions, market_chat or trending. It lacks an explicit verb for the overall operation, which keeps it just short of a 5.

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

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

Each enum value of the primary selector is given a when-to-use gloss (calls = individual posts/actions, episodes = full position lifecycle with entry/exit and track record, positioning = current open longs/shorts for one asset), and it even documents the derived query 'level=episodes with status=open and from set to now'. No sibling alternatives or explicit exclusions are named, so it stops short of a 5.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-open-world), and the description adds genuinely new behavior: exact-match failure mode, ticker non-uniqueness, family-id grouping for asset variants (WBTC/cbBTC as Bitcoin), and free-tier eligibility through 31 October 2026. These are operational traits an agent cannot infer from 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?

Front-loaded with the core conversion purpose, then behavioral caveats. Dense and mostly efficient, though the pricing-eligibility sentence is incidental to invocation and adds a small amount of non-essential weight.

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?

With an output schema present, return values need no explanation, and the description still supplies everything else an agent needs: accepted input forms, match semantics, disambiguation strategy, and reuse guidance. Nothing material is missing.

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 100%, so the baseline is 3, but the description adds interpretive value on the q parameter (ticker ambiguity, first-row verification) and on entityType as the narrowing lever. It stops short of explaining cursor/limit mechanics beyond what the schema already states.

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?

States a specific verb and resource: convert eight named identifier forms into the entity id consumed by events and calls. This distinguishes it sharply from siblings like events, calls and mentions, which take ids rather than produce them.

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 frames the tool as exact-match-not-search, warns that prefixes and misspellings return nothing, and tells the agent to take the first row and verify the name or narrow with entityType. It also says to resolve once and reuse the id, which preempts repeated calls.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: what each level returns, that impacts is usually empty, the explicit non-returns (post text, sentiment score, price), and a hard pagination constraint ('Change any argument but limit and it fails; start again without it'). That cursor-invalidations rule is exactly the kind of behavioral trait structured fields do not convey.

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 purpose before diving into level semantics, then query modes, then exclusions. Dense but every clause is functional, with the plan-eligibility sentence being the only marginally expendable content. No wasted or repeated phrasing.

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 21-parameter, three-mode tool with an output schema, the description covers level selection, per-level parameter applicability, access patterns, and exclusion caveats. The one omission is explicit routing versus sibling tools (narratives, trending, calls) that also surface market developments; otherwise an agent has what it needs to call this correctly.

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

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

Schema description coverage is 100% and each of the 21 parameters already carries per-level applicability rules, defaults, and enums, so the baseline is 3. The description's summary (q for topic, entityIds from the entities tool, ids for up to 30 held items) largely restates what the schema documents in more detail, adding only the cross-cutting 'Not returned' note.

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?

States a specific resource and scope: 'What is happening in crypto and equity markets, written up from posts across many sources,' then defines three distinct read levels (events/storylines/arcs) with what each contains. An agent can tell this apart from siblings like narratives, trending, or market_chat without opening the schema.

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?

Gives clear operating context: which level to choose, and three named access patterns (topic via q, asset via entityIds from the entities tool, or fetching up to 30 held ids). It also states the free-plan window and that impacts is empty on most events. It stops short of naming sibling alternatives (e.g. narratives, trending) as substitutes, so the when-not-to-use case is left implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real behavioral value beyond that: the free-until-31-Oct-2026 pricing constraint, the crypto-only restriction, and the interpretive caveat to read crowdingPercentile rather than longShare because accounts nearly always lean long.

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 the scope statement, then organized view-by-view; dense but each clause carries machine-relevant facts (pricing, crypto-only, which field to read). Minor sloppiness in fragments like 'with hot on those heating up' keeps it from a 5.

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 9-parameter, output-schema-backed tool this covers the mode semantics, conditional parameter applicability, and pricing constraint well, and return values need not be explained. The one gap is routing guidance against the many sibling tools (trending, narratives, mentions) that could overlap with these views.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds semantic meaning beyond the schema's terse 'Which view to read' by explaining what each view mode actually returns (attention ranking, hourly bars plus live tick, posted-address ranking). It also notes trending contracts read 30 days at most, reinforcing the schema's from-field note.

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 names the resource ('whole-market views, no asset needed') and enumerates the three distinct view modes with what each ranks (mindshare by share of attention, call_book by long/short lean, trending_contracts by pasted addresses). An agent can distinguish this market-wide tool from asset-scoped siblings like entities, calls, or account_stats without opening the schema.

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?

It gives clear per-mode context (period applies to mindshare, order to call_book, minMentions and crypto-only to trending_contracts) and states the free-tier window, which shapes when to call it. It does not, however, name an alternative sibling tool or say when NOT to use this one.

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

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

Annotations already cover the safety profile (readOnly true, destructive false), and the description adds genuinely non-obvious behavior: the call consumes credits, cost varies by speed, sessionId enables multi-turn continuity, and the reply includes source links (links only, not their text). The credit cost is the key disclosure an agent cannot get from 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?

Three tight sentences, front-loaded with what the tool does, then cost/speed, then session continuation, then return shape. Efficient, though the speed-status sentence slightly duplicates schema wording.

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?

With an output schema present, return values needn't be fully explained, and the description still flags the sources array. Cost, speed, session continuation, and return highlights are covered; only sibling differentiation is missing for an 8-parameter 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 100%, so the schema already documents all eight parameters. The description only restates schema content for speed/cheapness and sessionId, adding no syntax or format detail beyond what's structured. Baseline 3 is appropriate.

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

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

States a specific verb and resource: asking Elfa for written market analysis grounded in social data. This is clearly distinct from raw-data siblings like market or narratives, though the description never names those siblings to make the boundary explicit.

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 real operating context — credits cost, the fast-vs-expert speed tradeoff, and passing sessionId to continue a thread — but offers no explicit when-to-use or when-not-to-use guidance relative to alternatives such as market or trending. Usage is implied rather than directed.

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

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

The description adds valuable behavioral context beyond the annotations (readOnlyHint, idempotentHint, destructiveHint all true/false). It discloses the 1-credit cost, specifies that it returns engagement metrics and links rather than post text, and clarifies that news mode returns X posts from tagged news accounts, not traditional articles. This is rich, non-contradictory context.

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 compact and information-dense, front-loading the core purpose, then cost, return structure, and mode explanations. Every sentence earns its place, and there is no redundancy or filler. It is well-structured and easy to parse.

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 (15 parameters, 3 modes) and the existence of an output schema, the description covers the essential decision points: modes, cost, return limitations, and the nuanced nature of news mode. Some parameter interactions (e.g., timeWindow, searchType) are left to the schema, but that is appropriate. It is nearly complete for an agent to call correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters and their meanings. The description adds no new parameter-level semantic detail beyond what the schema provides; it only clarifies the behavior of mode=news and the general return format. This meets the baseline for full schema coverage without surpassing it.

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: it retrieves social mentions from X and Telegram, with three distinct modes (top, search, news) explained. It differentiates itself from sibling tools by focusing specifically on mentions, and the description names the sources and what it returns, making the purpose unmistakable.

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 clear usage context for each mode (top ranks by engagement, search filters by keywords/account, news returns a news-sourced feed), which effectively guides the agent on when to use which mode. However, it does not explicitly compare this tool to alternatives or state when not to use it, so it falls short of a perfect score.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: the cost of '5 credits per call' and the warning that scope=keywords 'can take over a minute to return', which are not captured in 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?

Three sentences, each earning its place: purpose, cost/alternative, and scope explanations. Front-loaded with the core purpose, and no fluff or redundancy.

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

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

Despite having 9 parameters with no required fields, the description covers the key decision points: when to use qualitative analysis, the cost, the two scope behaviors, and latency expectations. The rich schema and output schema handle the remaining parameter and return details, so the description is complete for the agent's needs.

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 100%, so the baseline is 3. The description adds semantic nuance for the main scopes—'market extracts the narratives moving the market' and 'keywords summarises events'—which goes beyond the schema's brief 'broad sweep' and 'needs the keywords argument'. This adds meaningful context for parameter selection.

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 'Written narrative analysis with source links', distinguishing it from count-based tools like trending and mentions. It also differentiates between the two scopes (market and keywords), giving specific verbs and resources for each.

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

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

Explicitly says 'for when counts are not enough' and 'prefer trending or mentions when metrics will do', providing clear when-to-use and when-not-to-use guidance. It also explains the distinction between market and keywords scopes, including the latency caveat for keywords.

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

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

Annotations already declare a safe read-only, idempotent operation, so the bar is lower; the description still adds real behavior: track is null for accounts that never opened a position, track metrics only rank accounts with >=20 scored positions since late June 2026, standing measures attention not accuracy, and there is a free-tier window through 31 October 2026. It omits error/rate-limit behavior but the eligibility and null semantics are genuinely useful.

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?

Dense but front-loaded: the two ranking modes and the metric recommendation come early, caveats follow. Nearly every clause carries information, though the pricing sentence and the scoring-window detail are slightly buried mid-paragraph, making it a touch harder to scan than an ideal two-to-three sentence definition.

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?

An output schema exists, so return-format explanation is unnecessary, and annotations cover the safety profile. The description supplies the missing interpretive context — null track semantics, ranking eligibility threshold, metric trade-offs, and a tool handoff for follow-up. Only pagination ergonomics (deferred to the schema's cursor text) are left unaddressed.

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 100%, so the baseline is 3, but the description earns more by adding decision-level meaning: it recommends alphaScore over avgReturn and warns that avgReturn is not market-adjusted. It reinforces the scoredEpisodes pairing ('quote the number you ranked by') rather than just restating the schema's metric definitions.

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?

States a specific action and resource — accounts ranked — and splits it into two clearly named modes (standing vs track record via metric). It also names the sibling tools it relates to (calls) and the parameter that selects the ranking basis, so an agent can distinguish it from account_stats and calls without opening a schema.

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?

Gives explicit guidance for choosing the right metric: 'For the best callers use metric=alphaScore, not avgReturn' with the reason (big wins or a rally can top it), and points to the calls tool for drill-down. It covers when to use each mode but does not state when not to use this tool relative to account_stats or other ranking siblings.

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

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

Adds a credit cost per call, which is not in the annotations, and details scope-specific return behavior (ranked by mention volume, change against previous window, contract addresses). This supplements the readOnlyHint and idempotentHint annotations with practical behavioral context.

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 compact: three sentences that front-load the purpose and cost, then clearly map the scope options to their outputs. No filler or redundant restatement of the tool name or schema.

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 full input schema, output schema, and annotations, the description covers the essential behavioral aspects: cost, scope variants, and output type. It lacks explicit pagination/filtering guidance, but those are already documented in the schema, so the overall package is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances the scope parameter by explaining what each enum value returns (tickers vs contract addresses) and introducing the notion of 'change against the previous window', adding semantic value beyond the schema's simple enum listing.

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

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

The description clearly states the tool returns what is gaining social attention, with explicit scope variants: tokens ranked by mention volume with change, and contract addresses for Twitter/Telegram. It uses a specific verb ('returns') and identifies the resource (trending tickers/contracts), distinguishing it from sibling tools like mentions or narratives.

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

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

The description implies usage for surfacing trending social attention, but it does not explicitly contrast with alternatives such as mentions or narratives, nor does it state when not to use this tool. The scope explanations provide parameter-level guidance, but not tool-selection guidance.

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