algoum-mcp

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds useful content context — that the event includes an item code and source document — but says nothing about error behavior when an ID is unknown or the return shape beyond those two 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?

One short sentence with the payload description front-loaded and no filler. It is appropriately sized, though it is arguably a touch thin for a tool with no output 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 carry the return-value burden; it names two returned fields (item code, source document) but does not describe the overall event structure or what a missing/invalid ID yields. Adequate but incomplete for a no-output-schema 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?

There is a single parameter with 100% schema description coverage, which already explains that the ID comes from the list tools. The description adds no format, prefix, or validity detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ("Returns a single material event") and the singular scope separates it from the events_list siblings. It stops short of explicitly naming an alternative, but the get-vs-list distinction is clear from the wording.

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 never mentions events_list or events_list_recent. The only workflow hint ("Resource ID as returned by the list tools") lives in the schema, not the description.

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 cover the safety profile (readOnly, idempotent, openWorld), so the bar is lower. The description still adds two behavioral facts beyond the schema: results are sorted 'newest filing first', and ticker-or-cik is a hard requirement despite the schema listing no required fields. No pagination or return-shape detail, but the ordering and constraint disclosure are substantive.

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 written sentences: the first identifies the resource, examples, scope and sort order; the second states the input constraint. Nothing is padded and the identity of the tool is front-loaded.

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

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

With no output schema, the description should carry return-value burden, and it partially does by disclosing sort order and pagination-nullable cursor plus the ticker/cik requirement. It stops short of describing what a result record contains, but for a read-only list tool with full schema coverage this is close to 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 description coverage is 100%, so every parameter (to, from, cik, limit, cursor, ticker, event_type) is already fully documented in the schema. The description adds only framing context ('SEC Form 8-K') and no syntax or semantic 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 and resource ('Searches material events (SEC Form 8-K)') with concrete examples of event categories and a scope qualifier ('of one company'). It differentiates from events_get by being a search/list, but does not explicitly distinguish itself from events_list_recent, which shares nearly identical framing.

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 one precondition — 'Either ticker or cik is required' — which is genuine usage guidance since the schema marks zero required parameters. However, it never says when to pick this tool over the sibling events_list_recent or events_get, so the agent must infer the 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 readOnly, idempotent and openWorld, so the safety profile is covered. The description adds the meaningful constraint that the window is limited to up to 7 days and that no ticker is required, but says nothing about pagination behavior or result ordering beyond 'most recently filed'.

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 compact sentence that front-loads the core capability (most recently filed material events) before the scoping constraints. Nothing is wasted, though it is terse enough that it omits context it could afford to include.

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

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

For a read-only list tool with full schema coverage and no output schema, the description covers what the tool returns at a high level (most recently filed events across all companies). The main gap is the absence of guidance on choosing this tool over its list/get siblings.

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

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

Schema coverage is 100%, so all six parameters are documented in the schema, making 3 the baseline. The description only loosely gestures at two of them (minutes via 'minute window', ticker via 'no ticker required') and adds no syntax or enumeration 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?

The description names a specific verb (list) and resource (material events) plus a scope qualifier: most recently filed, all companies, minute window. It distinguishes itself from a ticker-scoped listing by stating 'no ticker required'. It does not explicitly name siblings like events_list or events_get, 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: an agent can infer this is the tool for a recent cross-company feed without a ticker. However, no alternatives are named (events_list, events_get) and no explicit 'use this when' condition is given, so guidance is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds that the response contains metadata plus a source URL, which is genuinely useful context, but says nothing about error behavior when the filing is unavailable or what the metadata fields are.

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 naming the return content and the scope constraint, with no filler. 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?

With no output schema, the description carries the burden of telling the agent what comes back, and it does by naming metadata and a source URL. Given the trivial one-parameter read-only surface, this is nearly complete; only the exact metadata 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?

Schema coverage is 100% with a single parameter, so the schema already documents 'id'. The description slightly sharpens semantics by clarifying the id is a filing_id (not a trade/event id), which is a real though modest addition. 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 resource (the raw SEC filing behind an insider trade, event or holding) and what it returns (metadata and source URL), which is clearly distinct from the sibling tools that fetch the trade/holding/event entities themselves. It does not name a sibling explicitly, but the scope is unambiguous.

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 '(use its filing_id)' implies the calling context: you invoke this after obtaining a filing_id from a list/entity tool. However, it never states when to prefer this over the sibling get/list tools or what to do if no filing_id is available, so usage is implied rather than explicit.

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, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine value by disclosing what the payload contains (error schemas, pagination, rate limit). It does not warn about payload size/token cost, which is the main behavioral risk for a whole-spec dump, so it stops 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?

Two sentences, front-loaded with the return value and followed by the routing condition. Every clause earns its place, with no restatement 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?

