Returnolio

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

readOnlyHint is already declared in annotations, and the trailing 'Read-only' merely repeats it. The description does add one genuinely useful disclosure beyond the annotations: the response includes an app link to the full comparison, which matters because there is no output schema. Otherwise it omits pagination, any per-ticker failure behavior, or limits beyond the count.

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 short sentences with the scope and count limit front-loaded. The closing 'Read-only' is redundant against the readOnlyHint annotation and could be dropped, but overall it is tight with no 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 single-parameter, fully documented read tool with no output schema, the description covers purpose, scope, and return content (an app link). It stops short of explaining error behavior for invalid tickers or whether unsupported symbols are dropped, which would complete the picture.

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 'tickers' parameter is fully documented in the schema, so baseline 3 applies. The description restates the 'up to 5 tickers' cap but adds no format guidance (e.g., exchange suffixes, casing) beyond what the schema already provides.

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

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

States a specific verb (compare) and resource (Returnolio scores and pillar breakdowns) with an explicit scope of up to 5 tickers side by side. This cleanly distinguishes it from single-ticker siblings like get_stock_score, 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?

The 'up to 5 tickers side by side' phrasing implies the multi-ticker comparison use case and contrasts implicitly with single-score tools, but it never names an alternative or states when to prefer this over get_stock_score or screen_stocks. Usage is inferable rather than stated.

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

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

Annotations declare readOnlyHint=true, and the description is consistent ('this read-only connector cannot perform'), adding real value beyond the annotation: the regulatory rationale, the browser fallback note, and the fact that the response is a precise link. It stops short of describing exact return format, though that is minor for a link 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?

Front-loaded with the core behavior and the when-to-use condition; the single long sentence carries some redundancy between the parenthetical list and the following clause, but every element is relevant and nothing is wasted.

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, no-output-schema tool whose only job is to emit a link, the description covers purpose, trigger conditions, and the link's usage note. Return-format detail is unnecessary here, so the definition is essentially 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?

Schema coverage is 100% and the schema already gives examples for 'action', so baseline is 3; the description goes further by enumerating the action categories (trades, holdings, watchlists, alert subscriptions, advice) that map onto that single parameter, genuinely enriching its 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 ('return the exact Returnolio app link') and immediately scopes it to actions the read-only connector cannot perform, which cleanly distinguishes it from all data-retrieval siblings like get_top10, my_portfolio, and compare_stocks.

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 when to use it ('whenever the user wants to DO something the connector cannot do') and enumerates the triggering categories (trades, holdings/watchlist changes, alert subscriptions, personalized advice), so the agent can route without inference.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely new behavioral facts — results are a capped teaser subset, not the complete dataset, and the response includes an app link to the full calendar. It stops short of quantifying the cap or describing ordering/pagination.

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, front-loaded sentences with the resource and scope first and the limitation second. The trailing 'Read-only.' repeats the readOnlyHint annotation and does not strictly earn its place, but the rest is tight.

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 return-value burden and does so partially: it says the response is a capped teaser plus an app link. For a zero-required-param read tool this is largely sufficient, though cap size and ordering are unstated.

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 single enum parameter already documents all four values and its default ('defaults to earnings'). The description restates the same event types without adding format, combination, or filtering 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?

States a specific verb and resource ('Get upcoming market events') and enumerates the four event types covered, plus the scope restriction to the Returnolio-covered universe. No sibling tool (screening, portfolio, scoring) overlaps a calendar endpoint, so an agent can route here unambiguously.

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

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

The description gives a clear when-to-use context ('teaser list, capped') and implicitly a when-not-to-use alternative: the full filterable calendar with history lives in the app, and the response carries a link to it. It does not name any sibling tool as an alternative, so it stops short of full explicit routing.

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

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

Annotations already declare readOnlyHint=true, and the description redundantly restates 'Read-only', which earns no credit. It does add genuine context beyond the annotations: it discloses exactly what the response contains, that it is a compact summary, and that an app link to the full market view is included.

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, front-loaded with the core purpose before the scope exclusions and the app-link note. The trailing 'Read-only' is wasted words against the readOnlyHint annotation, but overall there is little fat.

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 zero-parameter read-only tool with no output schema, the description covers what is returned, what is excluded, and that a link to fuller data accompanies the response. An agent has enough to call it correctly, though the absence of an output schema means the exact fields remain unspecified.

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

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

There are zero parameters, so per the rubric the baseline is 4. Nothing in the description needs 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?

States a specific verb (Get) and resource (market-state summary) and enumerates the contents: headline index cards plus macro snapshot covering rates, inflation and jobs. Sibling differentiation is only implicit (the exclusion of yields/forex/crypto/commodities separates it from data-heavy siblings), so it falls short of a 5.

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

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

Usage is implied rather than stated: the sentence 'Yields, forex, crypto, commodities and analyst forecasts are in the app' tells the agent those are not returned here, which lightly bounds scope. There is no explicit when-to-use or when-to-prefer-an-alternative guidance among the many siblings.

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

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

