Perception

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds substantive context beyond annotations: the corpus scope (~800 tracked voices across X and LinkedIn), the exclusion of news outlets, the per-cohort response structure, and the net sentiment range (-1 to +1). This meaningfully informs an agent about what the tool will and won't return.

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

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

The description is well-structured with clear sections, front-loaded with the core purpose and immediately followed by usage examples. Every sentence adds value; the response-format guidance and citation requirement are placed at the end without bloating the main purpose.

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

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

There is no output schema, so the description correctly takes on the burden of explaining return values: per-cohort posts, positive/negative percentages, and net sentiment. It also covers semantics, scope, exclusions, and rendering guidance, leaving an agent with everything needed to invoke and interpret the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description reinforces the meaning of 'topic' with examples and lists the cohort roles, but it doesn't add substantial param-level detail beyond the schema. Baseline of 3 is appropriate given the schema carries the parameter documentation load.

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 ('breaks down') and resource ('digital-asset conversation') with a clear focus on cohort roles, and explicitly differentiates itself from aggregate sentiment tools. The examples ('are developers more bearish than CEOs?') make the tool's purpose immediately recognizable.

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?

Dedicated WHEN TO USE section gives concrete example queries and maps them to the topic parameter. The WHY IT'S DIFFERENT section explains when this tool is preferable to aggregate sentiment tools and explicitly notes that news outlets are excluded by design, preventing misuse.

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, and non-destructive behavior. The description adds useful behavioral details beyond annotations: the exact output shape, the expectation to create a visual artifact, personalization behavior via the context parameter, and the requirement to cite Perception.

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 somewhat long but organized with clear section headers and front-loaded purpose. Every section adds relevant guidance for the agent, including response formatting and citation, so the length is justified.

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 no output schema, the description adequately covers what the tool returns (comparison table metrics) and how results should be presented. Together with the input schema, annotations, and use cases, the agent has enough context to select and invoke the tool correctly. It does not cover edge cases like unknown entity names, but that is a minor gap.

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 reinforces what entities and context do, and adds a response-format nuance for the context parameter, but it does not substantially go beyond the schema's own parameter descriptions.

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

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

The description clearly states the tool's function: compare media coverage of 2-5 digital asset companies side-by-side, returning a comparison table with mention volume, sentiment breakdown, and top sources. This is specific and distinguishes it from sibling tools like perception_get_entity_profile or perception_search_companies.

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?

A dedicated 'WHEN TO USE' section gives concrete example queries and scenarios, such as competitive analysis and partnership due diligence. It provides clear context but does not explicitly state when not to use it or name alternative tools for other cases.

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?

Beyond the annotations, the description discloses meaningful behavior: it requires no query, compares data against a 7-day baseline, tailors the briefing when context is supplied, creates a visual artifact, and always cites Perception as the data source. These are behavioral expectations not captured by the read-only/idempotent 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?

Though longer than average, the description is organized into clearly labeled sections (WHEN TO USE, PERSONALIZATION, RESPONSE FORMAT) and the opening sentence immediately states the core purpose. Every section contributes actionable guidance and there is no filler.

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 no output schema, the description supplies the essential return expectations: 3-5 key items, anomaly/sentiment/volume/narrative signals, 7-day baseline comparison, visual artifact presentation, and source citation. It also covers both parameters and gives clear invocation examples, so an agent has everything needed to call 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?

The input schema already fully describes both optional parameters, so the baseline is 3. The description adds extra value by explaining how to populate the context parameter with portfolio details and strategic priorities and how Perception will adapt the briefing accordingly. The focus parameter is not discussed in the description, but the schema covers it comprehensively.

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 and resource: it surfaces the 3-5 most important things happening in digital assets, including anomalies, sentiment shifts, volume spikes, and narratives. It is clearly a daily briefing tool with a 7-day baseline comparison, but it does not explicitly distinguish itself from sibling tools such as perception_media_radar or perception_get_intelligence_digest.

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 provides concrete WHEN TO USE triggers like 'What should I know today?' and 'Starting a research session — use this first to orient', which gives an agent clear context for selecting the tool. However, it does not name alternative tools or state when not to use this tool, stopping short of explicit exclusion guidance.

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 establish read-only, idempotent, and non-destructive behavior, so the description's burden is lower. It adds useful context beyond annotations: the coverage universe of 70 digital asset companies, the data fields returned, and the personalization behavior of the context parameter. It does not mention rate limits or exact response format, but the tool is simple and no output schema exists.

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

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

The description is well-organized into front-loaded sections: WHEN TO USE, COVERAGE, DATA, BEST PRACTICES, and PERSONALIZATION. Every section contributes actionable guidance, and the example queries make the tool's intent immediately understandable without padding.

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 read-only tool with three parameters and no output schema, the description provides everything an agent needs: purpose, use cases, coverage, returned data, best practices, and personalization guidance. Nothing essential is missing for correct selection and invocation.

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?

All three parameters are fully documented in the input schema (100% coverage), so the baseline is a 3. The PERSONALIZATION section reinforces the purpose of the context parameter, but it does not add materially new parameter semantics beyond what the schema already explains.

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 operation — getting Wall Street analyst ratings, price targets, and upgrades/downgrades — and limits scope to crypto-related public companies. It is clearly distinct from sibling topics like sentiment, insider activity, and earnings, though it never explicitly names a sibling to differentiate against.

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 WHEN TO USE section provides concrete example queries and the BEST PRACTICES section recommends pairing with search_companies and get_market. It gives clear context for when to use the tool, but it does not state exclusions or direct users to alternative tools for different scenarios.

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=true and idempotentHint=true, so the safety profile is covered. The description goes further by disclosing the returned fields (full body, outlet, author, publication date, sentiment) and the required output behavior of linking to the original article and citing Perception. This adds meaningful context beyond the structured annotations.

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

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

