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

Annotations already cover read-only/idempotent/non-destructive/open-world, and the description layers on context annotations cannot express: 1 credit per call, deprecation on 28 October 2026 with no extension, and the fact that output is raw metrics whose signal lies in ratios. That is exactly the value-add the dimension rewards.

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, then cost, then interpretation guidance, then the migration path. The deprecation clause ('still works today and keeps working until 28 October 2026, when it will be removed, and it is not being extended before then') is slightly redundant but each clause carries actionable information.

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-value documentation is unnecessary, and the description still covers cost, lifetime, output nature, and the recommended replacement. An agent has everything needed to decide whether to call it and how 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?

There is a single parameter at 100% schema description coverage, and the schema already explains that the username may include or omit '@'. The description adds no format or syntax detail beyond the schema, so the baseline of 3 applies.

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 (follower and engagement stats for an X account) and clarifies what it is not ('raw metrics, not a reputation score'), which lets an agent distinguish it from scoring or reputation tools among the many siblings. The verb/resource pairing is unambiguous.

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

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

Explicitly gives the use case ('judge whether an account's reach is real before weighting what it posts') and names the preferred alternative for new work ('mentions with mode=search'), plus the legacy status. When-to-use, when-not-to-start-new-work, and the alternative are all present.

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 substantive context beyond the annotations: a concrete cost ('1 credit plus LLM usage'), the non-destructive draft semantics ('nothing starts running until you activate it'), and a real capability boundary around Elfa's real-time account set. readOnlyHint=true is consistent with the draft-only behavior, and openWorldHint=true matches the LLM-driven generation.

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?

Four short sentences, each carrying a distinct payload: purpose, cost, activation path, and coverage limit. Purpose is front-loaded and nothing repeats the 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?

For a 3-parameter drafting tool with full schema coverage, annotations, and an output schema, the description covers everything an agent needs: what it produces, that it costs credits, that it is inert until activated, and where it will refuse to generate conditions.

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 an increment by telling the agent what content to put in 'message' (what to watch, threshold, firing action) rather than just pointing at the schema example. It says nothing about 'speed' or 'sessionId', which the schema already covers.

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') and immediately bounds the output ('only drafts the query'). It also carves out its coverage limit (tweet conditions only for accounts in Elfa's real-time set), which separates it from auto_draft and 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?

Explicit handoff chain: this tool drafts, auto_query_write activates, auto_validate checks anything written by hand. It also gives a negative condition ('for any other X account, write the condition yourself') and input advice ('say 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 declare non-readonly, destructive, non-idempotent, open-world behavior. The description adds genuinely non-obvious context beyond that: drafts never evaluate and never fire, and the cost model where everything is free except method=convert, which costs the same as creating a query. It does not mention that delete irreversibly removes a draft or the credential-refusal rule (which the schema covers).

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?

Four short sentences, zero filler, and the most decision-relevant fact (never fires, free unless converting) is front-loaded before the when-to-use cue. 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?

With an output schema present, return values need no explanation, and all 9 parameters are fully documented in the schema. The description supplies the missing behavioral/cost layer for a multi-method mutation tool; nothing critical to invoking it correctly is absent.

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 real value by quantifying the cost of method=convert relative to creating a query, which the schema only describes functionally. The other enum values (list/get/upsert/delete) are left entirely to the schema.

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

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

The description states a specific verb+resource ('Park an Auto query without activating it') and clearly delineates drafts from live queries, which separates it from auto_query and auto_query_write. However, it frames the tool solely around creating/parking a draft and never hints that the same tool also lists, gets, and deletes drafts, so the full purpose surface is under-described.

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?

'Use drafts when the user is still deciding' gives a clear, actionable when-to-use condition tied to user state. It implies the alternative (a live query) without naming auto_query or auto_query_write explicitly, so the routing is inferable rather than spelled out.

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 mark the tool destructive, open-world, non-idempotent, and not read-only. The description adds important context beyond annotations: credit cost, LLM usage, unattended firing behavior, and the need for user confirmation.

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 tightly written sentences, front-loaded with the core write operations, followed by cost and safety guidance. No wasted language.

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?

Complete for a destructive, open-world write tool: it covers operations, costs, unattended side effects, validation prerequisites, and user confirmation. Output schema exists, so return values need not be explained.

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 method, query, queryId, title, and description are already documented in the schema. The description adds operational guidance but little additional parameter-level semantics beyond what the schema provides.

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 write operations (activate/create, cancel, delete) on the Auto query resource, clearly distinguishing this tool from read/query siblings like auto_query and validation sibling 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?

Gives explicit when-to-use guidance, requires validation with auto_validate first, and instructs the agent to confirm cost and action with the user before calling. It also notes cancel and delete are free.

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, but the description adds genuinely non-obvious behavioral context: the call is free, it returns an estimated cost that must be surfaced, and it explains per_post billing (creditsPerPost charged per post from the account, excluding replies and reposts, matched or not, on top of estimatedCredits). That billing model is unavailable in the structured fields.

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 action and the mandate to run it before auto_query_write, and every sentence carries information. The middle sentence on tweetAccounts billing is long and dense, packing several caveats (not replies, not reposts, matched or not) into one clause chain, which slightly hurts readability.

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

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

With an output schema present, return values need no explanation, and the description covers the remaining gaps an agent needs: validation modes, cost semantics, the pre-write sequencing requirement, and the user-facing disclosure obligation.

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 parameters are already documented; the description adds only light framing ('Pass either an inline query or a draftId') plus mode semantics for method=symbol. The tweetAccounts/billing text is more behavioral than parameter-level, so this sits modestly above the high-coverage baseline.

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?

Opens with a specific verb+resource ('Check EQL syntax and get a cost estimate') and explicitly positions itself as a pre-flight step ahead of auto_query_write. It also carves out the method=symbol variant, so the agent can distinguish both modes from siblings like auto_build and auto_query_write.

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?

States an explicit mandate ('Always run this before auto_query_write'), a required downstream action ('show the estimated cost to the user'), and a conditional alternative mode ('method=symbol instead checks that a symbol has market data... before you build price or ta conditions'). When-to-use and the alternative path are both spelled out.

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, idempotent, openWorld, non-destructive), lowering the bar. The description still adds genuine behavioral context: what is deliberately excluded from results, and the fact that a particular status/from combination produces a point-in-time holdings snapshot. It says nothing about auth or rate limits, so it is short of a 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?

