InsiderAlpha

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses a critical behavioral fact: 8-K classification was retired on 2026-08-27, so nine named fields are NULL or False for recent filings and hold historical values only for older ones. It also tells the agent not to present or infer those values and to steer users to filing_url, which materially changes how results must be handled.

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 mode behavior is front-loaded in the first sentence, and the deprecated-field caveat is placed where an agent will read it before formatting output. The multi-line field enumeration and the doubled 'do not present... do not infer' instruction are slightly verbose but justified by the risk of misreporting stale classifications.

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 explain what the two modes return, plus a strong caveat about the meaning of returned fields. It omits pagination/limit behavior and any note on how many filings the feed returns, which an agent calling this repeatedly would want.

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% and the description does meaningful work for ticker, explaining not just that it filters but that it changes the return set to filings matched against preceding insider purchases. The limit parameter is unexplained in both the schema and the description, leaving one 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?

The description names a specific verb and resource (recent SEC Form 8-K filings correlated with insider buying) and defines two distinct modes based on whether a ticker is supplied. It stops short of naming the sibling tools an agent might confuse it with (search_filings, get_filing), so it is clear but not sibling-differentiating.

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 clearly states the two usage contexts: pass a ticker to get that company's 8-Ks matched against preceding insider purchases, omit it for the general recent-8-K feed. No explicit when-not-to-use or named alternatives are given, so the guidance is strong but not exhaustive.

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 openWorldHint=true, so the safety and openness profile is covered. The description adds meaningful context by naming the return payload (OHLCV candles) and flagging that data is live rather than historical, but it says nothing about market-hours behavior, staleness/refresh, or invalid-ticker handling.

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 core purpose front-loaded and zero filler. Every clause (OHLCV, ticker, range, live data) 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 low-complexity, two-parameter read tool with no output schema, the description is nearly sufficient: it names the metric set (OHLCV) and scope (ticker, range). It stops short of describing candle granularity or interval, which the agent cannot infer from the schema.

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

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

Schema description coverage is 50%: ticker is documented in the schema, and range is self-documenting via its enum. The phrase 'over a range' loosely ties the parameter to intent but adds no format, semantics, or default detail beyond what the schema already provides, 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 (Get) and resource (OHLCV price-chart candles) scoped to a ticker and range, which cleanly separates it from siblings like get_company_profile or get_daily_trading_plan. An agent can identify the tool's output shape without opening the 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?

There is no when-to-use or when-not-to-use guidance and no named alternative among the many sibling tools. The parenthetical '(Live market data.)' hints at freshness but does not tell the agent when this is the right tool versus, say, get_daily_trading_plan or get_market_overview.

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 openWorldHint=true, so safety and data-scope are covered without the description's help. The description adds the payload contents, which is genuinely useful since there is no output schema, but says nothing about rate limits, data currency, or what happens for an unknown ticker.

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 compact sentence with the resource front-loaded and the fields listed colon-style. Nothing is wasted, though the field list is crammed in without punctuation structure that would help scanning.

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 tool with no output schema, the enumerated field list compensates reasonably well for the missing return documentation. Gaps remain around error behavior and ticker validity, but the core call path is unambiguous.

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% with a single well-documented parameter ('Stock ticker, e.g. AAPL'), so the baseline of 3 applies. The description adds no further meaning about ticker format, exchange prefixes, or case sensitivity beyond what the schema already states.

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

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