The description is well-structured with a clear opening, a WHEN TO USE section, and an output citation instruction. There is minor redundancy between the opening sentence and the first bullet, but the description remains compact and every section 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?

For a simple read-only tool with two well-documented parameters and no output schema, the description is complete. It states the input requirement (URL from prior search), the return payload, when to use it, and the required citation format. No essential information for invoking the tool correctly appears to be 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 fully documents both parameters. The tool description does not add significant parameter-level detail beyond what is in the schema, though it reinforces the URL source expectation by mentioning it comes from search_articles or media_radar. Baseline 3 is appropriate given full 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 and resource: 'Get the full text of a specific source by its URL.' It also clarifies the tool's scope by listing supported content types (article, social post, transcript, filing) and explicitly distinguishes it from lighter search previews. This makes it easy for an agent to recognize the tool's unique role among siblings.

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

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

The description provides explicit when-to-use bullets, such as digging into a specific search result or needing full context for analysis. It also gives a clear exclusion: 'For general analysis, content previews from search_articles are usually sufficient — only use this for deep dives.' This directly routes the agent to the appropriate tool and names the alternative.

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=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about high-velocity BigQuery archival data and a mandatory attribution requirement ('Always cite Perception'), but it doesn't disclose details like pagination, result limits beyond the schema defaults, or what constitutes a 'tracked handle.' This is adequate but not especially rich.

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, the WHEN TO USE examples are useful and compact, and the citation note is a single sentence. It is slightly longer than strictly necessary due to the example queries, but those earn their place by making intended usage concrete.

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 simple two-parameter read-only tool with annotations covering the safety profile, the description provides the essential facts: what to fetch, the source archive, and the attribution requirement. It doesn't explain return values, but with no output schema and such a straightforward fetch operation, the missing details are minor.

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 both 'handle' and 'limit' with defaults and bounds. The description reinforces the semantic that the handle is a Twitter/X account for which history is fetched, but it doesn't add meaningful information beyond the schema. Baseline 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?

The description opens with a specific verb and resource: 'Fetch chronological Twitter/X history and posts of any tracked handle from Perception's high-velocity BigQuery archive.' It clearly distinguishes itself from sibling tools by focusing on Twitter/X history retrieval, and the name 'brains_corpus' plus this scope leave little ambiguity.

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?

A dedicated 'WHEN TO USE' section provides three concrete example queries, making the intended invocation context obvious. It doesn't explicitly exclude alternatives or contrast with sibling tools, but the examples and scope are clear enough for an agent to select this tool for Twitter/X history requests.

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?

Even though annotations already mark this as a read-only, idempotent, non-destructive operation, the description adds significant behavioral context: 13F data lags up to 45 days, figures are the most recently reported rather than live, QoQ flow is computed across all filers, Bitcoin treasury data is self-reported, and no future price claims are made. This goes well beyond the annotations.

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

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

The description is longer than typical but well structured with clear sections: overview, when to use, what it reports, and best practices. Every sentence carries useful information for invocation or interpretation, and the core purpose is front-loaded. There is no filler 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?

With no output schema, the description does the necessary work of explaining what the tool returns: institutional holders, flow summary, beneficial owners, and treasury holdings. It also covers important caveats about data freshness and source reliability, making the tool's behavior fully understandable to an agent.

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 explains both ticker and context parameters. The description reinforces that the tool applies to US-listed companies and that context is used for framing, but it does not add new parameter-level semantics beyond 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 opens with a specific verb and resource: 'Get the institutional capital picture for a US-listed company,' then enumerates exactly what is included (13F holders, QoQ flow, 13D/G owners, Bitcoin treasury holdings). This clearly differentiates it from narrative or sentiment siblings like perception_get_sentiment or perception_narrative_momentum.

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 'WHEN TO USE' section gives concrete example queries and explicitly routes the agent to alternatives: perception_get_entity_profile or perception_get_divergences for the narrative side, and perception_get_insider_activity for a fresher discretionary view. This is explicit when-to-use and when-not-to-use guidance.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds meaningful behavioral context: it returns category names with counts, supports personalization via context, and requires citing Perception. It doesn't cover data freshness or exact count semantics, but for a read-only aggregation tool this is a strong 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 longer than average but every section earns its place: a clear opening, practical WHEN TO USE examples, actionable BEST PRACTICES, the category enum, and a personalization note. It is front-loaded with the core purpose and organized so an agent can quickly extract the needed 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 no output schema, the description appropriately explains what is returned. All parameters are documented and given usage nuance. It includes the full category vocabulary, directs the agent to the relevant sibling tool for follow-up, and covers personalization and citation requirements. Nothing essential is missing for correct invocation.

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 value beyond the schema by mapping hours to concrete use cases (168 for weekly, 720 for monthly) and by explaining how the context parameter affects highlighting and personalization. This goes beyond the property descriptions already present.

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 clear, specific action: 'Get trend category distribution showing which narrative types are most active in digital assets media.' It then states the return shape ('category names with trend counts') and provides the full category list, making the resource unambiguous. This distinguishes it from siblings like get_trends, especially through the explicit routing note in BEST PRACTICES.

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 WHEN TO USE section gives concrete example user questions and frames the tool as an entry point for narrative exploration. BEST PRACTICES provides specific hours values for weekly vs. monthly views and explicitly directs the agent to use get_trends after identifying dominant categories, which is strong alternative-routing guidance.

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?

Even with readOnlyHint and idempotentHint already set, the description adds extensive behavioral context: time windows for sentiment and insider behavior, exclusion of 10b5-1 plans, cluster definition, 13F reporting lag, daily computation time, non-predictive nature, and the meaning of zero divergences. No contradiction with annotations.

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

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

