Quantral Stock Sentiment

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond that: results are returned newest first, pagination works via the returned nextCursor, and recaps describe what people said rather than stock predictions or investment advice.

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

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

Four compact sentences front-load the usage trigger, then cover return shape, pagination, and an important interpretation caveat. There is no repetition of schema details or 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?

Given there is no output schema, the description provides the essential return contract: monthly recaps, newest first, containing score, tier, and post count. It also covers pagination and the limitation that recaps are not investment advice, making it sufficient 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 the baseline is 3. The description adds value by explaining the cursor as nextCursor from a previous call that pages further back, and by clarifying that limit maps to months of recap data via the returned post-count mentions.

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 identifies a specific resource—monthly conversation recaps for a company—and its output shape: month's score, tier, and post count. It also distinguishes itself from sibling score/signal tools by emphasizing the time-series, month-by-month nature of the 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 description opens with explicit triggers: use when the user asks what conversation around a company has been about over time, what is happening around a name, or for a month-by-month summary. It does not explicitly contrast with siblings like get_company_score, but the use cases are clear enough to guide selection.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: what a null score means (no mentions, not a low score) and clarifies it is not an investment recommendation, which goes 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 well-structured, front-loading the trigger and output, then adding nuance (null meaning, disclaimer) and usage guidance. Every sentence contributes essential information with no 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?

For a single-parameter read-only tool with no output schema, the description fully specifies return values, tier vocabulary, null semantics, and limitations. An agent has everything needed to call it correctly and interpret results.

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 fully describes the only parameter 'ticker' with an example (AAPL). The description does not add extra parameter details, but none are needed. Baseline 3 is appropriate given 100% 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 clearly states the tool returns the Quantral social-conversation signal score for a company, including specific windows and tier words. It differentiates from siblings by specifying the exact user requests ('Quantral score, signal strength or current conversation level') and notes it is per-company.

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 explicitly says 'Use this when the user asks for...' providing clear trigger conditions. It also advises 'call once per ticker' for multiple companies. It does not mention alternatives or exclusions, but the usage context is well-defined.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial behavior: result cap of 50, newest-first ordering, per-item fields (sentiment, excerpt, source, author track record), Reddit thread nesting with commentCount, the threadOnly edge case, broker-note handling, and an attribution caveat. This is well beyond what structured fields 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?

Long but front-loaded: the usage trigger and return shape come first, followed by the edge cases. Every sentence carries substantive information and none is filler, though the density of thread/broker detail makes it heavier 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?

With no output schema, the description carries the full burden of describing returns and does so thoroughly: item shape, ordering, cap, nesting semantics, and the threadOnly anomaly. It also flags that excerpts are opinions, not advice, which is important for correct downstream use.

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 both parameters are already documented in the schema. The description's note on month (YYYY-MM scoping to one calendar month) largely restates the schema rather than adding new syntax or constraints, so the 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?