States a specific verb and resource ('Get a company's profile') and enumerates the returned fields (sector, industry, market cap, description, website). It is clearly distinguishable from the search-oriented siblings by its single-entity, ticker-keyed nature, though it never explicitly contrasts itself with search_companies or get_insider_profile.

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

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

There is no when-to-use framing, no prerequisite (e.g. 'requires a valid public ticker'), and no named alternative such as search_companies for discovering a ticker first. The agent must infer the routing from the tool name 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 cover read-only and open-world behavior, and the description adds real context beyond them: values are filed ranges and never exact amounts, data derives from Periodic Transaction Reports, and it requires the Congress trades tracker entitlement on the account. It doesn't mention rate limits, pagination defaults, 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?

Purpose is front-loaded in the first sentence, and the caveats (filed ranges, no Senate, entitlement requirement) are appended as compact clauses. It is slightly long but nearly every 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?

For a tool with no output schema, the description usefully characterizes the returned data fields and the ranges-only nature of values, plus the access prerequisite. Remaining gaps are pagination/limit behavior and result-volume expectations, which are minor.

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

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

With 60% schema coverage, the schema already documents the member slug format, ticker example, and days semantics. The description reinforces ticker/member/transaction-type filtering and the trailing-window notion but adds little syntax detail and says nothing about the limit parameter.

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 — trades disclosed by U.S. House members under the STOCK Act — and enumerates the returned facts (who, which security, when, value range). It is clearly distinguishable from siblings like search_insiders, get_insider_profile and get_unfiltered_purchases.

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 concrete scoping guidance: filter by ticker/member/transaction type over a trailing window, and explicitly excludes Senate reports, which prevents a common mis-selection. It does not, however, name an alternative sibling for the Senate case or say when to prefer this over insider-category tools.

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

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

Annotations declare readOnlyHint and openWorldHint, so the safety profile is covered. The description goes further with 'Compute-heavy; cached per day,' which tells the agent about latency and that results are stable within a day — non-obvious context that isn't in 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?

Three tight sentences, front-loaded with the core purpose, then mode semantics, then the caching caveat. No filler.

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

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

With no output schema, the description must convey return shape, and it does name the key fields (insider signals with entry/exit levels, ranked ideas). Minor gaps remain around pagination/limit interaction and how as_of_date affects the 'pre-computed' cache.

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 33%, so the description has to carry weight; it explains what the 'side' enum values actually return, which is meaningful beyond the bare enum. But 'limit' and 'as_of_date' get no elaboration beyond the schema's own short date hint, leaving part of the gap unfilled.

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 InsiderAlpha's pre-computed daily trading plan') and clarifies the payload ('alpha-scored insider signals with entry/exit levels'). It differentiates content from generic siblings like get_market_overview, though it never names a sibling it should be chosen over.

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 side='buy'/'sell' split implies what each mode returns, which helps an agent pick a mode. However, there is no explicit when-to-use guidance relative to siblings like get_unfiltered_purchases or get_congress_trades, so the routing decision 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful content context (the response includes all transactions and footnotes), but says nothing about error behavior, missing/unauthorized filings, or payload size — modest added value against an already-covered safety profile.

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 sentence, front-loaded with the verb and resource, with no redundant or filler text. Every clause (single filing, full detail, contents) 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 description carries the burden of describing the return and does so at a high level (transactions and footnotes), and annotations cover read-only safety. It is nearly complete for a trivial one-parameter read, though the shape of the returned payload is only sketched.

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 at 100% schema description coverage, so the baseline is 3. The description only implies that the id refers to a filing ('one SEC filing') and adds no format, origin, or validity detail 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?

States a specific verb and resource — fetch the full detail of a single SEC filing — and disambiguates from the search-style siblings by emphasizing 'one SEC filing'. It also previews the payload contents (transactions, footnotes). It stops short of naming an alternative like search_filings, so it is clear but not fully sibling-differentiated.

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: 'one SEC filing' suggests the detail-fetch step after a search, but no explicit when-to-use versus search_filings is given, and there are no exclusions or prerequisites. An agent can infer the intent but is not told when this is the wrong choice.

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 openWorldHint=true, so safety is covered. The description adds genuine context by disclosing the returned content categories and flagging that net worth is an estimate and performance is a score, which tells the agent the data is derived rather than raw. It stops short of saying anything about freshness, provenance, or cost.

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 front-loaded sentence with zero filler; the resource and its contents are stated first and nothing is repeated from the title or schema.

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 must describe the return payload, and it does so by listing the four content categories. For a one-parameter read-only lookup with annotations, that is close to sufficient; only the link back to search_insiders 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?