The description is well-structured with clear headings, front-loaded purpose, and bulleted details. It is long but information-dense. Minor redundancy exists in repeating 'It surfaces disagreement' and the investment-advice disclaimer, but these do not significantly hurt usability.

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?

There is no output schema, so the description properly carries the return-value burden by listing the ranked fields: entity, ticker, narrative direction, behavior direction, cluster flag, evidence trail, and composite score. It also covers computation cadence, data sources, practical follow-ups, and expected empty results, making it complete for decision and invocation.

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 reinforces date semantics through 'today's' and 'computed daily at 09:30 UTC,' but it does not add meaningfully to the context parameter beyond what the schema already says. It does not need to compensate for schema gaps.

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 and resource: 'Get today's narrative-vs-behavior divergences.' It precisely defines what counts as a divergence (media coverage direction and observable insider behavior moving in opposite directions), which differentiates it from sibling sentiment, insider activity, and radar tools.

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

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

The 'WHEN TO USE' section lists concrete user queries and the screening context, making the intended use clear. It also names follow-up alternatives (perception_get_insider_activity, perception_search_companies), but it does not explicitly say when NOT to use this tool, so it stops short of a full exclusion-based guide.

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; the description adds non-obvious behavioral details: data source and construction (Claude AI on full transcripts), coverage constraint (50+ crypto/fintech/Bitcoin treasury companies), reliability caveat for the directness score (r ≈ -0.02 in a 455-call backtest), and citation requirement. This substantially goes beyond annotations.

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

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

Structured into labeled sections (WHEN TO USE, COVERAGE, DATA, BEST PRACTICES, PERSONALIZATION) with front-loaded purpose. Though longer than minimal examples, every section earns its place by carrying decision-relevant content; there is no filler or tautology.

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 no output schema, the DATA section enumerates all return components (tone, summary, Evade-o-Meter, participants, quotes) and the HOW-TO-WEIGH section clarifies score interpretation. Combined with coverage, examples, personalization guidance, and citation instruction, nothing critical is missing for an agent to invoke and present results 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?

Input schema covers 100% of four parameters, so baseline is 3; description adds value for the `context` parameter by explaining to pass portfolio details so Perception can highlight user-relevant intelligence. It also reinforces ticker examples and US-listing coverage, but most parameter semantics remain in 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?

States a specific verb and resource ('Get AI-analyzed earnings call intelligence for a public company') plus headline signal. Describes components and coverage, making it clearly distinct from sibling sentiment/research tools even without an explicit contrast. The name and content align.

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 a WHEN TO USE section with concrete query examples and a catch-all ('Any question about earnings calls...'). It names complementary tools (get_analyst_ratings, get_insider_activity) in best practices but does not explicitly state when not to use this tool or name a direct alternative, so it stops short of a full 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 already establish read-only, idempotent, non-destructive behavior, so the description improves on that by adding the supported-entity scope, the requirement to cite Perception (perception.to), and the personalization behavior driven by the context parameter. It does not cover failure modes for unsupported entities, but the disclosed scope helps an agent know when not to call it.

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 longer than average but well-structured into labelled sections, with the overview front-loaded before examples and alternatives. Each section adds practical value, though the PERSONALIZATION section partly restates the context parameter description and could be trimmed.

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?

There is no output schema, so the description carries the burden of describing return value shape; it names the four result categories (media coverage, analyst ratings, active trends, related entities). It also provides supported-entity scope, date-range semantics via schema, and routing guidance, leaving only edge cases like unsupported-entity errors undocumented.

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 actionable parameter guidance by recommending canonical names, tickers, or entity IDs and illustrating valid forms ('strategy', 'MSTR', 'Strategy'). It also explains how the context parameter changes behavior, which the schema only partially conveys.

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 and resource — 'Get a complete intelligence profile' — and names the exact content returned: media coverage, analyst ratings, active trends, and related entities. It also gives concrete example queries and supported entities, making it easy to distinguish from sibling tools like get_trends or get_analyst_ratings.

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 'WHEN TO USE' section maps natural-language user requests to this tool with concrete examples. 'BEST PRACTICES' explicitly names alternatives, including 'Use get_analyst_ratings for more detailed analyst data' and 'For broad market questions, use get_trends instead.'

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?

Beyond the readOnly/idempotent annotations, the description adds a significant interpretive trait: the numeric score has no predictive relationship with returns (r≈-0.02 in a 455-call backtest) and must be presented as 'how they communicated, never as a trading signal'. It also tells the agent that the qualitative payload is the useful part. This is substantive behavioral context not inferable 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?

Despite being longer than average, the description is tightly organized into purposeful sections: purpose, when-to-use, what-the-score-means, and data provided. Every sentence contributes—the example queries are illustrative, the backtest caveat is important, and the alternative-tool pointer saves agents from misrouting. The main purpose is front-loaded in the opening sentence.

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 no output schema, the description appropriately details the two return views (leaderboard and specific ticker) including the fields provided (score, classification, dodged questions, topic breakdown, historical trend). It also includes the crucial interpretation caveat and points to the sibling tool for deeper analysis. Nothing essential for correct use 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%: both 'ticker' and 'context' already have explanatory descriptions, including the optionality mapping to the leaderboard when ticker is omitted. The description adds example tickers and query phrasings that slightly reinforce usage, but does not materially surpass what the schema already conveys. 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 opens with a specific verb and resource ('Get Evade-o-Meter analysis for public companies') and immediately enumerates the core outputs: how directly management answered, which questions were dodged, and topic breakdown. It explicitly distinguishes itself from the sibling perception_get_earnings_intelligence by positioning that tool as the validated analytical lens, making the resource boundary clear.

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

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