With no output schema, the description must convey the return shape, and it does so thoroughly (JSON OpenAPI spec covering endpoints, params, schemas, pagination, timestamps, rate limit). Nothing an agent needs to call this zero-arg 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, which is the baseline-4 case. The description correctly implies a single no-argument call and adds no misleading parameter language.

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

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

States a specific verb and resource ('Returns the OpenAPI specification of the algoum API as JSON') and enumerates the contents (endpoints, parameters, response/error schemas, pagination, timestamps, rate limit). This clearly separates it from the data-retrieval siblings like events_get or filings_get, which return business data rather than the spec itself.

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

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

Gives an explicit trigger condition — 'Call it when a tool's description is not enough' — plus concrete examples ('to look up a response field or an error code'). An agent knows exactly when to fall back to this tool instead of the domain 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, so safety behavior is covered. The description adds the meaningful semantic that results reflect import/freshness state and may lag, which is real behavioral context beyond 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 short sentences, the resource is front-loaded and the usage cue follows with zero filler. 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-parameter read tool with no output schema, the description covers what is being reported and why it matters ('per source' implies the breakdown). A brief note on the return shape would make it fully self-contained, but nothing needed to invoke it 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, so the baseline is 4. There is nothing for the description to disambiguate and nothing is missing on the input side.

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+resource ('Import status and data freshness per source'), which is concrete and distinguishable from the data-fetching siblings like events_list or filings_get. It is clear what the tool returns even though the name 'get_status' alone would be ambiguous.

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?

'Check it before relying on very recent data' gives an explicit trigger condition for calling the tool. It does not name any alternative or when-not-to-use case, but the positive guidance is clear enough to route an agent.

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, so the safety profile is covered. The description usefully adds the score's normalization range (-1 to +1) and that capital invested is included, but says nothing about how officers are counted, coverage gaps, or data freshness.

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 the metric and its scale front-loaded and no filler. It is efficient, though the parenthetical about the score range interrupts the flow slightly.

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 state the score range and the capital-invested component. It leaves the aggregation methodology and any minimum-data conditions unspecified, which is a minor gap for a single-metric 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 description coverage is 100%, so both ticker and window are already documented with examples and the 90d default. The description only echoes 'one company over a window' and adds no format or edge-case 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?

The description names a specific metric (buy/sell ratio of reporting officers for one company) and its output form (score from -1 to +1 plus capital invested), which is clearly distinguishable from transaction-listing siblings like insider_get_transaction. It does not explicitly name or contrast those siblings, 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 use this tool versus insider_list_transactions, insider_list_cluster_buys, or insider_get_transaction. The reader can infer it is a sentiment/aggregate metric, but no conditions, prerequisites, or alternatives are given.

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, so the safety profile is covered. The description adds one piece of return-content context (the filing reference), but says nothing about error behavior for unknown IDs or data freshness. With annotations carrying the load, this is an adequate but thin addition.

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 and scope front-loaded and no wasted words. It is efficient, though extremely brief relative to what it could convey.

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-by-ID tool with full annotation coverage and a fully documented schema, the description covers the essentials and even notes the returned filing reference. Only minor gaps remain (error handling, explicit routing from the list tool), which are acceptable given the tool's simplicity.

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

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

There is a single parameter with 100% schema description coverage, so the schema already explains that the ID comes from the list tools. The description adds no format, syntax, or sourcing detail beyond the schema, matching the baseline for fully documented single parameters.

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 ("Returns a single insider transaction") and clarifies the scope as singular, which implicitly contrasts with the sibling insider_list_transactions. It stops short of explicitly naming that sibling, so it is clear but not fully 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?

There is no when-to-use guidance, no mention of when to prefer this over insider_list_transactions, and no stated prerequisites such as where the ID comes from. The only workflow hint ("Resource ID as returned by the list tools") lives in the schema, not the description.

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, so the safety profile is covered. The description adds real behavioral context beyond that: the window filters the transaction date rather than the filing date, and the signal may precede the last filing — a non-obvious timing trait that materially affects interpretation.

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 tight sentences with zero filler, and the primary scope statement is front-loaded ahead of the timing caveat. 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 six-parameter read-only screening tool with no output schema, the description conveys the result shape (companies with clustered insider buys) and the timing nuance. It stops short of describing result ordering or what fields each cluster contains, but nothing critical to 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?

Schema description coverage is 100%, so all six parameters are already documented in the schema, which sets the baseline at 3. The description reinforces the transaction-date semantics of 'window' but adds no syntax, defaults, or constraints beyond what the schema 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 ('Finds') and a well-defined resource ('companies where several distinct insiders bought within the window'), which is precise enough that an agent can separate it from raw-transaction siblings like insider_list_transactions. It does not, however, name or contrast with any sibling tool 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?