Only one parameter and schema description coverage is 100%, so the schema already carries the full burden; the schema text itself ('Insider id') is tautological and the description adds nothing about id origin or where to obtain it. Baseline 3 applies when structured fields do all the work.

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 (insider's enriched profile) and enumerates the payload: biography, roles, net worth estimate, trading-performance scoring. That is markedly more informative than a bare 'get profile'. It never distinguishes itself from the sibling search_insiders, which is the main gap keeping it below 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 required insider_id signals a detail lookup that follows an insider search, but the description never says when to reach for this instead of search_insiders or any other sibling. No prerequisites, no exclusions, no alternatives named.

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 openWorldHint=true, so the read-only, external-data nature is covered by structured fields. The description adds the source of truth (SEC filings S-1/EFFECT/424B), which is useful context, but says nothing about data freshness/lag, rate limits, or pagination behavior for a time-sensitive calendar.

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 sentence that front-loads the verb and resource, then qualifies the two windows. Each clause carries information the agent needs; there is no filler.

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

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

For a two-parameter read-only list tool with no output schema, the description covers the purpose and window semantics but omits the result shape (fields returned, pagination) and the limit parameter's meaning. It is adequate but leaves real gaps an agent would have to discover by calling.

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 0%, so the description must carry the parameter burden. It partially compensates by defining the 'window' enum values in substantive terms, but the 'limit' parameter (default 20, max 50) is never explained, and the description does not state which window is the default.

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 gives a specific verb ('Get'), a precise resource ('SEC IPO calendar'), and even the underlying filing form types (S-1 / EFFECT / 424B), so the agent knows exactly what data comes back. It does not explicitly differentiate itself from the nearest sibling, get_market_calendar, leaving that distinction to inference.

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 two operating modes are defined inline: 'upcoming (filed/effective, not yet priced)' vs 'recent (already priced)', which tells the agent which window to pick for a given question. There is no explicit when-not-to-use guidance and no pointer to an alternative tool 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 readOnlyHint=true and openWorldHint=true, so the safety and open-world profile is covered. The description adds the useful detail that results include holidays and early-close days, but says nothing about auth needs, rate limits, or how a partial/empty range behaves.

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 efficient sentence with the core purpose and returned content front-loaded and no wasted words.

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 calendar lookup with fully documented optional parameters and annotations covering the safety profile, the description is nearly sufficient. An output schema is absent but the description tells the agent what data comes back, leaving only minor gaps.

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 schema already documents the YYYY-MM-DD format and the 30-day-ago/60-day-forward defaults. The description only adds the phrase 'in a date range', contributing no syntax or formatting detail beyond the schema, 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 (get) and resource (market calendar) and enumerates the returned content (market holidays and early-close days), which separates it from the other calendars like get_ipo_calendar. It does not explicitly name a sibling, so it falls just short of 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 description gives no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_ipo_calendar. Usage is only implied by the phrase 'in a date range', which is inferred 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 already declare readOnlyHint=true and openWorldHint=true, so safety and open-world nature are covered. The description adds useful context that data is live and served from a shared cache (freshness/staleness behavior), but says nothing about refresh cadence, latency, or failure modes.

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 zero waste; the payload contents are front-loaded and the caching caveat is parenthetical. Every clause 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-argument read tool with no output schema, the description sufficiently covers what comes back (indices, VIX, breadth, trend) and the freshness model. A little more on scope/limitations would make it fully self-contained, but nothing essential 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 burden; the baseline of 4 applies and nothing in the description misrepresents the argument surface.

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 regime') and enumerates the contents returned (major indices, VIX, breadth, trend), so an agent knows what it gets. It does not explicitly differentiate itself from siblings like get_daily_trading_plan or get_market_calendar, but the scope is narrow enough to be inferred.

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: an agent can infer it should call this for a snapshot of overall market conditions, but there is no explicit when-to-use statement, no exclusions, and no mention of alternatives such as get_daily_trading_plan.

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 and open-world behavior, but the description adds two things they cannot: the required 'mcp:portfolio' scope (an auth prerequisite the agent must know) and the freshness guarantee 'Real financial data - never cached'. It does not disclose pagination or result shape, which is a minor remaining gap.

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 fragments: purpose first, then the scope prerequisite, then the view taxonomy and the freshness note. Nothing is repeated from the schema or annotations and there is no filler.

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

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

For a read-only, 2-parameter tool with no output schema, the definition covers auth scope, all view semantics, and data freshness, which is enough to invoke it correctly. The undocumented `limit` (default 50, max 50) is the one omission.

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 0%, so the description carries the burden and does explain every `view` enum member with a concrete meaning, adding real value over the bare enum list. The `limit` parameter is never mentioned, so it only partially compensates 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?

States a specific verb+resource ('Get the authenticated user's own portfolio') and immediately distinguishes it from every sibling, which all deal with third-party companies, insiders, filings, or market data rather than the caller's own account. No ambiguity about what is returned.

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 maps each `view` value to a concrete use case (account totals, current positions, daily P&L, trade journal), which tells the agent which invocation fits which intent. It stops short of naming when NOT to use it or pointing at an alternative tool, but no sibling overlaps this resource.

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 openWorldHint=true, covering the safety profile. The description adds meaningful behavioral context beyond that: no quality scoring, no value filtering, no result limit, and results grouped by ticker — all of which affect how an agent should handle the output. It stops short of describing volume/pagination implications of an unlimited result set.

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 padding. The key differentiator (raw, unfiltered, unlimited) is front-loaded, and the sibling routing follows immediately.

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-optional-param read tool with no output schema, the description conveys enough: what is returned (raw purchases grouped by ticker), what is omitted (scoring, filtering, limits), and the alternative. Minor gap is any indication of result volume given the explicit absence of a limit.

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 as_of_date parameter is fully documented with format (YYYY-MM-DD) and default behavior. The description adds no parameter-level detail, so the schema carries the load; baseline 3 is appropriate.

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

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

States a specific verb and resource ('Get ALL raw insider purchases'), adds scope ('for a trading day grouped by ticker'), and explicitly disclaims the filtering/scoring/limit behavior. It names the sibling get_daily_trading_plan as the contrasting option, so an agent can distinguish the two 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?

Explicitly routes the agent: use this for the raw, unfiltered view '(for manual strategies)', and use get_daily_trading_plan 'for the curated/scored view'. Both the when-to-use and the alternative are 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 already declare readOnlyHint=true and openWorldHint=true, so the read-only, external-data nature is covered. The description adds only the data scope ('tracked by InsiderAlpha') and says nothing about result ordering, pagination, rate limits, or how partial matches behave.

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 front-loaded sentence with no filler, but it is arguably under-specified for a tool with a pagination parameter rather than merely concise.

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 search with annotations covering the safety profile and no output schema, the description covers purpose adequately. It leaves the 'limit' parameter unexplained and gives no sense of result shape or breadth of matching, which is the main remaining 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 50%: 'query' is documented in the schema as 'Company name or ticker fragment', which the description merely restates, while 'limit' (default 20, max 50) is undocumented in both places. The description does not compensate for that gap or explain matching 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 ('Search companies') plus the data domain ('tracked by InsiderAlpha') and the match keys ('by name or ticker'). It is clearly distinguishable from siblings like search_filings and search_insiders, though it never names an alternative explicitly.

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 guidance, no prerequisites, and no exclusions or alternatives. The only hint is the implicit framing of a name/ticker lookup, which an agent could infer from the name 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 declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds non-obvious behavioral context: results are deduplicated and limited to primary filings, and it names the returned fields (company, insider, role, transaction detail). It does not disclose pagination or default-window behavior, keeping it from 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?

Three short sentences, front-loaded with the core verb and resource, followed by return contents and usage examples. Nothing is redundant, though the parenthetical about deduplication slightly interrupts the opening 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?

With no output schema, the description correctly describes what comes back (company, insider, role, transaction detail), and covers filtering intent for a 6-parameter read tool. It omits pagination/window defaults and the 90-day cap, which an agent would have to infer from the schema.

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

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

Schema coverage is 67% and the description mentions no parameter at all; days/ticker/min_value/transaction_type are documented in the schema, while limit and offset are undocumented in both places. The description neither compensates for the gap nor adds syntax guidance, so the baseline 3 fits.

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 (Search) and resource (recent SEC Form 4 insider-trading filings) with a scoping qualifier (deduplicated, primary only). It is clear what the tool returns, but it does not name any sibling tool, so it falls short of full sibling 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?

Provides concrete usage contexts ('which insiders bought/sold <ticker>', 'recent large insider purchases'), which tells the agent when to reach for it. It gives no exclusions or pointers to alternatives such as get_unfiltered_purchases, so it stops short of a 5.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds a little value by hinting at enrichment fields ('notability and aggregate activity'), but says nothing about pagination, result ordering, or empty-match behavior for what is an open-world search.

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 front-loaded sentence with no wasted words, leading with the action and scope. It is efficient, though the trailing enrichment clause is somewhat vague and could have carried routing information instead.

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 three optional parameters, no required inputs, and no output schema, the description does enough to convey the basic contract and hints at returned fields. It falls short on usage routing and on clarifying how the loose 'by name or company' phrasing maps to the concrete query/ticker parameters.

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 67%: the query and ticker parameters are documented in the schema, while limit is not. The description loosely maps to query/ticker via 'by name or company' but adds no format guidance (e.g., partial name matching) beyond the schema's 'Insider name fragment'. Baseline 3 is appropriate.

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

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

The description gives a clear verb+resource ('Search insiders') and names the qualifiers it supports ('by name or company'), so an agent understands the core operation. However, it does not distinguish itself from the related sibling get_insider_profile, leaving the boundary between search and detail lookup implicit.

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 guidance and no mention of alternatives, despite a directly related sibling (get_insider_profile) and adjacent search tools (search_companies, search_filings). The agent must infer that this is the discovery tool and the profile tool is the detail lookup.

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