The purpose is front-loaded and the level breakdown follows in a single dense block with no filler sentences. It loses a point for the malformed opening ('Telegram..' with a doubled period) and for compressing six level definitions into one run-on paragraph rather than clearly delimited units.

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, and the description covers the mode selection that is the main source of ambiguity for a 13-parameter tool. Filter interplay (ids vs from, entityId requirement for positioning, cursor invalidation) is delegated to schema text, which is reasonable given its 100% coverage.

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, and the description earns above baseline by defining what each level value actually contains ('each post that opened, added to, trimmed, reaffirmed...' vs 'each position from open to close, with entry and exit prices'). That is real meaning the schema's one-line 'Which level to read' does not carry.

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

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

The description states precisely what the tool returns and enumerates all three modes (calls, episodes, positioning), so an agent knows this reads account position activity rather than post text. It is specific about the resource and the shape of each level, but it never names or contrasts sibling tools (mentions, events, narratives, account_stats), which is what a 5 requires.

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 level is given an explicit use case, and it goes further by showing a concrete filter combination ('level=episodes with status=open and from set to now reads what every matching account holds right now'). It also states an exclusion ('Not returned: post text or a recommendation'). What's missing is any routing to alternative tools when this one is the wrong choice.

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 read-only, idempotent, open-world, and non-destructive traits. The description adds substantial behavioral context beyond that: exact match semantics (prefix or misspelling returns nothing), ticker non-uniqueness and ambiguity handling, and the family-id grouping concept (WBTC and cbBTC share a Bitcoin family id). This is rich, non-obvious behavioral disclosure.

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 the core purpose and each sentence adds useful information, but it runs longer than necessary and includes a minor typo ('take..'). It is efficient on balance, though not as tight as a perfect 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?

Given an output schema exists, the description need not cover return values or pagination format. It fully addresses the tool's complexity: what input forms are accepted, exact-match behavior, ambiguity resolution, and family-id reuse. 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 description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds only marginal parameter meaning: it lists input forms for `q` (already exemplified in the schema) and briefly advises narrowing with `entityType` (also described in the schema). 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?

The description states a precise verb ('Turn a ticker, ... into the entity id') and resource ('entity id that events and calls take'), and explicitly distinguishes itself from search-based tools. An agent can tell this is a resolver, not a search, without opening any 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 usage context: exact matching only, no fuzzy/prefix matching, and a disambiguation strategy when tickers are non-unique ('take the first row and check its name, or narrow with entityType'). It does not name a specific sibling alternative, so it falls short of the explicit when/when-not/alternatives standard.

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, openWorld, idempotent, and non-destructive, so the safety profile is covered. The description adds valuable behavioral context beyond that: it discloses that impacts is empty on most events, that post text, sentiment scores, and prices are not returned, and that arcs take no from parameter.

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 but well organized: purpose first, then level definitions, then query modes, then explicit exclusions. Minor waste exists (a stray double period and a slightly fragmented opening), but every sentence carries information.

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 complex 21-parameter tool with an output schema, the description covers the conceptual model (three levels), the main query strategies, and the data boundaries an agent must know. Return format details are delegated correctly to the output schema and field descriptions.

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

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