Usage context is implied rather than stated: the description explains the semantics of the window and the backtest angle lives in the schema, but there is no explicit when-to-use-this-vs-alternatives guidance. An agent must infer that this is the aggregated/screening tool rather than the raw listing tool.

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, openWorldHint and idempotentHint, so the safety profile is covered. The description adds the look-back window (1-30 days) and the all-companies scope, but says nothing about result ordering, pagination behavior despite the cursor parameter, or result volume. Adequate but not rich.

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 that states the resource, the cross-market scope and the time window with no filler. Every clause carries information an agent needs.

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 five-parameter, no-output-schema feed tool the description covers what the feed is and its time bounds, which is the minimum viable. It leaves pagination, ordering and expected result volume unstated, though the annotations and 100%-covered schema absorb most of that burden.

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 five well-documented optional parameters, so the schema carries parameter semantics fully. The description only echoes the 1-30 day window and implies the absence of a ticker filter; it adds no format or syntax 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?

The description states a specific verb and resource (list insider trades) plus scope (cross-market feed, most recently filed, all companies). 'Cross-market feed of all companies' implicitly distinguishes it from per-ticker siblings like insider_list_transactions, but 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?

Usage is implied by 'cross-market feed ... of all companies', suggesting this is the unfiltered discovery endpoint rather than a ticker-scoped lookup. However, there is no explicit when-to-use statement, no mention of the cluster-buys sibling, and no guidance on when a recent feed is preferable to a targeted transaction query.

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, openWorldHint and idempotentHint, so the safety profile is covered. The description adds ordering ('newest filing first') and source filings (Form 4/5), but says nothing about pagination behavior, result volume beyond the schema's limit, or rate limits.

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 tight sentences with no filler; the core purpose is front-loaded and the required-input constraint follows immediately. Nothing could be removed without losing 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 filtered list tool with full schema coverage and explicit annotations, the description covers what it returns (insider trades, newest first) and the minimum input requirement. It is largely complete, though the absence of an output schema leaves the result shape only loosely implied.

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 every parameter including role, side, form_type and cursor is already documented in the schema. The description's 'either ticker or cik is required' partially restates the schema and adds no syntax or format detail, 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 and resource ('Searches individual insider trades'), plus scope ('SEC Form 4 and 5', 'one company') and ordering ('newest filing first'). It implicitly distinguishes itself from siblings like insider_list_recent and insider_get_transaction by being per-company, but it never names those alternatives.

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

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

It states a hard prerequisite ('Either ticker or cik is required'), which is useful. However it gives no when-to-use guidance versus insider_list_cluster_buys, insider_list_recent, or insider_get_transaction, leaving the agent to infer which sibling suits a given query.

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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds the default-quarter behavior, which is useful context—especially since the schema also documents it—but it doesn't describe rate limits, pagination behavior, or what 'complete' entails beyond the obvious. It adds some value but not rich behavioral context beyond the defaults.

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 action, and the default behavior is stated clearly without waste. Every sentence earns its place.

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

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

For a read-only retrieval tool with full parameter documentation and annotations covering safety and idempotency, the description is nearly complete. It could mention pagination or the nature of the 13F data, but nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so all parameters are documented in the schema. The description reiterates the quarter default behavior, which is already in the schema's description for 'quarter'. It adds minimal meaning beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb and resource: 'Complete 13F portfolio of one fund for one quarter.' An agent can tell this is a retrieval of a fund's holdings, distinct from siblings like institutional_list_holdings or institutional_get_sentiment. The scope is clear and exact.

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

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

The description implies you use this to get a fund's portfolio, and notes the default quarter behavior, but it doesn't explicitly state when to use this tool versus alternatives like institutional_list_holdings. There is no mention of prerequisites or exclusions, leaving the agent to infer.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld), and the description adds a genuinely non-obvious data-semantics caveat: 'Position values are reported holdings, not money flows.' That prevents misinterpreting the returned numbers. It still omits aggregation method, units, and default-quarter behavior, keeping it out of the top band.

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, zero filler, with the core scope stated first and the interpretation caveat second. 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?

For a two-parameter read-only tool with no output schema, the description gives the gist of what comes back ('aggregated buy/sell picture', 'position values') but not the shape of the aggregation, which quarter is defaulted, or how many periods are returned. Adequate but with clear 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%, so both parameters are already documented with examples (AAPL, 2026-Q1). The description adds no syntax, format, or defaulting 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 and resource ('aggregated institutional buy/sell picture') scoped to one stock and one quarter, which naturally separates it from the sibling list tools such as institutional_list_holdings and institutional_get_fund_holdings. It does not name those siblings explicitly, so it falls just short of full 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?

The description never says when to use this tool versus the many sibling institutional/filings/insider tools, nor does it mention prerequisites or the default behavior when 'quarter' is omitted. Usage must be inferred entirely from the name and scope phrase.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld), so the bar is lower. The description adds two things annotations cannot: the newest-first ordering and the semantic warning that results are quarterly snapshots rather than discrete trades, which materially affects interpretation. It stops short of describing pagination behavior despite the cursor parameter.

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

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

