EquiReason

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

Annotations already establish that this is a safe, idempotent, closed-world read, so safety is covered. The description adds a genuine trait beyond them: output is auth-dependent, with verdict, valuation, prices and analyst estimates only appearing when signed in to a plan. It does not discuss rate limits, empty/unknown-ticker behavior, or payload size, so it is not a 5.

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

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

Two sentences, front-loaded with the core resource and no filler or hedging. The return-value enumeration is dense but each item tells the agent what it will receive, which matters given there is no output schema. Slightly list-heavy with no grouping, which keeps it from a 5.

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

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

With one parameter and no output schema, the description must describe the return payload, and it does so exhaustively, including the sign-in-dependent split between free and plan-gated data. What is missing is failure behavior for an invalid ticker and whether the response is large enough to warrant paging.

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 required parameter with 100% schema description coverage ('US ticker, e.g. AAPL'), so the schema already carries the semantics. The description says nothing extra about ticker format, case handling, or what happens for non-US or delisted symbols. 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?

The description names the resource (a single company's filed record) and enumerates the data families it returns: XBRL financials, segment revenue, filings, Form 4 trades, 13F holder counts, risk factors, earnings dates. That content list implicitly separates it from list_filing_events and search_companies. It never states the operation as a verb or explicitly contrasts a sibling, so it stops 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?

There is no statement of when to call this rather than search_companies, list_filing_events, get_trend, or get_fund_holdings, and no preconditions beyond the implied ticker requirement. The only conditional sentence concerns sign-in state affecting the payload, which is behavioral rather than routing guidance. An agent must infer usage from the sibling names alone.

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 the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds useful content scope (what categories of data come back) and 'latest' hints at freshness, but it says nothing about what happens for an untracked or unknown fund, or how stale a 13F can be.

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?

One densely packed sentence with the resource and the three returned data categories front-loaded; no filler, no restatement of the name or title.

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, no-output-schema tool, the description usefully previews the return shape (current positions, deltas, exits), which is exactly what's missing without an output schema. Only the error/freshness behavior for untracked funds is left uncovered.

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 'fund' parameter is documented with an example, so the schema does the work. The description only echoes the constraint via 'a tracked fund's' and adds no format or resolution detail beyond it.

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 resource (a tracked fund's latest 13F) and enumerates the payload: positions with shares and reported value, quarter-over-quarter changes, and exits. That is enough to separate it from list_funds or get_company in practice, though it never explicitly contrasts itself with those 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 qualifier 'a tracked fund's' implicitly signals that the fund must already be tracked (presumably discoverable via list_funds), which is a useful but unstated constraint. There is no explicit when-to-use/when-not guidance and no named alternative for related needs.

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, closed-world and non-destructive. The description adds two genuinely new facts: authentication is required and result depth is plan-dependent. However, "depth follows the plan" is undefined — it does not say whether results are truncated, capped, or paged, which is exactly what an agent needs to interpret an unexpectedly short list.

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 dense sentences with the core result shape front-loaded, then the optional filter and access constraints. It is efficiently sized, though the em-dash clause crams four return fields together and the plan caveat is vague rather than precise.

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 usefully enumerates the returned fields and states the auth requirement, which is the main thing an agent needs before calling. The gaps are the unspecified default limit / result cap and what "depth follows the plan" concretely implies.

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 only 50%: trend is documented in the schema, but limit has no description beyond its 1–50 bounds and no stated default. The description clarifies trend's optional semantics but never mentions limit, so it does not compensate for the undocumented parameter half.

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 resource and operation: companies ranked by EquiReason's verdict, with the return fields enumerated (band, score, matched trend, evidence count). It is clear what the tool returns, though it never explicitly names how it differs from the sibling 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?

"optionally for one trend" plus the schema note that trend is a trend_id from list_trends gives a concrete cross-reference for one path. But there is no guidance on when to prefer this over search_companies, nor any exclusion or prerequisite detail beyond the sign-in note.

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, non-destructive, and closed-world behavior, so the description doesn't need to repeat safety. It adds genuine value by disclosing the shape of the response — industries, lagged knock-on effects, evidence counts by source type, and invalidation conditions — which is the main unknown for this tool given there is no output schema.

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?

One tight sentence that front-loads the core concept ('One trend') and then lists the payload components in a scannable sequence. No filler, no repetition of the title or annotations.

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-entity read with no output schema, the description does the heavy lifting by enumerating return fields. It stops short of covering not-found behavior or whether the trend's name/summary is included, but nothing essential for correct invocation is missing.

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

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

With a single parameter at 100% schema description coverage, the schema already explains trend_id and even points to list_trends as its source. The description adds nothing about the parameter, which is acceptable at this coverage level but earns only the 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 names the resource ('One trend') and enumerates its payload — supported industries, knock-on effects with lag, evidence counts, and end conditions — which clearly separates it from list_trends. It never states the verb explicitly ('retrieve a single trend by id'), relying on the title and the leading 'One trend' to convey that, so it is clear but not fully self-contained.

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?

There is no when-to-use statement, no mention of list_trends as the discovery step, and no exclusion criteria. The only routing hint ('trend_id from list_trends') lives in the schema, not the description, so an agent gets no prose guidance on choosing this over 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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond annotations: the default window is the last 7 days, and 'each row quotes the filing or call' tells the agent the payload carries source excerpts. It doesn't mention pagination or result caps.

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 tightly packed sentences with zero filler; the temporal scope and default window are front-loaded right after the resource, and the event list follows. 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?

With no output schema, the one line about row content carries the return-value burden, and it does so briefly but adequately. Parameters are covered well enough for a single required enum plus an optional week; only pagination/ordering behavior is left 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 50% — only 'week' is documented in the schema — but the description compensates by spelling out the six event kinds that populate the enum and clarifying that 'guidance' means raised or cut. It also restates the week default semantics. Minor remaining gap is that the kind enum values are already fairly self-describing.

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 resource (companies with a given filing event in the last 7 days or an earlier ISO week) and enumerates the event categories, so an agent knows exactly what is returned. It is clearly distinct from siblings like get_company or search_companies, which resolve entities rather than surfaced events.

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

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

The parenthetical '(or an earlier ISO week)' hints at when to supply a week versus taking the default 7-day window, but only names the default implicitly. There is no explicit statement of when to prefer this over search_companies or other siblings, and no exclusions or prerequisites.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new context by disclosing what the response contains — latest 13F period, position count and reported value — which matters because there is no output schema. It does not cover result size or pagination, keeping it short of a 5.

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

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

A single, information-dense sentence with no filler, and the return payload is front-loaded. It is a noun phrase rather than an imperative clause, which slightly weakens the framing of the action but costs nothing in length.

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 tool with no output schema, the description supplies the key missing piece — what fields come back — and annotations carry the safety semantics. Only the absence of usage routing and result-size expectations keeps it from being 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate at the parameter level, and it correctly spends no words on 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?

The description identifies the resource precisely (institutional investors tracked by EquiReason) and the payload fields, which implicitly tells an agent this is a list operation with no arguments. It distinguishes itself reasonably from siblings like get_fund_holdings, which targets one fund's positions rather than the roster of funds.

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?

There is no statement of when to call this versus the siblings (get_fund_holdings, list_filing_events, search_companies) and no mention that the tool takes no filters, so an agent must infer that it returns the entire tracked-fund roster unfiltered.

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, non-destructive and closed-world, so the safety profile is covered. The description adds genuine value by disclosing the shape of the payload (trend plus number of companies' filings describing it), but says nothing about ordering, pagination, or whether the list is exhaustive.

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?

A single dense sentence with no filler, and the resource identity is front-loaded ahead of the return-value detail. Every clause carries information.

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

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

For a no-argument, read-only listing with full annotation coverage and no output schema, the description supplies what is actually needed: what the entries are and what they contain. Remaining gaps (ordering, exhaustiveness) are minor for this complexity level.

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; the schema is trivially complete. Baseline of 4 applies for a zero-parameter tool.

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 resource (market trends EquiReason is following) and states exactly what each entry contains: a company-filing count per trend. It implicitly reads as a listing operation, but it never contrasts with the sibling get_trend, so an agent must infer that this returns the whole set while get_trend fetches one.

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 trends EquiReason is following' suggests a discovery/overview call, but there is no explicit statement of when to use this versus get_trend or the other list_* tools. No prerequisites or exclusions are given, so the agent must reason about routing on its own.

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 and a closed-world dataset, so the description's job is lighter. It adds real value by disclosing the result shape (ticker, name, sector, company page) and the coverage constraint (US-listed, EquiReason-covered companies), which is not in the structured fields.

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

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

Two sentences, zero filler, scope stated before return values. Nothing 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 usefully summarizes return fields, and coverage limits are stated. The only omission is any mention of the limit/result-count behavior, which matters for a search 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 50%: query is documented in the schema, and 'by ticker or name' merely echoes it. The limit parameter (1-25) is never mentioned in the description, so the description does not compensate for the coverage gap.

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 and resource with scope qualifiers: 'Find US-listed companies covered by EquiReason by ticker or name.' It also names the returned fields, so the agent knows what it gets. Naming the sibling get_company and contrasting single-fetch vs. search would earn 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?

The 'by ticker or name' phrasing implies the lookup case, but there is no explicit statement of when to use this versus get_company (e.g., search first, then fetch details). Usage is inferable but not guided.

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