With 100% schema description coverage, baseline is 3, but the description meaningfully elaborates the level parameter by explaining what events, storylines, and arcs contain. It also clarifies that q makes from optional and that ids fetches work without from, adding semantic context beyond the schema's field-level notes.

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 purpose (crypto/equity market events synthesized from posts) and then defines the three hierarchical levels (events, storylines, arcs) in concrete terms. An agent can distinguish what each level returns without consulting the schema, and the sibling relationship to the entities tool is noted for entityIds.

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 clearly explains the three access patterns — topic search with q, asset filtering with entityIds, and direct fetching with ids — and notes limits (up to 30 ids). It does not explicitly contrast this tool against siblings like narratives or trending, so it stops short of full when/when-not routing.

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, idempotent, openWorld, non-destructive), so the bar is lower. The description still adds substantive behavioral context beyond them: accounts lean long almost always so longShare is misleading, call_book emits one bar per hour plus a live tick, and trending_contracts is crypto-only. That is genuinely useful data-behavior disclosure.

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 scope statement ('Whole-market views, no asset needed') followed by one clause per view. Dense but nearly waste-free; the trailing aside about unnamed contracts is a slight indulgence but carries information.

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 spelled out, and it covers all three view modes plus the range/required-parameter behavior handled in the schema. What is missing is the relationship to sibling tools, which would matter for a multi-view, zero-required-parameter entry point.

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 schema already maps each parameter to its view (view=mindshare on period, view=call_book on order, etc.), so the description largely restates structured data. Its one real addition is the crowdsPercentile-vs-longShare advice, which is minor relative to nine parameters.

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

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

The description names a specific verb+resource per mode: mindshare ranks assets by share of attention, call_book is the crowd's long/short lean, trending_contracts ranks contract addresses by pasted posts. Each view's purpose is concrete and readable. However, it never distinguishes this tool from siblings like `trending`, `narratives`, or `mentions`, which an agent must guess at.

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?

Guidance is mostly interpretive rather than selection-oriented: read crowdingPercentile rather than longShare, trending_contracts is crypto only, unnamed addresses are often worth watching. There is no explicit statement of when to choose `market` over `trending`/`narratives`, and no when-not condition.

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 read-only, open-world, non-idempotent safety profile, and the description adds genuinely new behavioral facts: the call consumes credits, cost scales with the speed tier, and replies carry source links (links only, not text) that can be cited or checked. It stops short of stating credit amounts, rate limits, or failure behavior, which keeps it below a 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?

Four short sentences, front-loaded with what the tool produces, then cost, then session continuation, then return content. Each sentence carries distinct information, with only minor overlap between the credit/speed sentence and the schema's speed description.

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 annotations covering safety, a full output schema covering returns, and 100% schema coverage for all eight parameters, the description supplies exactly the extras an agent needs: credit consumption, speed/cost tradeoff, session continuation, and the nature of the source links. Nothing material for correct invocation 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 description coverage is 100%, including the analysisType dependency map and the speed tradeoff, so the schema already carries most parameter meaning. The description largely restates the speed/cost point and the sessionId continuation rule rather than adding new semantics, which fits the baseline-3 case where the schema does the heavy lifting.

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 uses a specific verb+resource combination ('Ask Elfa for written market analysis grounded in its social data'), which is clearly distinguishable from list/lookup siblings like mentions or trending. It does not, however, name the closest sibling ('market') or explain how this differs from it, leaving the agent to infer the boundary.

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?

Guidance is given for parameter choice ('fast is the cheaper option', 'Ask for expert when the answer needs deeper reasoning', 'Pass sessionId ... to continue the same conversation'), but nothing says when to pick this tool over a sibling such as market, narratives, or calls. Usage is implied through cost/speed tradeoffs rather than stated selection criteria.

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 read-only, idempotent, and non-destructive. The description adds cost (1 credit per call) and return format (engagement metrics and link, not post text), which are valuable behavioral details beyond the annotations.

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

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

Front-loaded with key facts (source, cost, return format), then mode details. Every sentence is informative and there is no wasted text.

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

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