States a specific verb and resource (returns the individual posts and filings behind a company's score) and immediately distinguishes it from the sibling get_company_score by framing it as the underlying evidence. An agent can tell this apart from get_top_signals or get_company_recaps without opening a schema.

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

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

"Use this when the user wants the evidence behind a company's score" gives clear triggering context and implicitly routes against get_company_score. It does not explicitly name the alternative sibling or state when not to use it, so it stops short of full when/when-not 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 only cover the safety profile (read-only, idempotent, non-destructive); the description goes well beyond by disclosing the return payload (summary, caveats, current stocks, new-this-update flags, per-stock moves, dropped names, stats) and the hard constraint that live and backtest figures must never be combined. It also frames the resource as a tracked model portfolio, not advice, which materially shapes how the agent presents results.

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

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

Front-loaded with the trigger condition, then the return contents, then the editorial caveat, then the routing sentence. It is somewhat dense and long, but every sentence carries distinct information; no obvious 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?

There is no output schema, so the description carries the burden of describing return values, and it does so item by item (summary, caveats, holdings with new/move flags, dropped names, separated live vs backtest stats). An agent has everything needed to call it and to describe the result accurately.

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

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

Schema description coverage is 100% and the single slug parameter is fully documented there, including examples. The description adds no additional parameter meaning, so the 3 baseline 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 names a specific verb+resource (get one Quantral strategy) and enumerates the four question types it answers: holdings, basis, performance, and latest-change. It explicitly distinguishes itself from the sibling get_strategy_changes, so an agent can route without opening either schema.

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

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

It gives an explicit trigger ('when the user asks about one Quantral strategy') and an explicit alternative with its selection condition ('For someone already following a strategy, get_strategy_changes answers what changed since a date'). The slug's provenance from list_strategies is also implied via the schema.

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 context beyond the read-only annotations: it explains the since-based net difference, the edge case of a name added and dropped in between, how added/dropped names carry performance, pending scoring, and a caution that this is a tracked model portfolio, not a recommendation.

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 usage context and effectively structured. It is somewhat lengthy, but each sentence serves a purpose (usage, since behavior, edge case, return semantics, disclaimer), with minimal waste.

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 no output schema and a read-only, idempotent tool, the description fully covers what the return values contain, the difference calculation, edge cases, and the model-portfolio context. An agent has enough information to call it correctly without ambiguity.

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

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

With 100% schema coverage, the baseline is 3. The description adds meaning beyond the schema: it clarifies that since is when the user last looked or last updated holdings and that the result is a net difference, which enriches the parameter's semantics. It stops short of covering every nuance, but is above baseline.

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

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

The description provides a specific verb and resource: retrieving which stocks were added or dropped from a Quantral strategy's list. It clearly distinguishes itself from sibling get_strategy (current list) and list_strategies by focusing on changes over time.

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 states when to use the tool ('when someone already following a Quantral strategy asks what changed') and explains the two modes (with/without since). However, it does not explicitly name the alternative sibling tool (get_strategy) for retrieving the current list, leaving a small gap in 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 declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds valuable behavioral context: the score range (0-100), the measurement basis (social-conversation across tracked public sources), the caveat that it's not a price prediction or investment recommendation, and the inclusion of a tier word. This goes beyond the annotations without contradicting them.

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 about 120 words, which is somewhat longer than minimal but every sentence earns its place: it covers usage, return content, caveat, default, parameter mapping, and alternative. It is front-loaded with the primary use case and structured logically. Not excessive, but not as tight as a two-sentence example.

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 list tool with only two optional parameters and no output schema, the description provides all necessary information: when to use, what it returns (score and tier), the measurement meaning, the default limit, how to adjust the limit, and the alternative for single companies. An agent can invoke it correctly without needing additional clarification.

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 both parameters are fully described in the schema. The description adds practical guidance beyond the schema: it explains how to map the limit parameter to the user's request (1 for the single top name, 10 for a longer list) and reinforces the default of 5. This enhances the schema's static definitions.

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

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

The description clearly states the tool returns companies ranked by Quantral's social-conversation signal score, and explicitly differentiates from the sibling get_company_score for a single company. The verb 'get' plus resource 'top signals' is specific and the intended use case is defined.

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 opens with explicit when-to-use guidance ('Use this when the user asks...'), then provides a clear exclusion ('For one specific company use get_company_score instead') and even gives limit-matching instructions based on the user's question (1 for top name, 10 for longer list). This is exemplary.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered. The description adds genuinely non-structured behavior: live records and hypothetical backtests are returned as separate records, returns are before trading costs, and outputs must be presented as a record rather than a recommendation. That presentation constraint is exactly the kind of guidance annotations cannot carry.

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

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

Content is front-loaded (trigger first, then return shape, then caveats) and every clause carries information. It is somewhat long for a zero-argument list tool, but there is no filler or repetition.

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 describe the response, and it does: per-strategy update cadence, holdings, live vs backtest records, latest list date, and next update date. Nothing an agent needs to call and interpret this tool 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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly does not invent parameter semantics.

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: this lists the model portfolios Quantral tracks. It also names the sibling it is not (get_strategy) and the difference is explicit, so an agent can route without opening schemas.

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

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

Gives an explicit trigger ('when the user asks what strategies or model portfolios Quantral tracks, or how they have done') and names the alternative with its selecting condition ('Use get_strategy for one strategy's current list'). When-to-use and when-not are both covered.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the description adds complementary behavior: matching by name or ticker prefix, a result limit of 10, and confirmation that no scores are returned. It does not mention auth or rate limits, but those are less critical 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?

Three short sentences, each with a distinct purpose: when to use, what it returns, and what it does not return. The usage condition is front-loaded and every sentence earns its place.

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

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

For a one-parameter, read-only lookup with no output schema, the description covers when to use, matching logic, result limit, and the absence of scores. It does not explicitly list return fields, but the stated purpose ('need the ticker') implies the ticker is included, which is sufficient 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% and the query parameter is already described as 'Company name or ticker prefix.' The tool description repeats this and adds matching behavior, but it does not add new semantic meaning about the parameter itself. 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 states a specific verb and resource: 'matches companies Quantral tracks by name or ticker prefix and returns up to 10.' It clearly distinguishes from siblings by noting it returns no scores and is a precursor to per-company tools, so an agent can readily identify it as a lookup/discovery tool.

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

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

Explicitly says 'Use this when you need the ticker for a company name, or to check whether Quantral covers a company, before calling the per-company tools.' It also redirects: 'It returns no scores; use get_company_score for those.' This gives both a clear when-to-use and a specific alternative.

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