Two sentences, no filler, and the scoping/ordering fact is front-loaded before the semantic caveat. Every sentence earns its place.

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

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

With no output schema, the description would ideally indicate what a disclosure record contains (fund identity, filing date, holdings summary) so the agent knows what it will receive. Sorting and snapshot semantics are covered, but return shape and pagination expectations are left entirely to 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 100%: all four parameters carry descriptions with ranges, defaults, and format examples (e.g., 2026-Q1, meta.next_cursor). The description adds no parameter-level detail beyond ordering, 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?

The description names a specific resource (13F disclosures) with scope (fund level) and ordering (newest first), so the agent knows exactly what is listed. It does not, however, distinguish itself from close siblings like institutional_list_holdings or institutional_get_fund_holdings, so sibling differentiation must 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?

The clarification that this is a quarterly snapshot stream rather than a feed of single trades implies when the tool is appropriate, which is genuinely useful. But there is no explicit when-to-use statement and no named alternative (e.g., institutional_get_fund_holdings) for retrieving a specific fund's positions.

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, openWorldHint=true, and idempotentHint=true, so the description does not need to repeat safety details. The description adds only that it searches by free text or CIK; it does not explain result format, pagination, or rate limits, which would be helpful given the lack of an 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?

The description is a single clear sentence that front-loads the action and resource. Every word earns its place with no redundancy.

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

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

The tool has four parameters, no output schema, and no annotations about return format, yet the description omits pagination behavior, result shape, and how to use the cursor. For a search tool whose output schema is absent, the description is too thin to fully guide correct invocation.

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

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

Schema description coverage is 100%, so the schema fully documents the four parameters. The description mentions free text and CIK but does not add syntax, examples, or interplay between parameters beyond what the schema provides, making the baseline 3 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 uses a specific verb 'Searches' and a clear resource 'institutional investment managers (13F filers)', and mentions the two lookup methods (free text or CIK). It distinguishes itself from sibling lookups like institutional_get_fund_holdings and institutional_list_holdings, but does not explicitly name 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 description implies when to use it: searching for managers by name or CIK. However, it does not state when to use this versus other institutional disclosure tools, nor does it describe exclusions, pagination flow, 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 cover the safety profile (readOnly, idempotent, openWorld), so the bar is lower. The description earns credit by disclosing the data-source constraint — results are limited to 13F reporters, which implies quarterly, filing-lagged coverage rather than real-time ownership. It does not mention reporting lag or completeness caveats explicitly.

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; every clause (verb, resource, 13F constraint, quarter scoping) 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?

With no output schema, the description should arguably say more about what a result contains (fund name, shares, value, change) and how paging works, though the cursor parameter hints at pagination. It is adequate for a simple list tool but leaves the return shape 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 description coverage is 100%, so ticker, quarter, limit, and cursor are all documented in the schema. The description adds no format, default, or range detail beyond that, making the baseline 3 the right call.

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 ('Lists') plus a precise resource ('funds that report a 13F position in a stock for a quarter'), which is the inverse of the sibling institutional_get_fund_holdings and thus reasonably distinguishable. It stops short of naming that sibling or the direction contrast explicitly, so 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?

The purpose implies the natural use case (finding holders of a given ticker), but there is no explicit when-to-use/when-not guidance and no mention of the alternative institutional_get_fund_holdings for the reverse lookup. Usage is inferable but not 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, idempotentHint and openWorldHint, so safety and repeatability are covered without the description. The description adds only workflow framing, not behavioral detail such as pagination limits or the fact that a name search may return multiple matches. With annotations carrying the safety profile, 3 is appropriate.

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

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

Two short sentences, front-loaded with the core capability before the usage hint. Every clause carries information and nothing is padded.

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 five parameters, no required fields, a mutual-exclusion constraint, and no output schema, the description is minimally sufficient but does not tell the agent what a result contains (ticker, CIK, name?) or how pagination behaves. It is adequate to invoke the tool, not to interpret its output confidently.

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

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

Schema coverage is 100%, so the five parameters (cik, ticker, query, limit, cursor) are fully documented in the schema, including the mutual-exclusion constraint. The description restates the same three resolution inputs without adding format, precedence, or syntax detail. Baseline 3 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 specific verbs and resources: resolve a ticker or CIK, or search companies by name. That is far more informative than the tool name alone and matches the title. It does not explicitly contrast with any sibling, but the resolver role is implicitly distinct from the data-fetch 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?

"Use it to find the ticker for other tools" gives a clear workflow context: this is a prerequisite lookup step feeding the other tools. There is no statement of when not to use it or which alternative to prefer for a given input, 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.