Quantral Stock Sentiment

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

The readOnlyHint annotation already covers the safety profile, and the description adds valuable behavioral context beyond it: results are ordered newest-first and the cursor paginates backward through time. This discloses ordering and pagination semantics that the annotations and schema do not.

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

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

Two sentences, no filler: the first front-loads the core purpose and ordering, the second gives a single actionable pagination tip. Every phrase 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 paged-list tool with an existing readOnlyHint, the description covers purpose, ordering, and pagination. However, since there is no output schema, the description leaves the structure of the returned summaries undefined and only gestures at the response via 'nextCursor'.

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 slightly enriches the cursor parameter by clarifying it comes from a previous call's response, but it adds nothing substantive about ticker or limit beyond what the schema already documents.

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 — month-by-month summaries of what was said about a company — which is clearly distinct from score, signals, and search siblings. It is not ambiguous, but it does not explicitly name or contrast any sibling, so a small differentiation gap remains.

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?

No guidance is given for when to choose this tool over siblings like get_company_signals or get_company_score. The only usage hint is the pagination note ('pass the returned nextCursor to page further back'), which addresses navigation but not tool 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 declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds useful context: scores are aggregated social sentiment, not a price prediction. However, it doesn't disclose what the tier word means, how scores are scaled, or what the response format looks like. With annotations covering the safety profile, a 3 is appropriate.

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

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

Two sentences with zero waste. The core purpose is front-loaded, and the clarifying note about social sentiment vs price prediction is valuable context that prevents misuse. 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 simple read-only tool with one parameter and no output schema, the description is nearly complete. It explains the time windows, the tier word, and the nature of the score. The only minor gap is not explaining what the tier word represents or how the score is scaled, but this is a minor omission for a tool of this simplicity.

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 there is only one parameter (ticker) with a clear example (AAPL). The description doesn't add much beyond the schema, but with a single well-documented parameter, the baseline 3 is correct. The description's mention of 'one company' reinforces that the ticker parameter is singular.

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 ('get'), a clear resource ('signal strength for one company'), and the time windows (24h and 7d). It also distinguishes itself from a price prediction, which helps an agent understand what the tool is not. The sibling tools are different enough that this description clearly identifies this tool's unique purpose.

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

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

The description implies when to use this tool: when you need current signal strength for a single company over 24h/7d windows. It doesn't explicitly name alternatives or exclusions, but the context signals and sibling names (get_company_recaps, get_top_signals) make the usage context reasonably clear. A brief mention of when not to use it would push this to 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?

The annotation readOnlyHint=true covers that this is a safe read operation, so the description doesn't need to restate that. The description adds the cap of 50 and the ordering 'newest first', and the default behavior of 'most recent' when month is omitted, which adds behavioral context beyond the annotation. However, it does not mention potential rate limiting or the shape of the response (e.g., what fields each mention has), which might be needed for a comprehensive understanding. Given the annotation provides the safety profile, a 3 is appropriate.

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 concise, two sentences, with no filler. The key facts (individual mentions, newest first, cap 50, month scoping) are front-loaded in the first sentence, and the second sentence clarifies the default and month usage. Every word 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?

Given the tool has only two parameters with 100% schema coverage, and an output schema is absent, the description provides the necessary usage and behavior: what it returns, the cap, the ordering, and the month scoping. It does not describe the exact response fields or pagination, but since output schema is unspecified and the tool is simple, this is acceptable. The context is complete for an agent to correctly invoke the 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 coverage is 100%: both 'month' and 'ticker' have descriptions that already explain their format and meaning. The description adds the context that 'month' is for scoping to a calendar month, and omitting it gives most recent mentions, but this is partially redundant with the schema's description for 'month'. The ticker parameter is fully covered by the schema. The description adds some value by interpreting the parameters in the context of the tool's purpose, but does not go significantly 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 clearly states that the tool returns 'Individual mentions behind a company's signal strength', using specific verbs and resource. It differentiates from siblings by emphasizing 'mentions' contrasted with 'recaps' or 'score'. The order and cap are also explicit.

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

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

It explains that the tool defaults to the most recent mentions and that a month can be passed to scope to one calendar month, which provides clear context. However, it does not explicitly mention when to use this over a sibling like 'get_company_recaps' or 'get_company_score', nor does it state any exclusions. Still, the usage is clear enough for most 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?

Annotations already declare readOnlyHint=true, and the description usefully adds that the signal is aggregated sentiment rather than a price prediction, describes the 0-100 scale, and clarifies ranking and default length. This is valuable context 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?

Two sentences with no filler. The core behavior, metric meaning, default return size, and parameter tuning guidance are all front-loaded and each 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?

Given the simple read-only nature, two optional parameters, and no output schema, the description covers the essential facts: output concept, ordering, default count, metric scale, and limit guidance. It could mention the window parameter explicitly, but the schema already covers it.

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 limit and window fully. The description's limit guidance reinforces the schema's 'Use 1 when the user asks for the single top name' but adds little new semantic meaning.

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 exactly what the tool does: returns companies ranked by aggregated social chatter signal strength (0-100), explicitly notes it is 'not a price prediction', and mentions the default top-5 return. This clearly differentiates it from the sibling company-specific tools like get_company_signals.

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 practical guidance on how to adjust the limit based on the user's question ('limit 1 when asked for the number one', 'limit 10 for a longer list'). However, it gives no guidance on when to choose this tool over siblings or when not to use it, so selection between tools is only implied.

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 annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds the useful behavioral context that the tool returns a ticker for use in other tools, but it doesn't disclose details like result limits, exact matching behavior, or what happens with ambiguous prefixes. With annotations covering the safety profile, a 3 is appropriate.

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

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

Two sentences with zero waste. The first sentence states the core function, and the second explains the practical purpose. The most important information 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?

For a simple search tool with one parameter, 100% schema coverage, and a readOnly annotation, the description is nearly complete. It explains the return value's purpose (ticker for other tools) but doesn't specify the output format or whether multiple results are possible. Given the tool's simplicity, this 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 schema already documents the query parameter as 'Company name or ticker prefix.' The description repeats this information but doesn't add new meaning beyond what the schema provides. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description states a specific verb ('Find'), a specific resource ('companies Quantral covers'), and the search dimensions ('name or ticker prefix'). It also explains the purpose of the tool: to get the ticker that per-company tools expect, which clearly distinguishes it from sibling tools that operate on a specific 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?

The description explicitly says to use this tool to get the ticker that per-company tools expect, which implies it is the entry point before calling siblings like get_company_recaps or get_company_score. It doesn't explicitly state when not to use it, but the context is clear enough for an agent to select it appropriately.

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