The 'Read-only' claim merely restates the readOnlyHint annotation and earns no credit. The one genuinely additive detail is that the response includes an app link to the full list, which matters because no output schema exists; beyond that there is no disclosure of freshness, scope, or empty-result behavior.

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 short sentences with the resource identified first and the return hint last. The trailing 'Read-only' sentence is redundant against the annotation and is the only wasted clause.

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 zero-parameter, no-output-schema tool this is nearly sufficient: it identifies the dataset and notes the app-link payload. An agent could benefit from knowing freshness/cadence and whether the list is ranked, but nothing critical to invocation is missing.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; per the scoring baseline this is a 4. Schema coverage is 100% and the empty object schema is self-explanatory.

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?

Names a specific resource (Returnolio's Moonshot candidates) and characterizes it concretely as 'high-growth breakout names surfaced by the detector', so the agent knows this is a curated detector output. It stops short of distinguishing itself from conceptually similar list tools in the sibling set (get_top10, screen_stocks, get_top10_track_record), which is why it lands at 4 rather than 5.

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

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

Usage context is implied by 'breakout names surfaced by the detector', suggesting a screening/discovery use case, but there is no explicit when-to-use statement, no prerequisites, and no routing to or away from alternatives like screen_stocks or get_top10.

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 declare readOnlyHint, so the description usefully adds that the pillar-weighting methodology is deliberately unpublished and that the response carries an app link to full analysis. The trailing 'Read-only' merely restates the annotation, but the two pieces of added context about what is and is not disclosed exceed the annotation baseline.

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, front-loaded with the resource and the payload, with the pillar list doing real work. The final 'Read-only' is redundant against the readOnlyHint annotation, a small but avoidable bit of 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 the return, and it does: the five pillars, their underlying values, the opaque headline aggregation, and an app link. Nothing essential about invoking it correctly is missing, though error/edge cases (unknown ticker) go unmentioned.

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?

Only one parameter exists and schema description coverage is 100%, so the schema fully documents the ticker format. The description adds no syntax or format detail beyond 'one stock', making this the baseline case where structured data 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?

States a specific verb and resource ('Get Returnolio's score for one stock') and enumerates exactly what is returned: five named pillars plus the underlying values. The phrase 'for one stock' implicitly distinguishes it from multi-stock siblings like compare_stocks and screen_stocks, but no sibling is named explicitly, so it falls short of a 5.

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

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

Usage is only implied: the scope 'for one stock' suggests it when a single-ticker score is wanted rather than a comparison or screen, but the description never says when to prefer this over compare_stocks or screen_stocks, nor mentions any prerequisites or failure conditions.

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, so the closing 'Read-only' sentence is largely redundant. However, with no output schema the description earns credit for disclosing what the response contains: a one-line thesis per pick and an app link to the fuller rationale, which tells the agent how much depth to expect.

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, front-loaded with what the tool returns. The final 'Read-only' sentence repeats the readOnlyHint annotation and is the only wasted text; everything else 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 zero-parameter, read-only tool with no output schema, the description adequately covers what is returned and flags freshness ('current monthly'). The main omission is routing guidance against the nearby get_top10_track_record sibling, but nothing needed to invoke the tool correctly is missing.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No schema-level semantics are needed or missing.

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 Returnolio's current monthly Top 10 list') plus the payload shape ('one-line thesis per pick'), so an agent knows exactly what comes back. It does not explicitly distinguish itself from the sibling get_top10_track_record, though 'current' versus an implied historical track record does provide soft differentiation.

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?

Usage is only implied: the agent can infer this is the tool for fetching the live monthly picks, but there is no explicit when-to-use statement, no exclusion, and no pointer to get_top10_track_record or get_app_link as alternatives. With zero parameters there is little to misuse, which keeps this at minimum-viable rather than low.

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, so safety is covered. The description adds substantive context beyond that: weekly sampling cadence ('at most one point a week'), rebasing to 100, and crucially that only editions the user's plan can open are returned, hinting at subscription gating. It restates 'Read-only' but the extra cadence and plan-gating detail earns the score.

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

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

The core purpose is front-loaded in the first sentence and the return contents are enumerated compactly. The trailing disclaimer and app-link sentence are slightly boilerplate but still informative, so only minor 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?

With no output schema, the description carries the full burden and does so thoroughly: it names the benchmark, the series construction (rebased, weekly), the trailing returns, the per-edition fields (month, rank, ticker, company, sector), and the embedded app link and rationale. An agent knows exactly what it will receive.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter syntax for the description to clarify or omit. No further value can be added here.

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 live track record of Returnolio's Top 10 portfolio against the S&P 500 since inception') and enumerates exactly what is returned (rebased lines, trailing returns, past editions). An agent can distinguish this from the bare get_top10 list tool 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?

The informational framing ('Information only, not a recommendation') implies this is a performance/history lookup, but it never states when to prefer this over the sibling get_top10 or get_market_overview. No explicit alternatives or exclusions are offered, so routing is left to inference.

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

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

readOnlyHint=true already establishes the safety profile, so the description's job is supplemental — and it adds real value: the output is mechanical numbers, cost basis is split-adjusted, no advisory interpretation is intended, and the response carries an app link. It does not cover auth/scope requirements or empty-portfolio behavior.

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

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

