form4api-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.9.6
Disambiguation5/5
Each tool targets a distinct aspect of insider trading data (e.g., company overview, insider transactions, signals, sentiment). Descriptions explicitly compare related tools, making boundaries clear. No two tools serve the same purpose.
Naming Consistency4/5
Tool names follow a verb_noun pattern with snake_case (e.g., get_company_overview, list_companies). The set uses a mix of 'get', 'list', 'search', 'check', and 'research', which is slightly inconsistent but still predictable and descriptive.
Tool Count3/5
27 tools is on the high side for an MCP server, but each addresses a specific need (e.g., signals, sentiment, webhooks, usage). The scope is broad, and while some tools could be merged, the set remains manageable.
Completeness4/5
The server covers core insider data retrieval thoroughly (companies, insiders, transactions, signals, sentiment, filings, webhook events). Notable gaps include the absence of a create/delete webhook tool and lack of data export, but these are minor.
Average 4.6/5 across 27 of 27 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 33 commits in the last 12 weeks
- Last stable release on July 12, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnlyHint and openWorldHint annotations by disclosing plan gating, the PLAN_REQUIRED error on Free/Starter, the live no-cache behavior, the meaning of non-superseded trades, and the 200-with-empty-array behavior for tickers with no congressional trades. This is strong behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but appropriately detailed, covering return shape, edge cases, plan limits, and live behavior. It is not overly verbose, though the explanation about the absence of a separate ticker entity could have been tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description sufficiently explains the expected return shape, empty-ticker behavior, and access constraints. It could be even more complete by specifying exact response fields or boundary behavior, but it is enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters with 100% coverage, so the description adds little parameter meaning beyond repeating the trailing-window behavior for window_days. This matches the baseline of 3 when schema descriptions carry the semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it returns every politician who traded a given ticker, with per-politician trade counts and ticker-level totals. This is a specific verb-resource pairing that is semantically distinct from sibling tools like get_transactions or list_congress_trades.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear parameter context, such as optional window_days behavior and Pro plan requirements, but it never explicitly tells an agent when to choose this tool over a sibling like get_congress_politician or list_congress_trades. It provides implied usage rather than direct routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnly and openWorld hints. Description adds pagination limit (max 100/page) and plan requirement, which are useful behavioral details beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no redundancy. Efficiently conveys resource, filters, use cases, sibling associations, and constraints (plan, pagination).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with good schema and no output schema, description adequately covers functionality, filtering, pagination, and plan requirement. Missing return format details but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 7 parameters with descriptions (100% coverage). Description adds context like 'CUSIP resolved to ticker automatically' but mostly summarizes, not adding significant new semantics beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool returns institutional 13F-HR holdings with filtering options. It gives concrete use cases ('who owns NVDA') and distinguishes from siblings like get_managers and get_transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides examples of when to use and pairs with siblings for further lookups. Mentions plan requirement. Lacks explicit when-not-to-use but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and openWorld. The description adds value by detailing pagination (max 100/page) and the Business plan requirement, which are behavioral traits not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each serving a clear purpose: stating the function, explaining filters and pairing, and noting requirements and limits. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only browsing tool with good annotations and schema, the description covers essential usage aspects (filters, companion tool, plan requirement, pagination). No output schema exists, but the return value is implicitly clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description reiterates the partial match and minimum AUM filter, but does not add significant new meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool browses the institutional manager index with specific data (latest 13F-HR filing date and AUM). It distinguishes itself from siblings by mentioning pairing with get_holdings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for use (browsing managers) and suggests pairing with get_holdings. It also notes the Business plan requirement. However, it does not explicitly exclude scenarios where other tools might be better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description adds value by specifying 'Free plan' (implies usage limits) and listing returned fields. No contradictions; additional context enhances transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose and fields, followed by usage guidance. No unnecessary words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description lists all returned fields and provides usage context. Lacks mention of limits or pagination, but not needed for single-ticker lookup. Adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter (ticker), so baseline is 3. The description doesn't add extra semantics beyond the schema, but it's adequate given the high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides a company profile for a single ticker, listing specific fields (name, CIK, SIC, etc.). It distinguishes from siblings by explicitly naming get_company_insiders and get_transactions as alternatives for different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool ('for company identity/metadata') and when to use alternatives ('use get_company_insiders to list who is filing, or get_transactions with ticker= for their trade history'). Clear and actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite readOnlyHint and openWorldHint already being present, the description adds substantial behavioral context: live database execution, no caching, Pro plan requirement, non-predictive non-ML semantics, explicit STOCK Act disclosure ranges, and exact definitions for strength, firstSeen, lastSeen, and disclosureLagDays.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but deliberately structured and information-dense. The use of DEFINITION, STRENGTH, and HONESTY anchors helps parseability, though some redundancy around window semantics and non-predictive claims could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex convergence endpoint with no output schema, and the description covers response field meanings, pair-picking logic, the representative signal, disclosure range semantics, filtering, pagination sufficient, and operating expectations. The agent is well equipped to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all parameters with 100% coverage, including defaults and clamps. The description reinforces the meaning of window_days and lookback_days but does not add materially new information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: it returns tickers where an insider cluster-buy and a congressional purchase converged within a window. This clearly distinguishes it from broader tools like get_signals or get_insider_transactions by the defined convergence concept.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it is for surfacing current insider-plus-congress convergence signals, supports a trailing lookback, requires Pro plan, and runs live with no caching. It does not explicitly name alternatives or state when not to use it, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds valuable context: caching for 30 minutes, no API key required, and a detailed list of returned metrics. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with purpose, then usage guidance, then a bulleted list of included metrics, and finally caching/auth notes. It is slightly long but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description provides a comprehensive list of what is returned (timestamps, latencies, counts, percentages) and context on caching and public access. The tool is simple and the description fully explains its behavior and output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameters and the description explicitly confirms 'Takes no parameters', adding certainty. With no parameters, the baseline is 4, and the description fulfills that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns public data-quality metrics for the whole dataset, using specific verbs like 'returns' and 'use this to check'. It distinguishes itself from sibling tools by explicitly stating it is not for looking up individual companies or transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use guidance ('check whether the dataset is current before relying on it') and what not to use it for ('not to look up any single company'). It mentions it's public and needs no API key, but does not explicitly name alternative sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds specific context: requires valid X-Api-Key (401 otherwise), data is per calendar day UTC, and window is trailing. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no wasted words. Front-loaded with core purpose, then usage guidance. Every sentence serves a clear function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with no output schema, the description covers purpose, usage guidelines, auth requirement, and return format (daily time series). Could be slightly improved by explicitly stating the output structure (e.g., array of {date, count}).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the single parameter 'days' with its default and maximum. The description adds little extra beyond mentioning 'trailing N days' and 'one data point per calendar day'—the latter relates to output, not parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'daily request counts for the authenticated key over a trailing window' as a time series, and distinguishes itself from siblings by naming specific alternatives for different use cases (single snapshot or raw log).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use this tool ('plot usage trends or check rate-limit headroom over time') and when not to, referencing exact alternative endpoints. Also notes authentication requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds that the tool is paginated with a max of 100 per page and is on a free plan, providing useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first states the purpose and filters, the second gives usage guidance. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters and no output schema, the description covers the key aspects: what the tool returns (Form 4 rows), pagination limits, and differentiation from similar tools. It is sufficiently complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description briefly summarizes the filterable fields (ticker, transactionCode, date range, exclude_10b5) but does not add significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves all Form 4 transactions for a specific insider by CIK, and distinguishes it from siblings by noting that get_transactions provides broader filters and get_insider_career_summary returns aggregated data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to use the tool after obtaining an insider's CIK and contrasts it with alternative tools, covering when to use each. Also mentions free plan and pagination limits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint: true and openWorldHint: true. The description adds valuable context: does not return the signing secret, requires valid X-Api-Key, and implies the tool is safe and open. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loads the main purpose, and uses only necessary sentences. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no parameters, the description covers all essential aspects: what is returned, what is not, auth requirements, and a hint for secret recovery. Complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, schema coverage is 100%. The description compensates by describing the output fields and important constraints (e.g., not returning the secret). Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('list webhook subscriptions'), the scope ('owned by the authenticated API key'), and details the returned fields. It distinguishes itself from other tools by specifying it returns both active and deactivated subscriptions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some context (e.g., not returning the signing secret, auth requirement) but does not explicitly state when to use this tool versus alternatives like 'get_webhook_events' or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Disclosed pagination, case-insensitive substring matching, minimum length requirement, and 400 error for short queries. Also notes free tier availability. Annotations already indicate readOnlyHint and openWorldHint, but description adds concrete details beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each with clear purpose. First sentence defines action, second explains output and downstream use, third covers default behavior, fourth notes pricing. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return fields (CIK, title, flags, filing count). Covers error case (short query) and pricing. Complete enough given the tool's simplicity and sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters fully described in schema (100% coverage). Description adds key details: case-insensitive substring, minimum 2 characters, page defaults, per_page max 500. This adds practical usage constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool searches insiders by name and returns CIK, title, and flags. Distinguishes from sibling tools like get_company_insiders by explicitly mentioning CIK resolution for downstream endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use: 'resolve a person's name to their CIK before fetching transaction history, career summary, or scorecard'. Also notes behavior when name is omitted. Does not explicitly mention when not to use, but context with sibling tools implies it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds value beyond readOnlyHint and openWorldHint by specifying pagination (max 100/page), free plan, and the exact fields returned. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences covering purpose, usage guidance, and pagination/free plan. No unnecessary words, highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output fields are described, pagination mentioned. Lacks handling of edge cases like empty results or error conditions, but adequate for a list tool without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description does not need to add much. The description mentions 'given ticker' but adds no extra semantics beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a full roster of insiders who filed Form 4 for a ticker, listing specific fields. It distinguishes from sibling tool get_transactions by noting it is for enumerating insiders before pulling career summaries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool (to enumerate insiders before pulling career summaries) and directs to get_transactions for trade history, providing clear alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/anomaly annotations, the description discloses live execution with no caching, the Pro plan requirement (402 on Free/Starter), and the 404 behavior when neither ID nor slug matches. These are valuable behavioral traits that the annotations do not already cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and contains all necessary behavioral context in a compact two-sentence paragraph, but there’s a small redundancy: the pseudo‑'Requires Pro plan or higher' line repeats the parenthetical '(Pro plan+)' from the opening sentence. Still, overall structure and placement are excellent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description clearly enumerates the required return data: identity fields, buy/sell trade counts, most recent disclosure date, top N tickers, and recent trades with their shape. It also covers error responses and plan restrictions, making the tool realistically callable end-to-end without additional assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The main description adds marginal value by clarifying that 'most traded' is by trade count and that recent trades have a specific shared shape, but it does not materially change understanding of the three parameters beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get one politician's congressional trading profile.' It then enumerates the exact returned fields and differentiates the tool from paging /v1/congress/trades by framing it as a 'one-call politician overview,' which helps an agent distinguish it from siblings like list_congress_trades or get_congress_ticker_rollup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly directs agents with 'Use this for a one-call politician overview rather than paging /v1/politician= yourself.' This names the alternative approach and tells the agent when this tool is appropriate, satisfying both when-to-use and an alternative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and openWorldHint. Description adds return fields (dates, identity, transaction count) and free plan mention, but lacks details on error behavior or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and example, concise with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 1 param and no output schema, description covers what is returned and when to use. Could mention missing accession handler but sufficient for context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with description. Description adds format example (0000320193-26-000001) and context to copy from other tools, exceeding the schema's base description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it fetches a Form 4 filing by accession number, with format example. Distinguishes from siblings like get_recent_filings and get_transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this once you already have an accession number from get_recent_filings or get_transactions', providing clear when-to-use and source of input.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. Description adds that it requires a Pro plan and that return fields are fractions (e.g., 0.05 = +5%), complementing annotations without contradiction. No missing behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph is efficient and front-loaded with the main purpose. Could be slightly more structured (bullets for fields), but no redundancy. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage guidance, behavioral nuances, and parameter details. Does not mention error handling or rate limits, but given simplicity (single param, no output schema) and annotations, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the CIK parameter fully. Description adds value by noting leading zeros optional, providing a concrete example (Tim Cook), instructing to resolve names via search_insiders, and clarifying return format (fractions).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it aggregates a career rollup for one insider by CIK, listing specific data fields. It explicitly distinguishes from get_insider_transactions, making its purpose unambiguous and distinct among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance: 'Use this instead of get_insider_transactions when you want a pre-computed summary rather than raw rows; pair with the generated get_insider_scorecard'. Provides when-to-use, when-not, and recommended companion tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds valuable context: no API key required, cached for ~12 hours, and lists the specific fields returned. Does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and key feature (no API key). It lists the returned fields but could be slightly more concise by grouping related items. Still, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, no output schema, and clear annotations, the description provides complete context: what it returns, use cases, limitations, caching, and alternatives. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. Description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns public corpus-wide statistics and distinguishes itself from sibling tools like get_company_overview and get_data_quality by specifying where to find per-company or per-insider data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: use for corpus-wide totals (e.g., marketing widget), not for per-company or per-insider data, and suggests alternative endpoints. Also recommends get_data_quality for freshness metrics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and openWorldHint. The description adds critical behavioral context: exclusion of 10b5-1 plans, output composition, Business plan requirement (402 error), and pagination details. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph with front-loaded purpose. Every sentence adds value, but it is slightly dense. Could be slightly more concise, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no required ones, no output schema, the description fully explains the output structure (signal type, detection date, counts, total value, underlying transactions), pairing with explain_signal, and Business plan requirement. Complete for a read-only list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented. The description does not add new parameter meaning beyond the schema. Baseline 3 is appropriate as the schema carries the semantic burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns 'Cluster buy/sell signals' and explains the concept of multiple insiders trading same direction. It distinguishes from get_transactions and pairs with explain_signal, making the purpose specific and differentiated from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool (for cluster signals), explains what it excludes (10b5-1 trades), and recommends get_transactions for raw trades. It also mentions Business plan requirement and pagination, providing comprehensive usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate read-only and open-world behavior, but the description adds substantial behavioral detail: 500-attempt cap, newest-first ordering, default and maximum range for since, 401 auth behavior, and plan-based payload redaction with payloadRedacted flag. This gives the agent accurate expectations beyond 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded with the core purpose and return shape. It is slightly redundant in stating the default 24-hour window twice, but every other detail serves a clear purpose, especially given the absence of an output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema, the description is remarkably complete: it states result limit, ordering, timestamps, status code, dead flag, payload behavior, auth requirement, and error conditions. Very little is left for the agent to guess.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining how since interacts with the 24-hour default and 30-day maximum, and why old timestamps may still return redacted payloads based on the current plan.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb and resource clearly: it replays and returns webhook delivery events. It goes beyond a vague label by explaining what is returned — delivery id, subscription id, event type, timestamps, status code, dead state, and payload — making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit use case: reconcile missed webhook deliveries after an outage, rather than depending on push delivery. However, it does not name a sibling tool as an alternative or state when not to use it, so there is clear context but no formal exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses graceful degradation with null and _unavailable notes, concurrency (fetches all sections concurrently), and plan-based availability (Free vs Business), which go beyond the readOnlyHint and openWorldHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately sized but front-loaded with the main purpose, and each sentence adds value; however, it includes a disclaimer that could be separate, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with no output schema, the description thoroughly explains the bundled components, plan behavior, concurrency, and degradation, providing sufficient context for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description does not add significant new information about parameter meaning beyond the schema, though it contextualizes recent_limit within the bundled result.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool bundles company profile, insider transactions, signals, sentiment, and direction summary into one call, and explicitly distinguishes it from four sibling tools it replaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to use this tool FIRST for any insider-research question, replaces separate calls, and explains graceful degradation and plan requirements for when to use alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, indicating it's a safe read operation. The description adds useful behavioral context: it works on every tier and is free, and it's a snapshot of current usage. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It is front-loaded with the core purpose and efficiently includes usage guidelines and alternatives.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description sufficiently explains the tool's output fields (plan name, requests today, daily limit, all-time count). It is complete for a simple snapshot tool with no parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters (schema coverage 100% trivial), so baseline is 4. The description adds meaning by explaining what the tool returns (plan name, requests today, etc.), compensating for the lack of an output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides a snapshot of the authenticated API key's current usage, listing specific fields (plan name, requests today, daily limit, all-time count). The verb 'check' matches the tool name and the resource is well-defined, distinguishing it from sibling tools like get_usage_history and get_key_activity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this for a quick right-now check and provides alternatives: get_usage_history for daily trends and get_key_activity for per-request logs. This gives clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld annotations, the description discloses important behavior: only insiders with 3+ non-superseded transactions, the 5,000 most active cap, daily rebuilds, non-normalized casing, and de-duplication of filer groups into one row per group. It also confirms this is not plan-gated, which is useful invocation context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but every paragraph adds substantive context: coverage rules, source collision behavior, grouping rationale, and search alternative. It is front-loaded with the core behavior and mostly well organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description does enough by stating the returned scaffold: A-Z rail, counts, one page of insiders, and filerGroupSize. Minor gaps remain around full row field names and pagination metadata, but nothing that blocks correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real value by explaining letter omission semantics, the '#' use case, sorting by surname due to EDGAR formatting, and how one page maps to a letter. This goes beyond simply restating the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb and resource: browse insiders alphabetically by surname, returning a per-letter rail and one page of rows. It clearly differentiates this from search-by-name tools, telling the agent this is not a full-text search over every filer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit alternative: use GET /v1/insiders?name= to search every filer when a target is outside the capped directory set. It also explains the inclusion rule and caps, making the configured scope unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral traits beyond annotations: uses absolute return (not market-adjusted), only discretionary open-market buys, excludes non-10b5-1 buys, min_trades floor of 5, caching for 1 hour, and plan requirement. These details are not in the readOnlyHint or openWorldHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with front-loaded purpose. Each sentence adds value, but the description is relatively long. For the complexity, it's acceptable; minor room for tightening.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return values implicitly, explains methodology, plan requirement, and caching. Without an output schema, it provides adequate context for an agent to understand what is returned and how it is computed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the min_trades floor (silently raised to 5) and referencing the scoring methodology. However, it does not enumerate each parameter's details beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a ranked leaderboard of insiders by buy track record, distinguishing it from the per-insider scorecard sibling tool. It uses specific language like 'ranked leaderboard' and 'scored-buy methodology' to convey purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this to discover which insiders have the best track record; use the per-insider scorecard once you have a specific CIK.' It also notes the Business plan requirement and caching behavior, guiding appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the response structure (endpoint, status, duration, timestamp), auth requirement, and the ordering (most recent first). Annotations indicate readOnly, which aligns; the description adds valuable context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, front-loaded sentences: function, usage, auth. No wasted words, well structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple interface (1 param, no output schema), the description is complete: covers purpose, return fields, use cases, auth, and alternatives. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and fully describes the 'limit' parameter with defaults and maximum. The description does not add additional meaning beyond what the schema provides, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns recent per-request API activity logs for the authenticated key, and distinguishes it from the sibling tool for aggregate usage trends by name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when-to-use scenarios (debugging, checking errors, spotting slow requests) and when-not-to-use (usage trends), with a direct reference to the alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, openWorldHint) are minimal; the description adds critical behavior: automatic exclusion of 10b5-1 plan trades, explaining that the score reflects discretionary conviction. This is beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences, front-loaded with the core purpose. Every sentence adds value: purpose, behavioral note, alternative usage, requirement. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description adequately explains the return value (one point per month, range -100 to +100). Combined with the schema and minimal annotations, the description is sufficient for a simple read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; both parameters have clear descriptions. The tool description adds only minor nuance (e.g., case-insensitive for ticker, default months), not significantly beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb (get), resource (insider-sentiment score), and scope (by ticker, monthly, with range -100 to +100). It distinguishes from sibling tools like get_transactions and get_signals by noting they provide trade-level detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use alternatives: 'Use get_transactions or get_signals for the trade-level detail behind a given month.' Also notes the Business plan requirement, setting usage prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint=true and openWorldHint=true annotations, the description reveals key live behaviors: the result is uncached, the exact staleness thresholds for each component, the overall status values, and the HTTP 503/200 response semantics. That is strong behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Though the description is dense, every clause earns its place: thresholds, status logic, HTTP behavior, and authentication requirements are all covered without fluff. The leading 'Ingestion-death detector' immediately orientates the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema health utility, the description provides all the context an agent needs to invoke it and interpret the result: what is measured, when it is considered stale, what overall statuses occur, and what HTTP status is returned. Nothing crucial is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and schema coverage is 100%, so there are no parameter semantics to document. The baseline for a parameterless tool is appropriate here, and the description correctly focuses on behavior instead of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a precise resource ('Form 4 freshness, parse-queue health, price-feed freshness') and an actionable verb ('detector'/'Returns live ingestion health'). It clearly differentiates this tool from the broader sibling set focused on filings, insiders, or usage by centering on ingestion pipeline health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit context on when to use the tool: it can be pointed at directly by an external uptime monitor, and it requires no API key or plan. It does not enumerate alternatives or say 'use X instead of Y', but the use case is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the readOnlyHint and openWorldHint annotations, disclosing non-superseded trade filtering, exactly how trade types count (e.g., Sale and PartialSale count as sells; Exchange only toward total), ordering behavior, pagination, live query behavior, and the 402 PLAN_REQUIRED failure mode. This is exceptionally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns a place: result scope, counts semantics, ordering, use case, alternative endpoint, plan requirement, and caching behavior. It front-loads the core purpose and avoids filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description does the work of explaining what each result includes: total/buy/sell counts, sell semantics, and most recent disclosure date. The ordering, pagination, live-query behavior, plan requirement, and full-profile alternative complete the context an agent needs to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both page and per_page are already described with defaults and maximums. The description's mention of 'paginated list' reinforces the parameter purpose but adds minimal semantic detail beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Ranked rollup of politicians by congressional trade activity.' It clearly differentiates this from siblings like list_congress_trades and get_congress_politician by describing the aggregated politician-level nature and trading counts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use the tool: 'Use this to discover active traders.' It also provides a direct alternative for full profiles with a specific endpoint, making routing between this and get_congress_politician clear. The plan requirement is also stated, which is valuable usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds that the tool returns 'pass/fail/warn per check plus concrete next steps' instead of raw errors, and that it can isolate configuration vs. plan vs. backend issues.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: first states purpose and return format, second tells when to use, third reassures no parameters. No wasted words, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only diagnostic tool with no output schema, the description fully explains the return type (pass/fail/warn + next steps) and usage context. Nothing missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in schema, and description confirms 'No API key or parameters required'. This adds clarity that nothing is needed, scoring baseline 4 for zero-param tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it performs a diagnostic check for API key validity, backend reachability, and plan status. It distinguishes itself from siblings like check_usage or get_public_stats by focusing on setup verification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use: 'Run this first whenever another tool fails or returns a 401/402'. Also notes that no API key or parameters are required, guiding the agent to use it as a first step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already providing readOnlyHint and openWorldHint, the description adds valuable behavioral context: timing (2 days before Form 4), pagination (max 100/page), and the signal nature (discretionary vs 10b5-1). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence adds value: purpose, timing, filtering, cross-reference, plan requirement, pagination. No wasted words, well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core purpose, filtering, usage advice, complementary tools, and restrictions. Lacks explicit output fields, but given no output schema and common knowledge of Form 144, it is sufficiently complete for an experienced agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds marginal value by advising use of exclude_10b5 for signal analysis and clarifying date range and partial match on insider name, but mostly reiterates schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves Form 144 'notice-of-proposed-sale' filings, explaining they are early-warning signals for insider sales. It distinguishes from siblings like get_transactions by suggesting cross-referencing to check execution, and specifies filtering options.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly guides when to use (early-warning signal) and when to use alternatives ('Cross-reference with get_transactions/get_insider_transactions'). Also recommends excluding 10b5-1 for signal analysis and notes 'Requires Business plan' as a usage restriction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, which the description does not contradict. The description adds context about being a free plan and the specific output fields, but nothing beyond that. With annotations covering safety, the description adds value without being exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each serving a distinct purpose: function/output, usage guidance, and context. Information is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description enumerates return fields (name, titles, role flags). With one required parameter and a simple lookup, this is complete and sufficient for the agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (cik) with 100% schema coverage. The description adds meaning by explaining the CIK format, leading zeros optionality, and linking to search_insiders for name resolution. This goes beyond the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool looks up an insider by CIK and lists the returned fields (name, titles, role flags). It distinguishes from sibling tools like search_insiders, get_insider_transactions, and get_insider_career_summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use search_insiders if only a name is available, and directs to other tools for trading history or career summary. This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint and openWorldHint, and the description adds substantial behavioral detail: plan gating with 403 rejection semantics, pagination depth limits per plan, return-horizon fraction convention, 10b5-1 filtering behavior, and the shape of returned rows. It also notes that inst_ownership_trend may have no effect if enrichment is disabled, which is exactly the kind of edge-case transparency agents need.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and information-rich, with no filler, but it is a single long paragraph that would benefit from structural separation for readability. Given the tool's 31-parameter complexity, the length is justified, and front-loading the purpose and alternatives helps the agent fast.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, 31-parameter tool with no output schema, the description covers all essential contextual needs: purpose, alternatives, output row contents, pagination behavior, plan restrictions, parameter semantics, and bulk-export fallback. The agent has enough to decide when to call it and how to interpret the result shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all 31 parameters. The description still adds meaningful value beyond the schema by clarifying plan requirements for min_value vs max_value, explaining that max_value rejection fails loudly rather than silently, and summarizing the 'significant' preset behavior and the distinction between code/codes/exclude_codes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Search SEC Form 4 insider transactions with rich filters', then enumerates the supported dimensions. It also explicitly separates itself from get_recent_filings, get_insider_transactions, and get_company_insiders, so an agent can confidently distinguish this tool from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('filtered or historical search across many companies/insiders') and names direct alternatives with their use cases: get_recent_filings for an unfiltered live feed, get_insider_transactions/get_company_insiders when a specific insider/company is already known. It also routes bulk pulls to the REST export endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations (readOnlyHint, openWorldHint) are augmented by detailed behavioral context: House-only coverage, Senate 403 behavior, amended-away rows excluded, plan-clamped windows, no caching, and the X-Coverage-Note header. This goes far beyond the annotations and materially changes how an agent should interpret empty or partial results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but information-dense; every sentence earns its place given the complexity of the coverage rules, plan clamps, and filter semantics. It is front-loaded with the core purpose, though the all-caps section labels make it a bit visually noisy rather than elegantly structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter list endpoint with no output schema, the description covers the output shape (paginated JSON, ordering, amountLow/amountHigh, disclosureLagDays), the pagination defaults live in the schema, and the major edge cases (Senate coverage, plan clamps, amended rows, live query behavior) are explicitly disclosed. An agent can decide whether to call this endpoint and how to interpret ambiguous results without guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% parameter coverage with individual descriptions, so the baseline is 3. The tool description adds meaningful behavior beyond the schema: it explains that plan-level clamps constrain disclosure_date_from, that min_amount is range-aware against AmountLow rather than a midpoint, and that every row carries amountLow/high plus disclosureLagDays.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource — 'Query congressional STOCK Act trades' — and clarifies exact scope and ordering: paginated, most recently disclosed first, non-superseded rows only. It clearly differentiates itself from sibling rollup endpoints by stating that per-politician or per-ticker rollups belong on /v1/congress/politicians and /v1/congress/tickers/{ticker}.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly names when to use the endpoint, such as for listing congressional periodic-transaction-report trades, and routes rollup-style queries to alternative endpoints. It also warns that chamber=Senate returns empty results with a special header due to coverage limitations, and explains plan-based date clamps so callers know not to expect results beyond their entitlement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds critical behavioral context: live reconstruction, no caching, potential difference from stored signal, plan requirement, and specific error codes. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly concise for the amount of information conveyed, and front-loaded with the main purpose. However, it is somewhat verbose with the detailed reconstruction list; could be slightly more streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description thoroughly explains what the response contains (cluster buyers/sellers, excluded trades, ratios) and all error scenarios. It fully equips an agent to understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds value by explaining that omitting 'date' retrieves the most recent signal, and by detailing error conditions for invalid date. This goes beyond the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Explain why a signal fired', detailing the specific resource (signal) and the elements it reconstructs (insiders, trades, exclusions, criteria). It distinguishes itself from the sibling 'get_signals' which is for scanning many companies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use ('audit or debug a specific signal') and when not to ('rather than to scan many companies, use GET /v1/signals for that'). Also mentions plan requirement (Business plan+) and error conditions (404, 400).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, openWorldHint), description details scoring methodology (absolute return, anchored at filing close), hit definition, handling of small samples, no caching, and specific return value formats (fractions). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is comprehensive but efficiently structured: opens with purpose, then methodology, usage guidance, edge cases, and format notes. Every sentence adds value without unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all essential aspects: required parameter, output fields (with fraction notation), sample sufficiency guard, error scenarios, plan restrictions, and computational behavior. Suitable for correct invocation despite lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema fully describes the single parameter (cik) with 'exact match'. Description adds contextual value by mentioning plan requirement and 404 error for missing CIK, which aids agent understanding of parameter validation and error handling.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it returns a scored track record of insider buys, differentiates from sibling tools like get_insider_summary (raw totals) and get_insider_leaderboard (ranking many insiders), and specifies the methodology and output fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use this tool (for scored track record) versus alternatives, notes plan requirement (Pro+), mentions error conditions (402, 404), and explains when fields are null due to sample insufficiency.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, openWorldHint) already indicate read-only and open-world behavior. Description adds specific behavioral info: new filings appear within ~60 seconds, returns specific fields like accession number, dates, identities, and transaction count. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with all key information front-loaded: purpose, sorting, filtering, timing, alternative tool, output summary, and constraints. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description lists returned fields (accession number, dates, identities, transaction count) and mentions subsequent use of get_filing for full detail. Covers timing, filtering, pagination, and sibling comparison. Complete for a simple paginated read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 3 parameters with descriptions, so baseline is 3. Description adds extra value by explaining the purpose of the ticker filter, noting pagination and max per_page limit, and describing output fields that imply what parameters control. Slight improvement over schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it's a live feed of newest SEC Form 4 filings, sorted most-recent-first, with optional ticker filter. Distinguishes from sibling get_transactions by specifying its use case for checking current activity rather than historical search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool ('what just happened') vs. get_transactions (filtered/historical). Also mentions free plan, pagination, and max 100 per page, giving clear operational context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, and the description builds on them with substantial behavioral detail: the 5-minute heartbeat cadence, DB-connectivity nature, pro-rating of partial days, 5-minute caching, and no API key or plan requirement. It also explains the semantics of start date and overallPct, which is far beyond what annotations alone provide. There is no contradiction between description and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence carries useful information: response shape, date window semantics, computation method, intended usage, alternative tool, caching, and auth requirements. It is front-loaded with the core purpose and avoids filler or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description correctly carries the full burden of explaining the return value: the days array, per-day slot counts, uptime percentages, overallPct, and start date behavior. It also covers parameters, caching, and auth requirements. An agent has enough information to call the tool correctly and interpret its response without external context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing meaningful to add beyond the empty input schema. The description explicitly states 'Takes no parameters,' which removes any assumption that a timeframe or entity filter might be required. Given the zero-parameter baseline, this is appropriately handled.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Measured uptime history for the public status page — trailing 90-day daily breakdown.' It clearly distinguishes what the tool returns from other data endpoints, and later explicitly contrasts it with live freshness data from GET /v1/data-quality. This is enough for an agent to understand the tool's distinct purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description is explicit about when to use the tool: 'Use this to render an uptime history / status bar; for live corpus freshness use GET /v1/data-quality instead.' It gives a positive use case, a negative use case, and names the alternative endpoint. No agent would need to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and openWorld. Description adds that it returns a single page, always top limit, sort order behavior (case-insensitive, fallback), and no page parameter. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph with logical flow: purpose, usage constraints, entry details, sort behavior. Efficient but could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, use cases, entry fields, sort behavior, limits, plan access. No output schema but details what each entry includes, making it complete for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but description adds meaning: explains sort options (name/totalfilings), default, case-insensitivity, fallback; clarifies limit defaults and max; explains no page parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists companies with public tickers, sorted by name or total filings, for browsing or building a company picker. It distinguishes from sibling tool by directing to use GET /v1/companies/{ticker} for exact ticker search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (browsing/picker) and when not (searching by name/CIK), provides alternative endpoint, explains no page parameter and default sort behavior. 'Not plan-gated' adds clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only assert readOnlyHint=true and openWorldHint=true, so the description carries the behavioral burden — and it delivers: pagination (per_page default/max thrown in schema, but the description frames newest-first ordering), the semantics of an entry (accession number, amendment type, non-superseded transaction count), inclusive date-window behavior, alias precedence (per_page wins), and the plan-gating note. All of this is context annotations alone could not supply, and nothing contradicts the read-only/open-world hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the verb and primary use case in the first clause, then flows from result semantics to entry fields to alternatives to parameter trivia. Every sentence carries distinctive information — the only minor redundancy is that filters are mentioned twice (first and second sentence), but this is low-cost re-emphasis, not waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 fills the return-value gap by enumerating what every entry carries (accession number, ticker/name, period of report, filed date, amendment type, non-superseded transaction count). Pagination, ordering, filter behavior, alias semantics, and sibling routing are all covered; nothing an agent needs to call this read-only list tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the schema already documents every parameter with defaults (per_page=20, page=1, to=100), formats (YYYY-MM-DD), examples (CIK string with leading zeros), and alias precedence. The description adds value on top by grouping several params into a cohesive semantic idea: the filters ticker, CIK, and 'a from/to filed-date window', which is small but real framing benefit beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb-resource pair ('List Form 4 filings') and immediately scopes it: optional ticker/CIK/date filters, paginated, newest-first, with per-entry fields enumerated. It explicitly distinguishes itself from get_recent_filings and get_transactions by pointing at their unique behaviors (no page parameter vs. individual trades), so an agent can disambiguate without opening sibling schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit selection logic: 'Use this for a company's filing HISTORY', then names the alternatives with the condition that selects each — GET /v1/filings/recent for a live feed (explicitly noting it lacks a page parameter) and GET /v1/transactions when individual trades are needed. Also discloses that it is 'Not plan-gated', which is relevant access/cost context an agent can act on.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![form4api-mcp MCP server](https://glama.ai/mcp/servers/theodor90/form4api-mcp/badges/card.svg)](https://glama.ai/mcp/servers/theodor90/form4api-mcp)

Score Badge

Copy to your README.md:

[![form4api-mcp MCP server](https://glama.ai/mcp/servers/theodor90/form4api-mcp/badges/score.svg)](https://glama.ai/mcp/servers/theodor90/form4api-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/theodor90/form4api-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server