Given the tool's complexity (15 params, 3 modes), the description covers cost, return limitations, and mode behaviors. Output schema exists, so return values needn't be explained. Minor gaps like rate limits beyond credit are acceptable; annotations cover the safety profile.

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 baseline is 3. The description adds meaning about mode behavior (e.g., top ranks by engagement, search filters by keywords or account, news is X posts from news-tagged accounts), enhancing the parameter semantics beyond the schema's requirement notes.

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 (social mentions from X and Telegram) and what it returns (engagement metrics and link, not post text). Clear on its own, but does not explicitly distinguish from siblings like trending 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?

Describes what each mode does (top ranks by engagement, search filters by keywords or account, news returns a feed), which implicitly guides usage. However, it lacks explicit advice on when to choose this tool over sibling tools or exclusions.

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, idempotent, non-destructive, openWorld), and the description adds genuinely new behavioral facts: per-call credit cost, that scope=keywords can exceed a minute to return, and that results include source links. Cost and latency disclosure are exactly the kind of context annotations cannot carry.

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?

Four sentences, each carrying distinct payload: capability, cost/alternative steering, then per-scope behavior with a latency warning. The alternative-routing sentence is front-loaded ahead of mode details, which is the right order for a selection decision.

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 9 fully documented parameters and an output schema present, the description need not explain return shapes and instead spends its words on the non-schema facts (cost, latency, mode semantics). Nothing an agent needs to call this 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 3 baseline applies, but the description adds real meaning beyond it by describing what each scope returns ("extracts the narratives moving the market" vs "summarises events for keywords you supply") rather than the schema's vague "market is a broad sweep." It does not cover the date/window parameters, which the schema handles.

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 ("Written narrative analysis with source links") and immediately scopes it against metric-based tools. An agent can distinguish this from trending, mentions, and market without opening any 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?

Explicitly routes the agent: use trending or mentions when counts/metrics suffice, and use this only when "counts are not enough." It also gives the cost trigger (5 credits per call) that should drive the decision, plus the latency caveat for scope=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 readOnly/idempotent/non-destructive/open-world, so the safety profile is covered. The description adds real domain behaviour beyond that: track is null for accounts that never opened a position, track metrics only rank accounts with at least 20 scored positions, the window is 'every position since late June 2026', and standing measures attention rather than accuracy. It does not mention rate limits or cost, but the semantic caveats are unusually substantive.

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, followed by caveats, metric guidance, and a cross-tool pointer — a sensible ordering. Nearly every sentence carries information, though there are typos ('callers..', trailing period) and the standing/track definitions are dense enough to need a second read.

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 shape need not be explained, and the description still calls out scoredEpisodes to quote alongside the ranking metric. It covers the ranking semantics, null behaviour, the 20-position threshold, and the date window. Pagination mechanics are left to the schema, which is acceptable.

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 parameter meaning is already largely carried by the schema (baseline 3). The description still adds value the schema lacks: it explains that standing means attention, not accuracy, and why avgReturn can be misleading relative to alphaScore. It leaves hitRate entirely to the schema, so it is not a full 5.

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: accounts ranked by standing, or by their track record when a metric is supplied. It also routes the agent to a sibling ("Pass a handle to the calls tool to see its positions"), so it is distinguishable from neighbours like calls and account_stats. The phrasing ('track record as callers', stray double period) is slightly muddled, keeping it 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?

Explicitly says which metric to choose and why: 'For the best callers use metric=alphaScore, not avgReturn, which a few big wins or a rally can top.' It names the condition that selects an alternative and warns against the tempting wrong choice. It also gives a cross-tool next step (hand a handle to 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, openWorld and non-destructive, so safety is covered. The description adds context those annotations cannot: a per-call cost of 1 credit and what each scope actually returns (mention-volume ranking with change vs. the previous window). It doesn't cover rate limits or whether results are cached/delayed, but the added detail is substantive.

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, zero filler. The purpose leads, the cost disclosure follows immediately, and the scope semantics come last where they are most actionable.

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 explained, and all seven parameters are fully described in the schema. Cost and scope semantics are covered. The remaining gap is the absence of sibling routing guidance in a crowded namespace.

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 earns the bump by explaining what the scope enum values produce — 'tokens' means tickers ranked by mention volume with change against the previous window, while the two contracts scopes return trending contract addresses — which is meaning the enum's one-line schema description does not supply.

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 opening line pins down the resource precisely: socially trending items ranked 'right now', and the scope breakdown tells the agent it can return either tickers or contract addresses. It is clear what the tool returns, but it never distinguishes itself from siblings like 'mentions' or 'narratives', which plausibly cover adjacent ground.

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 scope values imply when each mode applies, and the timeWindow/from-to note hints at range selection, but there is no explicit statement of when to reach for this tool rather than 'mentions', 'narratives', or 'market'. Usage is inferable rather than stated.

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