Three sentences, front-loaded with what is returned, then the guardrail, then the hand-off note. The 'NOT analysis, a rating, or investment advice' clause is slightly redundant but serves a real agent-behavior purpose; otherwise no 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?

With no output schema, the description carries the return-value burden and does so adequately by naming holdings, cost basis, totals, unrealized P/L, and the app link. It omits edge cases such as an empty or unavailable portfolio, which would fully round it out.

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

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

The tool takes zero parameters, so the baseline is 4 by rule; there is no parameter surface for the description to explain or fail to explain.

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 signed-in user's own Returnolio portfolio') and enumerates the aggregation content (holdings with weighted-average, split-adjusted cost basis, totals, unrealized P/L). This clearly separates it from siblings like compare_stocks, screen_stocks, or my_watchlist.

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

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

Explicitly frames the tool as a 'numbers-only readout, NOT analysis, a rating, or investment advice,' which rules out use cases an agent might otherwise route here (e.g., score/rating requests belong to get_stock_score). It also notes holdings edits happen in the app, but it does not name a sibling tool as the alternative for any specific need.

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?

readOnlyHint=true already declares the safety profile, but the description adds real context beyond it: the output is a 'mechanical readout, not advice' (important framing that prevents the agent from presenting it as a recommendation) and it discloses that the response includes an app link. It stops short of describing the response shape or whether results are ranked/limited.

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 with the core purpose front-loaded and no filler. Each sentence adds a distinct fact: what it returns, that it is read-only/non-advisory, and where mutation happens.

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 and no parameters, the description carries the burden and does: it names the returned content (score, price, app link) and discloses the read-only constraint and mutation route. Nothing needed to call this tool correctly is missing.

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

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

The tool takes zero parameters (empty object schema), so there is nothing for the description to disambiguate; the baseline for a no-param tool applies. It correctly spends no words on nonexistent inputs.

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 (Get) and resource (the signed-in user's own watchlist / followed tickers), and names the returned fields (score and price). The 'signed-in user's own' scoping plus 'followed tickers' distinguishes it clearly from my_portfolio, which covers holdings rather than a followed 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?

Explicitly rules out the mutation path an agent might otherwise attempt: 'To add or remove tickers, the user does it in the app.' That is a clear when-not statement. It does not name a sibling alternative (e.g. my_portfolio) for related reads, which keeps it from 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 declare readOnlyHint=true, and the description's 'Read-only' matches rather than contradicts. Beyond that it discloses real behavioral traits the annotations do not: a hard cap of 15 results, the teaser limitation, and that the response embeds an app link to the full screener.

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

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

Three tight sentences, front-loaded with the primary action and result cap before the limitation and the read-only note. The trailing 'Read-only' duplicates the annotation but costs little.

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 return-value burden and does so adequately by stating the count cap and the app link. What is missing is any note on ordering or scoring semantics of the returned names, but nothing essential to invoking it correctly is absent.

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

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

Schema description coverage is 100%, so both parameters (sector partial match, min_score 0-100) are already documented in the schema. The description adds no filtering syntax or default behavior beyond that, 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?

Specific verb+resource ('Screen the Returnolio universe', return up to 15 top-scored names) that tells the agent exactly what comes back and how it is bounded. It does not explicitly distinguish itself from the closest sibling get_top10, which also returns a ranked list, leaving a small overlap 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?

Clear when-to-use framing: it is a 'teaser, not a bulk export' and the full filtered screener lives in the app, which tells the agent to stop here when bulk export is needed. It offers no explicit guidance against sibling tools such as get_top10 or compare_stocks, so the routing is only implicit.

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

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

Annotations already declare readOnlyHint=true, so 'Read-only' is largely redundant. The description does add genuine behavior beyond annotations: a hard cap of 10 results and the fact that the response contains an app link into the stock universe where each company opens its full analysis. It stops short of covering rate limits, empty-result behavior, or ranking of matches.

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, front-loaded with the core action, followed by the result shape and the safety note. Nothing is padded and each sentence carries distinct 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 partially compensates by describing the return (app link, up to 10 results). For a one-parameter read-only lookup that is nearly sufficient, though match ordering and no-result handling remain unstated.

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

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

There is a single parameter with 100% schema description coverage, so the schema already explains 'q' as a company name or ticker fragment. The description restates the same semantics ('by company name or partial symbol') without adding case-sensitivity, partial-match behavior, or whether spaces are acceptable. Baseline 3 applies 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?

States a specific verb and resource ('Find tickers') plus the input modality ('by company name or partial symbol') and a result cap ('up to 10 results'). An agent can distinguish this from siblings like screen_stocks or get_stock_score without opening the schema, since those are filtering/scoring tools rather than lookup 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?

Usage is implied: use it when you have a name or symbol fragment and need a ticker. But there is no explicit when-to-use versus when-not, no mention of alternatives such as screen_stocks for broader filtering, and no note on what to do if no match is found. 'Read-only' is the only directive signal.

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