A dedicated 'WHEN TO USE' section lists concrete user queries for both the leaderboard and specific-ticker modes. It also gives an explicit exclusion: 'For the validated analytical lens on earnings calls, use perception_get_earnings_intelligence' and warns to never present the score as a trading signal. This provides both when-to-use and when-not-to-use guidance, plus a named alternative.

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 as read-only and idempotent, but the description adds substantial behavioral context: it distinguishes 'days open' from 'change over window,' warns against conflating the two dates, states that the response explicitly reports the observation window, and explains coverage limits. This goes well beyond what annotations could 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?

The description is front-loaded and uses helpful section headers, but it is longer than needed. The 'WHY IT MATTERS' section is more motivational than operational, the DATA section contains a garbled phrase ('the current book by month') and repeats 'change over the observed window,' and some content duplicates the schema descriptions.

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?

There is no output schema, so the description carries the burden of explaining return expectations. It does so well: open role count, split by function, median days open, change over observation window, newest postings, and the explicit observation-window warning are all mentioned. Coverage limits and required data-source citation are also covered, making this complete enough for an agent to invoke and interpret results 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?

The input schema provides 100% parameter coverage, including explanatory text for company, context, and role_category. The tool description mostly restates this guidance, for example the personalization paragraph mirrors the context parameter description, and the role_category mapping already exists in the schema. Since the description adds little new parameter-level meaning, the 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 a specific verb and resource: 'Get open job postings and hiring posture for a digital-asset company, from its public applicant-tracking board.' This clearly identifies the hiring domain and data source, and distinguishes it from the broader perception sentiment, market, and research tools in the sibling list.

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 'WHEN TO USE' section provides concrete example queries, maps role_category values to intentions, and recommends pairings with get_entity_profile. It also includes a useful coverage caveat about untracked companies. However, it does not explicitly name alternatives or state when not to use this tool instead of a sibling like perception_hiring_leaderboard, so it falls just short of fully explicit routing guidance.

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, and non-destructive, so the description's job is to add behavioral depth, and it does: default response shape, differing measurement windows, reliability values, correlation caveats, and explicit warnings like never presenting Ethereum's 7-day window as a same-day divergence. This goes well beyond what annotations or the schema 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?

The description is long, but it is well-structured with clear headings (PORTFOLIO METRICS, PERCEPTION INDEX SCOPES, READING THEM TOGETHER, WHEN TO USE, BEST PRACTICES) and every section carries useful agent-facing guidance. It is not minimal, but the density and organization justify its length; a small amount of redundancy with the schema exists.

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 no output schema, the description carries the full burden of explaining return behavior, and it does: it lists what default and portfolio selectors return, covers scopes and reliability, explains cross-scope interpretation pitfalls, and gives best practices for framing the response. An agent has enough context to invoke the tool and interpret its output 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%, which sets a baseline of 3, but the description substantially enriches every parameter: scope is explained with windows and reliability, metric is expanded into the full portfolio family, context gets personalization guidance, and include_history clarifies the bounded historical series. It adds meaning far beyond the enum labels and short schema descriptions.

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

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

