AlphaCreek SEC Filings MCP

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

Adds context beyond annotations: resolution of latest filing when artifact_document_id omitted, and page number mapping for FCA. Does not contradict readOnlyHint=true. Could mention response structure or limits.

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

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

Three sentences, front-loaded with main purpose. No redundant or filler content. Efficiently conveys key information.

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

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

Covers main usage, parameter interactions, and special cases. With no output schema, could describe return format or pagination, but overall sufficient for the tool's complexity.

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

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

Schema coverage is 40% (2 of 5 parameters described in schema). Description adds meaning for artifact_document_id, document_type, and filing_registry, but omits ticker and company. Partially compensates but not fully.

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

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

The description clearly states the verb 'Return' and the resource 'full filing table of contents'. It distinguishes from siblings like list_filings and read_node_content by focusing on the table of contents retrieval.

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

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

Explicitly advises to use list_filings first for discovery, explains behavior when artifact_document_id is omitted, and provides special instructions for FCA filings with filing_registry and node IDs.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds minimal behavioral context beyond that (it does not mention performance, error behavior, or data freshness).

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

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

The description is a single, clear sentence that is front-loaded with the action. It is appropriately concise but could be slightly expanded to cover parameter usage without becoming verbose.

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

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

Given the tool has 4 parameters, no output schema, and only 50% schema description coverage, the description is insufficient. It does not explain what 'metadata' includes, how to use ticker versus company, or behavior when no filing is found. The agent may struggle to use the tool correctly.

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

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

Schema coverage is 50% (only document_type and filing_registry have descriptions in schema). The description mentions 'company or ticker' but does not clarify the relationship between the two parameters (e.g., required, mutually exclusive, or both optional). It adds no semantic value beyond the schema.

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

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

The description uses a specific verb ('Return') and clearly identifies the resource ('latest filing metadata') and target ('a company or ticker'). It distinguishes from sibling tools like list_filings (which returns multiple filings) and get_filing_toc (which returns table of contents).

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

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

The description implies usage for retrieving the most recent filing but does not explicitly state when to use this tool over alternatives like list_filings or read_node_content. No guidance on prerequisites or context is provided.

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

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

Annotations already indicate readOnlyHint=true. Description adds behavioral details like sorting order ('newest first') and output fields ('artifact_document_id and dates'), providing useful context 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.

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

Two concise sentences front-load purpose and usage guidance, with no redundant or extraneous information.

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

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

Given 5 parameters, no output schema, and moderate complexity, the description covers the main listing behavior, ordering, and a registry use case. It hints at return fields but lacks details on pagination or parameter optionality, leaving minor gaps.

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

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

Schema coverage is 40% (only document_type and filing_registry described). Description adds minimal parameter context (e.g., 'Use filing_registry=fca_nsm'), but does not fully compensate for missing descriptions of ticker, company, or limit. Baseline 3 is appropriate.

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

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

The description explicitly states 'List available filings for a ticker (newest first) with artifact_document_id and dates', using a specific verb and resource, and distinguishes from siblings that retrieve specific filing content rather than listing.

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

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

Provides clear guidance: 'Use filing_registry=fca_nsm for UK FCA annual reports' and 'Use this first when you need a specific reporting period', implicitly directing to other tools for later steps.

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

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

Annotations already declare readOnlyHint=true. Description adds output format details and instructions on granular child nodes, enriching behavioral understanding.

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

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

Front-loaded with purpose, then explains parameters and output. Every sentence adds value, though could be slightly more concise.

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

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

For a read-only tool with annotations and no output schema, the description explains usage, output format, and citation guidance well. Minor gap: artifact_document_id meaning is implied.

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

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

Schema covers 67% of parameters. Description adds meaning for node_id/node_ids by linking to TOC, but artifact_document_id remains undescribed. Baseline 3 with partial compensation.

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

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

Clearly states verb 'return content' and resource 'navigation nodes in a filing'. Distinguishes from sibling tools like get_filing_toc which returns TOC, not node content.

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

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

Provides source of node ids (TOC lines) and explains how to pass nodes. Lacks explicit when-to-use vs. alternatives, but gives enough context for typical use.

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