The first sentence states a specific verb and resource: "Get Perception's proprietary index portfolio." It then enumerates the metric families and scopes, and explicitly contrasts itself with get_market in the WHEN TO USE section, so an agent can distinguish it from siblings like perception_get_sentiment and perception_get_market.

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 WHEN TO USE section provides concrete triggers ('What's the market sentiment?', 'How is Bitcoin coverage specifically?', 'Is sentiment diverging from price?') and explicitly directs when to pass scope='bitcoin' rather than reading the market number. It also names get_market as an alternative and explains why this tool gives a richer answer.

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 signal read-only and idempotent behavior, and the description adds substantial behavioral context: 58-company coverage, open-market vs. 10b5-1/option-exercise handling, 90-day cache behavior, cluster alerts, and the AI-generated narrative overlay. This goes well beyond what annotations alone provide and contains no contradiction.

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

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

The description is longer than average but well-organized into labeled sections (WHEN TO USE, COVERAGE, DATA, BEST PRACTICES, PERSONALIZATION) with the core purpose front-loaded. Some content, particularly the repeated example questions, could be trimmed, but the structure keeps it scannable and useful.

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 read-only data-retrieval tool with no output schema, the description fully prepares the agent: it lists the returned data fields, explains the coverage scope, flags the 90-day cache limit, covers the optional context parameter, and gives interpretation guidance. Nothing critical is missing for correct invocation and result handling.

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

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 notable meaning beyond the schema: it explains startDate/endDate are for querying full Form 4 history instead of the 90-day cache, and it describes how the context parameter personalizes output. This elevated usefulness justifies a 4.

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 and resource: 'Get insider trading activity and narrative signals for a US-listed company' and immediately clarifies it covers SEC Form 4 filings. This clearly distinguishes it from the broader Perception sibling tools by specifying the exact data domain. Example questions reinforce the intended scope without ambiguity.

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?

A dedicated WHEN TO USE section lists concrete example questions, and BEST PRACTICES explicitly recommends pairing with get_analyst_ratings and search_companies. It stops short of stating when not to use this tool or naming negative alternatives, but the guidance is strong enough for an agent to select it appropriately.

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds substantive behavior: scans 6 signal sources daily at 9:30 AM UTC, ranks by signal convergence, and synthesizes narratives for top 5 entities. No contradiction with annotations.

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

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

The description is long but well-organized with clear headers and front-loaded core definition. Example queries and signal lists add practical utility, though some redundancy could be trimmed.

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

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

For a tool with no output schema, the description adequately conveys what the result looks like: a ranked cross-signal summary with AI narratives for top entities. Date generation caveats and personalization behavior are covered. Slightly more detail on exact response fields would make it fully complete.

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?

Input-schema descriptions cover 100% of parameters with clear details about date format, default, and context semantics. The PERSONALIZATION paragraph reinforces the context parameter but adds no syntax or constraints beyond the schema, so the description does not need to compensate.

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: 'Get the daily Intelligence Digest' and characterizes it as a cross-signal briefing fusing six signal types into one ranked summary. It also distinguishes itself from siblings by naming daily_radar and follow-up tools like get_entity_profile.

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?

Includes a WHEN TO USE section with concrete example queries and explicit guidance to compare with daily_radar while drilling into specific entities with get_entity_profile or get_insider_activity. This makes the selection criteria clear.

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 substantial behavioral detail beyond the readOnly/idempotent annotations: price and block height are live, other metrics are daily-resolution closes, the chain.as_of timestamp should be cited, and users should never rely on training data for on-chain figures. It also discloses the expected response format and source citation requirements.

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 structured with clear sections and front-loads the core purpose in the first sentence. It is somewhat long, but each section—WHEN TO USE, BEST PRACTICES, RESPONSE FORMAT, PERSONALIZATION—adds operational value that the schema and annotations do not provide.

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 there is no output schema, the description does a strong job of specifying what fields will be returned, data freshness behavior, formatting expectations, and how to handle the Perception Index scoring. It gives an agent enough context to invoke the tool and present results 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?

The input schema already fully documents both parameters, so the baseline is 3. The description adds meaningful guidance on the context parameter through the PERSONALIZATION section, explaining what to pass and why, and the days parameter is implicitly tied to 'Perception Index over recent days.'

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 identifies the tool's function: fetching current Bitcoin market data, on-chain metrics, and the Perception Index. It is specific about the resource and content, but it does not explicitly differentiate itself from the sibling perception_get_index, which may also surface Perception Index data.

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 WHEN TO USE section provides explicit triggering conditions such as 'Any question about current BTC price or market state' and 'What's the market mood right now?'. Best practices also mention complementary tools like get_trends and get_sentiment, but there is no explicit 'when not to use' guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: the Perception Index scale, the expectation to produce visual artifacts, personalization via the context parameter, and the requirement to cite the source.

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 longer than average but well organized with clear sections: summary, index scale, when to use, best practices, response format, personalization, and citation. It front-loads the core purpose and then provides actionable guidance. A few phrases, such as 'let the data and visuals do the talking,' are slightly promotional but not harmful.

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 no output schema, the description fully explains what the tool returns, how to interpret the index, how to present results, and when to pass context. It gives enough detail for an agent to select, invoke, and format the tool's output correctly without needing additional information.

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 value by recommending 7-day and 30-90 day windows, which gives practical guidance for choosing startDate and endDate values. It also reinforces the context parameter's role in personalization, matching and slightly expanding on the schema description.

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: getting daily sentiment metrics over a date range, including positive/neutral/negative counts, total volume, and the Perception Index. It is specific about the resource and the output, and it differentiates itself from siblings by mentioning how it complements get_market and search_articles rather than replacing 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?

The 'WHEN TO USE' section provides concrete example questions and use cases, and 'BEST PRACTICES' gives window recommendations and suggests pairing with get_market and search_articles. It does not explicitly state when not to use this tool, but it clearly implies the proper context and complementary tools.

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=true, idempotentHint=true, and destructiveHint=false, covering side effects. The description adds meaningful behavioral context: trends are grouped from 1,000+ sources, each includes summary/highlights/source references, personalization via the context parameter affects result relevance, and response format guidance tells the agent how to present findings. It doesn't mention pagination or rate limits, but the annotation coverage lowers the burden.

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 moderately long but well-organized with clear headings (WHEN TO USE, BEST PRACTICES, TREND CATEGORIES, PERSONALIZATION, RESPONSE FORMAT), and the primary purpose is front-loaded in the first sentence. There is slight redundancy between the PERSONALIZATION section and the context parameter schema, and 'search_articles' is referenced rather than the exact sibling name, but overall each section 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?

This is a complex, read-only tool with seven optional parameters and no output schema, and the description covers use cases, parameter best practices, output content, categories, personalization, and citation requirements. It does not explicitly explain the relationship between hours and startDate/endDate, though the schema does, and there is no mention of pagination behavior. Given the annotation coverage and schema richness, the remaining gaps are minor.

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%, giving a baseline of 3. The description goes further by giving idiomatic values for hours (24/168/720), explaining when to set include_emerging=true, how min_article_count filters for significance, and how the context parameter should be populated with user portfolio details. This adds practical meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Get AI-extracted narrative trends from Perception's analysis of 1,000+ sources.' It goes on to explain that trends are AI-generated narratives with signal strength, confidence metrics, and business implications, plus trend categories. This clearly distinguishes it from sibling get_* tools such as perception_get_sentiment or perception_get_categories, even without naming 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?

The 'WHEN TO USE' section provides concrete example queries (e.g., 'What are the major stories in crypto this week?'), making the intended use obvious. The description also names a specific alternative for historical research in the hours parameter ('use perception_search_mentions with explicit start_date/end_date') and recommends complementary tools like get_categories, giving explicit routing guidance.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds useful behavioral context beyond annotations: the modes ('discover', 'research', 'agent_workflow', 'workflow') and what each mode returns. There is no contradiction between the description and annotations.

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

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

The description is wellorganized with clear sections: purpose, when to use, modes, and available workflows. Every section contributes to selection and invocation. It is longer than some tool descriptions, but the content is relevant and densely informative rather than verbose.

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 that there is no output schema, the description compensates by stating what is returned and by detailing mode-specific behavior and available workflows. It sufficiently supports correct invocation for a guidance tool, especially with 100% schema coverage and read-only annotations. A slight gap is that it does not describe the exact response structure or interaction pattern, but this is minor for a guide 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 parameters are already documented. The description adds value beyond the schema by explaining what each mode does in practice and listing available workflows, which helps the agent select an appropriate mode. This exceeds the baseline for fully covered 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 opens with a specific verb and resource: 'Get guidance on how to use Perception's intelligence tools effectively.' It clearly distinguishes this meta-tool from the data-gathering siblings by stating it returns tool overviews, role-specific tips, and multi-step research workflows. The purpose is immediately understandable and not a tautology.

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 an explicit 'WHEN TO USE' section with three concrete scenarios, such as new users asking 'what can you do?' and users wanting a structured research workflow. It gives clear context, but it does not explicitly state 'when not to use' or name alternative sibling tools as fallbacks.

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 as read-only and idempotent, and the description adds substantial behavioral context beyond that: it explains that companies with small crypto divisions are filtered to digital-asset roles only, that absence is not evidence because many protocols/DAOs use no ATS, and that median days open is a meaningful signal. These caveats materially shape how an agent interprets results and avoid overclaiming.

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 longer than typical, but every section earns its place: purpose, when to use, why it matters, data caveats, best practices, and attribution. The key message is front-loaded in the first sentence, and headers make the content easy to scan. No filler or repetition is present.

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 no-output-schema tool with four optional parameters, the description is remarkably complete: it explains what the ranking represents, the universe covered, filtering limits, data normalization, caveats about missing companies, how to interpret metrics like median days open, and how to combine this tool with siblings. An agent has enough context to invoke it correctly and interpret results cautiously.

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 schema already provides 100% parameter coverage, so the baseline is 3. The description adds operational meaning beyond the schema, particularly for role_category: it identifies bd_sales as the strongest buying-intent filter and connects policy_regulatory to compliance staffing. It also explains how sector/function filters relate to the ranking's purpose, which helps an agent choose parameters more intelligently.

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 sentence states a specific verb and resource: rank digital-asset companies by open roles across the whole tracked universe, with filtering by sector and function. This clearly distinguishes it from single-company tools like perception_get_entity_profile or perception_get_hiring by emphasizing the cross-company view. The scope is explicit and actionable.

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 WHEN TO USE section provides concrete example queries and conditions, such as 'Who is hiring hardest in custody right now?' and building prospect lists. It also explicitly contrasts this cross-company ranking with per-company views and recommends cross-referencing with get_entity_profile or search_companies, giving clear routing and alternative guidance.

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 readOnly and idempotent, and the description adds meaningful behavioral context: it returns aggregated metrics and individual mentions, requires separate calls per outlet for comparisons, and personalizes analysis via the context parameter. No contradictions with the read-only annotation.

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

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

The description is well-structured with clear sections and the core purpose is front-loaded. It is somewhat verbose and the PERSONALIZATION section mostly repeats the context parameter's schema description, but every section still contributes useful operational guidance.

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

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

For a read-only tool with no output schema, the description explains its return values, use cases, parameter behavior, comparison workflow, and citation requirements. An agent has enough information to decide when to call it and what to expect from the response.

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 reinforces using exact outlet names and mentions context personalization, but the schema already documents these semantics thoroughly. No substantial new parameter insight is added beyond the schema.

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

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

The description opens with a specific verb and resource: 'Get detailed coverage analysis for a specific media outlet.' It clearly lists the returns (mention count, sentiment breakdown, date range, individual mentions with content previews), and the 'WHEN TO USE' examples make it obvious this is the outlet-specific analysis tool versus broader perception tools.

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

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

Provides an explicit 'WHEN TO USE' section with concrete use cases like 'How is Bloomberg covering crypto this week?' and best practices such as comparing outlets and combining with search_articles. It does not explicitly state when not to use this tool, so it lacks the full exclusion guidance needed for 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 already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond that: the comparison methodology (two equal time periods), the output concept ('momentum score with directional indicators'), and the required response format ('create a visual artifact... Keep written analysis concise'). It also mandates source citation. These are behavioral traits an agent needs to know and are not inferable 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?

The description is well-organized into clear sections (description, when to use, response format, personalization, citation) and each section earns its place. It is longer than strictly necessary, but the length is justified by the usage guidance and output expectations. A small amount of redundancy exists between the opening paragraph and the response format section, but it does not detract significantly.

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 read-only analytics tool with no output schema, the description is quite complete: it explains what the tool does, when to use it, how to present results, how to personalize via the context parameter, and the required data source citation. It does not detail the exact structure of the momentum score or handle edge cases like insufficient data, but those are minor gaps given the richness of the rest of the definition.

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 adds value beyond the schema by clarifying the days parameter's behavior with an explicit alternative (perception_search_mentions for historical research) and by explaining how the context parameter should be populated ('pass relevant details in the context parameter'). This exceeds the baseline because the added guidance helps an agent choose and fill parameters correctly.

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 and resource: 'Track whether a narrative or topic is accelerating, steady, or fading.' It then defines the mechanism ('Compares mention volume, sentiment, and source diversity between two equal time periods'), which clearly differentiates it from sibling tools like perception_search_mentions or perception_get_trends. The mention of perception_search_mentions in the days parameter further establishes 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?

A dedicated 'WHEN TO USE' section lists concrete example questions and use cases (trend lifecycle analysis, newsjacking timing). It also explicitly points to an alternative tool in the days parameter: 'For article-level historical research, perception_search_mentions with explicit start_date/end_date covers back to 2011.' This gives the agent both positive and negative usage guidance.

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=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond those annotations by clarifying it returns the user's saved research notes and by instructing the agent to always cite Perception (perception.to) as the data source.

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

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

The description is well-structured: a clear purpose statement, a focused 'WHEN TO USE' block with examples, and a mandatory citation note. It is slightly longer than strictly necessary, but each section earns its place and the main purpose is front-loaded.

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?

This is a simple, safe, two-optional-parameter read-only retrieval tool. The description plus schema covers purpose, when to use, parameters, and data source attribution. Since there is no output schema, a brief note on the return shape would add clarity, but the phrase 'research notes' already gives the agent a solid mental model.

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 input schema already fully documents limit and topic. The description provides example queries that implicitly map to topic ('Show my notes about stablecoins') but does not add substantive semantic detail beyond the schema, earning the baseline 3.

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 and resource: 'Retrieve your saved research notes from previous sessions.' It clearly distinguishes this from sibling tools like perception_save_research and the various get_* retrieval tools by focusing on the user's own saved notes rather than public data.

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?

A dedicated 'WHEN TO USE' section lists concrete scenarios with example queries, such as 'What did I find last time?' and 'Show my notes about stablecoins.' It does not explicitly state when not to use the tool or name alternatives, so it falls 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 already indicate readOnlyHint=false and destructiveHint=false, so the basic write behavior is known. The description adds meaningful context beyond that by noting notes persist across conversations, are stored for the authenticated account or team, and that the source must be cited. It does not explain potential duplicate behavior or return outcomes, but the annotation coverage lowers the burden.

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, then organized into a WHEN TO USE list, persistence note, and retrieval pointer. Every section serves a distinct selection or invocation purpose, and there is no fluff or repetition of schema details.

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

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

The description covers purpose, persistence, and related tools well, but because there is no output schema, it leaves unclear what happens on success (e.g., whether a note ID is returned) and whether repeated saves create duplicates or overwrite. These gaps are minor for a simple write tool but still exist.

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 parameter already has a clear description with examples. The tool description mentions 'key findings, topics, and summary' but adds no extra parameter-level semantics 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?

The description opens with a specific verb and resource: 'Save a research note from your current session.' It clearly states that the tool stores key findings, topics, and summary for future sessions, and it distinguishes itself from the sibling tool by naming perception_recall_research as the retrieval counterpart.

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?

A dedicated 'WHEN TO USE' section provides concrete scenarios with example user utterances, such as saving a briefing at the end of a session or remembering findings after a deep dive. It also explicitly directs the agent to use perception_recall_research for retrieval, making the selection criteria unambiguous.

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, and non-destructive. Beyond that, the description adds significant behavioral context: it promises 'grounded in real data, not speculation', describes the output components (event clusters, sentiment arcs, outlet breakdown, narrative half-liffe), and adds requirements like passing user context via the `context` parameter and always citing Perception (perception.to). It also provides tuning guidance (increase lookback_days for rarer events). No annotation contradiction exists; the description adds substantial behavior beyond the annotations.

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

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

The description is organized into clear labeled sections and front-loaded with a compact definition sentence. It is longer than many tool descriptions, but the length is justified by the tool's richer outputs, usage examples, and best practices. Some repetition exists (first sentence summarizes returns, then WHAT YOU GET repeats in more detail), but it remains highly structured and scannable. No wasted filler; still, a slightly shorter version could achieve the same effect.

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?

There is no output schema, so the description must carry the return-value burden. The WHAT YOU GET section enumerates all major output components (historical event clusters, sentiment arc, outlet breakdown, narrative half-life, pattern summary). It also covers when to use it, how to improve results via lookback_days and context, and the required citation behavior. Given the tool's complexity and missing output schema, this description is complete enough for an agent to invoke it correctly without further documentation.

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 meaningful extra semantics: concrete scenario examples (e.g., 'Tether loses banking partner', 'Bitcoin drops below $50k'), a best practice to increase lookback_days to 365 for rarer event types, and a detailed PERSONALIZATION section explaining how and why to populate the `context` parameter. This goes beyond the schema's basic parameter descriptions, so a 4 is warranted.

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 and resource: 'Analyze a hypothetical scenario by finding historical analogues in Perception's database.' It explicitly states what the tool returns (media coverage, sentiment, outlet attention) and frames it around 'what if' questions, which clearly distinguishes it from sibling retrieval/search tools. The sibling list contains many get_/search_ tools, so this purpose clarity is essential and delivered.

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 'WHEN TO USE' section provides concrete query examples ('What happens if Tether loses its banking partner?', 'What if the SEC rejects the next Bitcoin ETF application?') and a general rule ('Any 'what if' question about digital assets'). Best practices also name alternatives and follow-up actions: 'Follow up with get_entity_profile or search_mentions' to dive deeper. This gives explicit conditions and alternatives, exceeding a basic recommendation.

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. The description adds meaningful behavioral detail: NLP entity extraction, return contents such as sentiment, outlet attribution, content previews, and the full list of trackable companies, plus presentation and citation expectations.

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 long but well organized into targeted sections: WHEN TO USE, BEST PRACTICES, RESPONSE FORMAT, and PERSONALIZATION. Core behavior is front-loaded, and most content earns its place, though some best-practice bullets are slightly redundant.

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 no output schema, the description compensates by listing what the tool returns, how to present results visually, and how to cite and link mentions. It covers use cases, personalization, and response expectations, leaving little ambiguity for an agent to invoke the tool correctly.

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

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 five parameters. The description adds useful practical guidance on exact company names, date-range tracking, and context personalization, but does not substantially redefine parameter semantics beyond the schema.

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

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

The description opens with a specific verb and resource: 'Search for media coverage of a specific company using entity-recognition powered matching.' It also contrasts with keyword search, which helps differentiate the tool, though it does not explicitly name a sibling such as perception_search_mentions.

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?

A dedicated 'WHEN TO USE' section lists concrete user queries and due-diligence scenarios, and 'BEST PRACTICES' recommends pairing with get_sentiment and get_trends. It provides clear contexts but no explicit when-not-to-use guidance or named alternative tools for 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 mark it read-only and idempotent; the description adds valuable behavioral context: query syntax semantics, region vs. region_outlet distinction, aggregation stats returned, and explicit response-format expectations (visual chart, citation, markdown links). This tells the agent what executing the tool will and will not produce beyond the safe-read annotations.

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

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

The description is longer than average but earns its length: it is front-loaded with the core purpose and uses clear headings so an agent can scan to the relevant section. There is no filler or repetition of schema text; each section addresses a distinct decision or behavior.

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 10-parameter read-only search tool with no output schema, this is complete: it covers when to use it, query syntax, all filter classes, output contents, output formatting, and cross-tool guidance. The only gaps (e.g., ignored language when outlet is specified) are already covered by the input schema.

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 high; the description still adds meaning by explaining comma/space query semantics, examples for language codes, the important region vs. region_outlet distinction, and how `context` personalizes results. Not every parameter gets extra prose, but the most semantically subtle ones are enriched.

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: 'Search Perception's database of 1,000+ curated digital asset sources' and names the returned payload (mentions with sentiment, source URLs, aggregation stats). This distinguishes it from sibling search tools like search_companies and search_regulatory by focusing on media mentions and their analytics.

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?

Has an explicit 'WHEN TO USE' section with concrete example queries and use cases, plus 'BEST PRACTICES' that name sibling tools (get_trends, search_companies) and explain when to prefer them. It even gives routing criteria such as using search_companies for entity-specific analysis because it is 'more accurate than keyword search for company names'.

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 carry readOnly/idempotent/non-destructive hints, and the description adds meaningful behavioral detail: full-text PDF indexing, default 30-day lookback (vs 7 days for general mentions), and sentiment-filterable regulatory stance. The PERSONALIZATION note also explains how the context parameter alters output framing. The only unaddressed behavior is result shape/ordering, which is secondary for a read-only search 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 definition is long but tightly organized with clear sections (WHEN TO USE, QUERY TIPS, BEST PRACTICES, PERSONALIZATION) and front-loaded scope. The only redundancy is repeating the agency list that also appears in the schema's jurisdiction parameter, but the regional breakdown adds value for routing the agent quickly.

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

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

For an 8-optional-parameter tool with no output schema, the description covers tool selection, query construction, lookback defaults, filtering strategies, and citation behavior — everything required to invoke it correctly. The small gap is that result fields and ordering are not specified, though references to 'agency and document title' partially mitigate this.

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 value by explaining how parameters relate — agency vs jurisdiction with explicit region-to-agency maps, and strategy-level guidance like 'For enforcement tracking: filter sentiment Negative + specific agency.' This turns raw filters into combinable search tactics beyond what the schema 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?

The description states a specific verb and resource: 'Search regulatory documents, policy papers, enforcement actions, and central bank publications from 36 government agencies worldwide.' It goes beyond a bare label by detailing full-text PDF coverage and the agency universe, which clearly separates it from siblings like perception_get_sentiment or perception_get_trends.

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 dedicated WHEN TO USE section lists concrete example queries ('What has the SEC said about stablecoins recently?'), and BEST PRACTICES names alternatives: 'Combine with get_trends' and 'Cross-reference with search_mentions.' It also draws an explicit comparison to general mentions via the 30-day vs 7-day lookback distinction, giving the agent a precise basis for choosing this tool.

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, so the safety profile is covered. The description adds that results include clean snippets and timestamped occurrences, which is useful, and instructs citing Perception as the data source. However, it does not describe limitations, pagination, or data recency, so it adds only partial behavioral context beyond the annotations.

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

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

The description is front-loaded with the core purpose and then uses a compact WHEN TO USE section with three illustrative examples. The 'Always cite Perception' line is an additional required instruction, not fluff. Overall it is efficient and well-organized, though slightly longer than strictly necessary.

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 search tool with no output schema, the description does explain that results are clean snippets with timestamped occurrences, which is useful. However, it does not clarify result limits, sorting, or how much context is included, and it does not route users away from overlapping sibling tools. The example queries help, but the description is not fully complete for an agent encountering this tool cold.

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 query, ticker, and context. The description provides helpful search-phrase examples, but it does not add meaningful detail about the optional ticker filter or the context parameter beyond what the schema already states. 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 clearly identifies the resource: keyword matches across earnings transcripts, conferences, and digital asset podcasts, so an agent can understand the search scope. It does not explicitly differentiate from sibling search tools like perception_search_mentions, but the specific data-source framing provides enough distinction for most cases.

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 WHEN TO USE section gives concrete example queries that clearly indicate appropriate scenarios, such as searching for what management said about stablecoins or finding podcast mentions of Bitcoin regulation. It does not state when not to use this tool or mention alternatives, but the examples provide clear contextual guidance.

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 readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context by describing the response row contents, the entities vs topics modes, and the data-source attribution requirement. This goes beyond what annotations alone 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?

The description is well-organized under headers—WHEN TO USE, MODES, RESPONSE, PERSONALIZATION—and every section adds practical value. It is somewhat long, and there are minor typos, but the structure makes it easy for an agent to parse and apply.

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

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

For a tool with 9 optional parameters and no output schema, the description covers the core use cases, parameter selection, response fields, modes, and even personalization guidance. An agent has enough context to invoke the tool correctly for typical media-leaderboard queries.

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 practical meaning by mapping example queries to parameter combinations (outlet, mode, limit, categories) and explaining the entities vs topics distinction. This supplements the schema with real usage patterns.

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: 'Returns the top entities or topics ranked by mention count within a date range or outlet.' The 'media-leaderboard view' framing and example queries clearly differentiate it from sibling search/report tools. An agent can understand exactly what this tool computes.

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 an explicit 'WHEN TO USE' section with concrete query-to-parameter mappings, such as outlet for conferences and mode='topics' for theme coverage. It gives clear context for common use cases, though it does not explicitly name sibling tools to exclude or state when not to use this tool.

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