AIsa Equities

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

Adds substantial context beyond the readOnlyHint/openWorldHint/destructiveHint annotations: the call is free, it requires the Authorization header, and it discloses result semantics ('ok is true only when the balance was read; otherwise each entry of errors says what to do in next_step'). That tells an agent how to interpret partial failure, which annotations cannot convey.

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 what the agent gets, followed by cost/auth, then call triggers, then result interpretation. No sentence is redundant and none could be dropped without losing information.

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

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

For a zero-parameter read tool with an output schema already present, the description covers the remaining gaps: cost, auth requirement, invocation triggers, and the ok/errors/next_step contract. Nothing an agent needs to call or interpret it correctly is missing.

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

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

The tool takes zero parameters, so the description has nothing parameter-level to compensate for, and the schema is fully covered. A 4 rather than 5 reflects that it adds no input-syntax detail, though none is possible here.

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

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

The description states a concrete resource set (identity/key, account balance, Go-to-Market wallet, usage over 1/7/30 days) rather than restating the name. It is clearly distinguishable from every sibling, which are all Reddit, batch, or search tools. An agent knows exactly what it will learn by calling it.

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?

Explicit triggering conditions are given: 'Call it to verify a new connection or to explain a 402.' That is a strong when-to-use statement. It stops short of 5 because it names no alternative tool or a when-not condition, though the sibling list offers no obvious competing diagnostic.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is not required to restate it. It adds genuine operational context: the batch_use prohibition, exact-name/prefix requirements, and session reuse semantics. It does not cover failure handling when names are invalid, keeping it below a 5.

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

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

Front-loaded with the core action and size limit, and every sentence carries workflow value. The session_id sentence duplicates the schema's own parameter description, which is minor redundancy rather than bloat.

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 batch retrieval tool with an output schema, the description supplies the orchestration context an agent needs (source of names, next steps, session handling) without needing to explain return values. Nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema by constraining names to those returned by search and warning against a client prefix such as mcp__aisa__, which is not encoded in the schema.

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

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

States a specific verb and resource ('Retrieve schemas for 1 to 20 exact tool names') and pins the source of those names to search. This clearly separates it from siblings like search (finds tools), batch_quote, and batch_use.

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 sequences the workflow: build arguments from successful schemas, then call batch_quote, and 'Do not call batch_use yet.' This is an explicit when-to-use and when-not-to-use instruction naming the alternative siblings.

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

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

Goes well past the readOnly/idempotent annotations by explaining that quotes are price observations rather than authorization grants, and precisely delimiting what auto_execute_eligible does and does not waive (user prohibition, narrower scope, tighter budget). It also guarantees no execution fallback, which is the key behavioral risk for this tool.

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

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

Purpose is front-loaded and most sentences carry distinct rules (no fallback, eligibility limits, naming, session reuse). It is on the long side and the argument-shape constraint is stated twice in spirit, but little is truly wasted.

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?

An output schema exists, so return-value documentation isn't required, yet the description still flags the two response fields that matter for a downstream decision. Combined with session and naming guidance, an agent has everything needed to call it 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?

At 67% schema coverage the schema already documents each parameter, so the description earns credit only for added meaning: exact-name rules for 'tool', session_id reuse semantics, and the 1-to-20 argument-shape parallel with batch_use. It doesn't clarify search_id beyond what the schema states.

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

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

States a specific verb and resource ('Obtain AIsaServices cost quotes for 1 to 20 published tools') plus the crucial scope qualifier 'without executing them.' It is immediately distinguishable from the sibling batch_use, which executes rather than quotes.

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 names the parallel sibling ('Same input as batch_use') and draws the boundary ('Never falls back to execution'). It also gives operational conditions: use names exactly as search returns them, strip any mcp__aisa__ prefix, and reuse session_id from Search for the task.

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

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

Annotations already cover mutability, destructiveness, and open-world behavior. The description adds critical business logic: billable calls, quote dependency, the meaning of auto_execute_eligible (waives only cost confirmation, not user prohibitions), and no silent retry. It doesn't detail rate limits or return format, but with an output schema present, that's acceptable.

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 dense and front-loads the cost warning, but it packs many separate instructions into one block, making it less scannable. Some sentences like 'A missing or failed quote is not free' add value, but the overall flow could be better structured.

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 destructive, open-world annotations and the presence of an output schema, the description covers the essential preconditions and behavioral constraints. It could mention error handling or partial failure behavior, but the core guidance is sufficient for correct invocation.

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

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

Schema coverage is 67%, and the description adds important semantics: tool names must be exact without client prefix, session_id reuse guidance, and 1-20 call limit. It doesn't explain search_id, but the schema description for search_id is already clear enough.

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 and resource: 'Execute 1 to 20 independent published-tool calls', and the title matches. It distinguishes itself from batch_quote by requiring a quote first, but doesn't explicitly contrast with the singular 'use' sibling, though that's implied by 'batch'.

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

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

The description gives explicit when-to-use and when-not-to-use conditions: only after a successful batch_quote with auto_execute_eligible=true or explicit user authorization. It also states re-quote conditions and prohibits silent retries, leaving little ambiguity.

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 idempotentHint=true, but the description adds valuable behavioral context: it returns `total_filings` and `returned` so a filtered view cannot be mistaken for the whole day, it does not rank results, and it provides measured payload sizes (112 KB unfiltered, 73 KB with listed_only, ~10 KB with doc_type_code). These details go beyond generic annotations and inform the agent about response characteristics and data volume.

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 front-loaded with the core purpose and then elaborates with relevant details. It is longer than minimal, but every sentence earns its place: upstream comparison, field list, filtering behavior, size measurements, and return fields. The structure is logical, moving from general purpose to specifics. A slightly tighter wording could improve it, but it remains efficient.

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

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

The description is thorough for an agent to invoke correctly. It explains the filtering semantics, the return fields (`filings`, `total_filings`, `returned`), the relationship to the upstream tool, and the date format. Since an output schema exists, it need not detail return structure. Nothing critical is missing; the description covers all necessary operational details.

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 0% (no descriptions in the schema), so the description must fully explain parameters. It does: `date` is YYYY-MM-DD, `listed_only=true` keeps filings with a secCode (~two thirds of a day), and `doc_type_code` matches exactly with concrete examples (120, 140, 160, 350). This gives the agent complete semantic understanding of all three parameters, far exceeding what the schema provides.

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

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

The description states a specific verb and resource: 'One day of Japanese EDINET filings as a scannable list, with the filtering upstream lacks.' It clearly identifies the tool's function and differentiates it from the sibling `get_edinet_documents` by highlighting the filtering capability. The mention of six fields and the explicit contrast with the upstream tool leaves no ambiguity about what this tool does.

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 names the sibling `get_edinet_documents` and contrasts it: the upstream has no filter parameters and returns raw fourteen-field records, while this tool provides filtered six-field records. It also states 'It does NOT rank or select beyond your filters,' clarifying scope. However, it does not explicitly say 'use this when you need filtered results, use the upstream when you need full records,' leaving the decision slightly implicit.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the bar is lower. The description still adds real context the annotations do not: the required Subscription-Key authentication parameter, and the exact shape of the two response modes (metadata vs. metadata plus results). It stops short of describing rate limits or pagination for large filing lists.

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 raw API spec dump wrapped in 'methods'/'requestParams' JSON scaffolding rather than prose, so nothing is front-loaded for an agent. It also carries a pricing comment block that is noise for tool selection, and repeats parameter text already in the schema.

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

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

An output schema exists, so return values need not be explained, yet the description spends most of its budget on response fields. With only 2 parameters and full annotation coverage, the remaining gap is the missing sibling differentiation and when-to-use guidance, leaving it minimally viable rather than complete.

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

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

Schema description coverage is 100%, so the schema already documents both date and type verbatim, including the YYYY-MM-DD format and the 1/2 enum — the description largely restates it. The only genuinely additive item is the Subscription-Key parameter, which is absent from the input schema entirely.

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 embedded methodDesc states a specific verb and resource: 'Query the EDINET filing list for a given file date,' and the name get_edinet_documents matches that scope. It never distinguishes itself from adjacent siblings like edinet_filings_digest, get_financial_filings, or get_details, so an agent cannot route between them from this text alone.

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

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

Usage is only implied through the type parameter semantics ('1 for metadata only, 2 for metadata plus filing list'), which tells the agent how to choose a response mode. There is no statement of when this tool should be chosen over the filing-oriented siblings, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered by structured fields. The description's only added behavioral information is a per-request pricing disclosure ($0.02 USD per successful request, with settlement caveats) — genuinely beyond the annotations, but boilerplate that says nothing about return shape, data scope, or latency.

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 text is short but consists of HTML-comment-wrapped pricing boilerplate rather than tool documentation. It is under-specified rather than concise: every sentence is spent on billing metadata and none on the tool's function.

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 data-retrieval tool with three undocumented parameters, no output schema, and a dense field of similar financial siblings, the description supplies nothing an agent needs to invoke it correctly. The pricing banner does not substitute for purpose, parameter, or routing information.

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

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

Schema description coverage is 0% across three parameters (limit, period, ticker), none typed beyond 'string' and none described anywhere. The description must compensate and instead provides zero parameter meaning — no format for ticker, no accepted values for period, no units or default for limit.

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 never states what the tool does. The only content is an AISA pricing banner, so the agent must infer purpose entirely from the name 'get_financial_analyst_estimates' and the title 'Get Analyst Estimates'. Nothing distinguishes this from siblings like get_financial_earnings or get_financial_financial_metrics.

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

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

There is no when-to-use guidance, no prerequisites, and no routing to any of the 27 sibling tools. With many near-synonymous financial siblings, the absence of any selection criteria leaves the agent with no basis for choosing this tool over alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds the per-request cost context, which is genuinely useful, but says nothing about return format, caching, or the cik-vs-ticker preference — acceptable given the rich 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?

The single-sentence description is front-loaded and free of waste, and the pricing note is a clearly delimited injected block. Sizing is appropriate, though the minimal content borders on under-specification rather than tightness.

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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. However, for a two-optional-parameter lookup tool whose scope ('company facts') is undefined, the description leaves the caller without enough to choose between cik and ticker or to know what will be returned conceptually.

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

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

Schema description coverage is 100%, so both params are already documented; baseline 3 applies. The description's 'for a ticker' hints at ticker usage but does not clarify the more important ambiguity that both cik and ticker are optional (required: []), leaving the agent unsure which identifier to supply.

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

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

States a verb and resource ('Get company facts') but 'facts' is generic and undefined, and it makes no attempt to distinguish itself from close siblings like get_financial_financials, get_financial_filings, or get_financial_financial_metrics. An agent cannot tell from the text what data class 'facts' covers versus those tools.

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?

Only 'for a ticker' is offered; there is no when-to-use guidance, no prerequisite, and no mention of alternatives among the many financial siblings. The agent must infer selection criteria entirely on its own.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety and idempotency profile is covered without the description. The one extra bit — 'Optional change fields are returned only when available' — is a useful, non-obvious note about variable response shape, but that is the only behavioral disclosure.

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 authored content is two tight, front-loaded sentences with no padding. The injected pricing block is boilerplate noise that dilutes the definition, but the substantive description itself is efficiently sized.

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

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

With a full output schema and complete annotations, the missing piece is routing guidance among many overlapping financial siblings. Return values need not be explained, so the only real gap is when to pick this over get_financial_financials or get_financial_analyst_estimates.

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

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

Schema coverage is 100%, so the schema already fully documents ticker, limit, and cursor, including pagination and clamping behavior. The description adds nothing about parameters, which is acceptable at baseline when the schema carries the full load.

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

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

States a specific verb and resource — 'Get the most recent earnings snapshot for a ticker' — so an agent knows it retrieves current earnings data keyed by ticker. However, it does not define what an 'earnings snapshot' contains or distinguish this tool from closely-named siblings like get_financial_financial_metrics_snapshot, get_financial_analyst_estimates, or get_financial_financials_income_statements.

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?

No when-to-use guidance, no prerequisites, and no alternatives are named despite a crowded sibling set that overlaps heavily on financial fundamentals. The agent must infer selection from the name alone.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The only added behavioral content is the pricing note ($0.02 per successful request), which is genuinely useful cost context but is boilerplate rather than tool-specific behavior; nothing is said about coverage limits or what happens when all optional filters are omitted.

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

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

A single front-loaded sentence with no filler, and the pricing note is confined to a delimited block. It is terse to the point of under-specification, but nothing present is wasted.

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?

An output schema exists and the parameters are fully documented, so the description needn't explain returns. However, with zero required parameters and many overlapping siblings, the description should at least say how to scope a request or when this differs from get_financial_filings_items.

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

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

Schema description coverage is 100%, including pagination semantics for limit and the opaque cursor, so the schema does the heavy lifting. The description adds nothing beyond that, which is the baseline expectation.

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

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

States a specific verb and resource ('Get SEC filings for a company'), so the agent knows exactly what the tool returns. It does not distinguish itself from close siblings such as get_financial_filings_items or edinet_filings_digest, which is the only gap at this level.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives despite a large sibling set covering overlapping financial data. The agent must infer usage entirely from the name and schema.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds that output is raw, unparsed item text and discloses a per-request price, which is useful context; it says nothing about payload size or rate limits.

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

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

A single front-loaded sentence that states purpose immediately, followed only by a clearly delimited pricing block. Nothing in the prose is wasted, though the pricing boilerplate occupies more space than the functional description.

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?

An output schema exists, so return values need not be described. However, for a tool whose enum mixes 10-K and 8-K item codes and whose required fields shift by filing_type, the description omits the conditional-argument model entirely, leaving a real gap for an agent assembling a call.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description contributes no additional parameter meaning — it does not explain that the enum spans two different item numbering schemes (10-K Items 1–16 vs 8-K Items 1.01+) or which fields are conditionally required.

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

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

States a specific verb and resource ('Get the raw text Items from an SEC filing'), and the word 'raw text' signals it returns unparsed content rather than metadata. It does not explicitly contrast itself with the sibling get_financial_filings, leaving the item-level vs filing-level distinction to be inferred.

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

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

No guidance on when to use this over get_financial_filings or the other filing-related siblings, and no mention that item/quarter/accession_number must be matched to the filing_type. An agent gets no routing or prerequisite information from the description.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and open-world behavior, so the safety profile is covered externally. The description adds no further behavioral context: nothing about pagination mechanics, the UK-ticker limitation on price-based values, or how many records come back by default (the schema carries pagination, but the description does not reinforce it). The embedded pricing banner is commercial metadata rather than behavioral disclosure.

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 single descriptive sentence is front-loaded and efficient, with the metric families listed in a compact enumeration. The only bloat is the injected pricing comment block, which is boilerplate rather than substance.

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?

An output schema exists, so return structure need not be explained, and annotations cover the safety profile. What is missing is the disambiguation from the snapshot and general financials siblings and any note that periods drive the result shape, which matters for a 17-parameter tool in a dense sibling family.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including the CIK/ISIN/ticker lookup alternatives, pagination, and the LSE limitation. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

Specifies a concrete verb and resource ('Get financial metrics for a ticker') and enumerates the metric families returned (valuation, profitability, efficiency, liquidity, leverage, growth, per share), which tells an agent what data is inside. It does not, however, distinguish this tool from close siblings such as get_financial_financial_metrics_snapshot or get_financial_financials, so an agent cannot route between them from the description alone.

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

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

There is no when-to-use guidance, no statement of prerequisites (e.g., that ticker or cik must be supplied), and no mention of the snapshot variant that overlaps in name and purpose. The agent must infer applicability entirely from the name and schema.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds 'real-time' and a pricing note, which is modest extra context, but says nothing about freshness guarantees, rate limits, or which identifiers are required (it implies none, matching the empty required list).

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

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

The substantive sentence is front-loaded and dense with the metric categories. The interleaved pricing boilerplate is not the description author's content but does pad the block slightly.

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

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

With an output schema present, return values need not be explained, and annotations cover the safety profile. However, for a tool surrounded by many overlapping financial siblings, the absence of any disambiguation leaves the agent to infer selection from names alone.

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

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

Schema description coverage is 80%, so the schema already documents cik, isin, ticker, and exchange (including the UK limitation on price-based values). The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

The description names a specific verb ('Get') and resource ('real-time financial metrics snapshot') and enumerates the metric categories returned (valuation, profitability, efficiency, liquidity, leverage, growth, per-share), so the agent knows exactly what this produces. It does not distinguish itself from the near-identical sibling get_financial_financial_metrics, which is the main gap.

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

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

There is no statement of when to use this tool versus the very similar siblings (get_financial_financial_metrics, get_financial_financials, the snapshot variants). No prerequisites, no exclusions, no routing guidance of any kind.

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 read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds only the per-request pricing note, which is genuinely useful cost context, but says nothing about pagination depth or result volume beyond what the schema already documents.

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 core sentence is tight and front-loaded. The pricing block is relevant but wrapped in decorative HTML comment markers that add noise without content.

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

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

With an output schema and fully documented input schema, the return shape is handled elsewhere. What remains missing is the disambiguation that matters most for a 27-sibling toolset: whether this returns all three statement types, and the effect of `period` on that. Adequate but with a clear gap.

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

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

Schema description coverage is 100% across all 17 parameters, including enums, identifier alternatives, cursor opacity, and date-filter semantics, so the schema carries the full burden. The description adds no parameter meaning at all, making 3 the correct baseline.

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

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

States a specific verb and resource ('Get all financial statements for a ticker'), which reads as the aggregate counterpart to the sibling balance-sheet/income-statement/cash-flow tools. However it never explicitly says it returns all statement types combined, so the distinction from get_financial_financials_balance_sheets et al. must be inferred.

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

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

No when-to-use, when-not-to-use, or named alternative appears. Nothing tells the agent when to pick this aggregate tool over the three per-statement siblings, which is the key routing decision here.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered by structured data. The description adds no behavioral context of its own — no mention of pagination (up to 10 records per page, cursor carries original filters), no history depth, only a pricing note that does not help an agent decide or invoke.

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 single substantive sentence is well front-loaded and wastes nothing. But the embedded pricing comment block is boilerplate that adds no selection or invocation value and dilutes an otherwise one-line definition.

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

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

With an output schema present and 94% parameter coverage, the description needn't explain return values or field formats. The remaining shortfall is guidance on identifier selection and pagination, which is partially covered by the schema's own cursor and limit text.

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

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

Schema description coverage is 94%, so the parameters are already well documented in the schema, and the baseline of 3 applies. The description contributes nothing beyond 'for a ticker', which actually omits the cik/isin/exchange alternatives the schema spells out.

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

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

States a specific verb and resource ('Get balance sheets for a ticker'), which distinguishes it from the income-statement and cash-flow siblings by resource name. However, the description narrows the input to a ticker while the schema accepts cik, isin, market and exchange as alternative identifiers, so it under-describes the tool's actual access paths.

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?

No guidance on when to use this versus get_financial_financials, get_financial_financials_income_statements or the search/screener siblings. Nothing explains which identifier to prefer (ticker vs cik vs isin), how to choose period, or when pagination via cursor is needed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety and side-effect profile is fully covered. The description adds only a pricing note, which is billing context rather than invocation behavior; it does not describe return shape, pagination quirks, or data-source caveats. Minimum viable given the annotation coverage.

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 functional content is a single front-loaded sentence with zero waste. The injected pricing comment block is template overhead rather than description content, keeping it short of a 5.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The remaining gap is usage guidance for choosing among the sibling financials tools and identifier/period options, leaving the definition adequate but thin for a 17-parameter endpoint.

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

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

Schema description coverage is 100%, so every one of the 17 parameters is already documented in the schema (including identifier alternatives, cursor opacity, and filing-date semantics). The description adds no parameter meaning beyond that, which is the baseline 3 when the schema does the heavy lifting.

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

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

The description uses a specific verb and resource ("Get cash flow statements") and names the input ("for a ticker"), so the agent knows exactly what data is returned. It does not, however, distinguish this tool from close siblings like get_financial_financials_balance_sheets or get_financial_financials_income_statements, relying on the tool name alone for that differentiation.

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

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

There is no when-to-use guidance, no mention of when this is preferable to get_financial_financials (the general statements tool) or to the balance-sheet/income-statement variants. Nothing tells the agent which period mode (annual/quarterly/ttm) or identifier scheme to prefer in a given situation.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorld, so the safety profile is covered. The description's only added behavioral fact is the $0.02 per-request cost, which is genuinely useful for an agent deciding whether to call it, but nothing about pagination limits, auth requirements, or rate behavior is disclosed.

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 functional sentence is front-loaded and wastes no words. The embedded pricing block is boilerplate rather than tool-specific guidance, but it is short and clearly demarcated.

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?

An 18-parameter, zero-required query tool with an output schema needs at least a hint about identifier selection (ticker vs cik vs isin), pagination, and how it differs from the sibling statement endpoints. The description supplies none of that, leaving an agent to reconstruct intent from the schema alone.

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

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

Schema description coverage is 94%, so the schema already carries the parameter burden (limit/pagination semantics, cursor opacity, date-filter ranges, market/exchange enums). The description adds no syntax or usage detail for any of the 18 parameters and slightly narrows the identifier story to tickers.

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

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

States a specific verb and resource: "Get income statements for a ticker." That is enough to separate it from the balance-sheet and cash-flow siblings at the name level. However, the "for a ticker" framing is incomplete, since the schema shows cik and isin are first-class alternatives, and no explicit contrast with get_financial_financials or the other statement tools is offered.

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

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

There is no when-to-use guidance, no exclusions, and no mention of alternatives such as get_financial_financials (broad), balance sheets, or cash flow statements. An agent must infer selection purely from the tool name.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds useful pricing context ($0.02 per successful request), but does not disclose rate limits, authentication needs, or edge cases like what happens when no ticker is provided.

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 core description is a single efficient sentence, front-loading the purpose. The pricing block is boilerplate but standard, and does not detract significantly from conciseness.

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

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

With a rich output schema and detailed annotations, the description needs only to orient the agent. However, it implies that a ticker is required ('for a ticker') when the schema marks it optional, and it omits any mention of the many available filters (name, form type, dates), which could lead to underutilization or confusion.

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

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

Schema description coverage is 100%, so the schema fully documents all 11 parameters. The description adds no parameter-level meaning beyond what the schema already provides, making the baseline of 3 appropriate.

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

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

The description states a specific verb ('Get') and resource ('insider trades') and clarifies the scope ('for a ticker by a company insider'). It distinguishes from most siblings, though it doesn't explicitly differentiate from broader filings tools that might also contain insider information. Overall clear and direct.

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?

No guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It simply states what the tool does, leaving the agent to infer context from the schema and tool name.

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 establish that this is a read-only, idempotent, open-world, non-destructive query. The description adds valuable behavioral detail beyond annotations: page size (10 rows), ordering (newest first), rate-change timing, and the Federal Reserve midpoint convention. Pricing is also disclosed.

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 main content is front-loaded and concise: it describes the returned data shape and pagination first. The pricing notice is boilerplate but clearly separated. No sentence is wasted, though the description is not maximally tight.

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?

An output schema exists, so return-value details need not be exhaustive, and the description usefully supplements it with row frequency, ordering, and rate-change semantics. However, it omits guidance on when to prefer this tool over the snapshot sibling, leaving a meaningful usage gap for an agent choosing between the two.

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

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

Schema description coverage is 100%, so the schema already fully documents `bank`, `cursor`, `start_date`, and `end_date`. The description adds only that data is for one central bank, which is implied by the required `bank` parameter, but does not explain any parameter syntax 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 clearly identifies the resource: daily policy rates for one central bank, one row per calendar day, newest first. It does not explicitly name the sibling `get_financial_macro_interest_rates_snapshot` as the alternative for current data, but it is clear enough to distinguish from most other tools.

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?

No explicit when-to-use or when-not-to-use guidance is provided, and the sibling snapshot tool is not mentioned. The description implies a historical daily-rate query but leaves the agent to infer that this tool is for historical rates rather than a current snapshot.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds the row-level return shape and a pricing disclosure ($0.02 per successful request), but the return shape is largely redundant with the existing output schema, leaving the pricing note as the only substantive addition.

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

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

Two tight sentences with the core scope front-loaded ahead of the filter note. The injected pricing blockquote adds boilerplate length, but the substantive prose is efficient.

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

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

With an output schema present, return values need no explanation, and annotations carry the safety profile. The description covers resource, scope, and filter adequately; only the sibling-differentiation against the historical rates tool is left implicit.

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

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

Schema description coverage is 100% and the single bank parameter is fully documented in the schema, including example codes and a pointer to the banks endpoint. The description only restates the optional single-bank behavior, adding no syntax or format detail beyond the schema.

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

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

The description gives a specific resource (central bank policy rates) with an explicit scope qualifier: 'newest published' and 'one row per bank with the date it is in effect.' This implicitly separates it from the time-series sibling get_financial_macro_interest_rates, though it never names that sibling explicitly, so it stops short of a 5.

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

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

It states the filter behavior ('Pass bank to get one bank only'), which is clear usage for the optional parameter. However, it never says when to prefer this snapshot over the historical get_financial_macro_interest_rates tool, leaving the key routing decision to inference.

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

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

Annotations already declare the full safe-read profile (readOnly, idempotent, non-destructive, openWorld), so the safety bar is low. The description adds the dual-mode behavior, but says nothing about freshness/coverage window, rate limits, or result ordering; the pricing line is injected boilerplate rather than authored disclosure.

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

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

Two short sentences, capability first and operational detail second, with zero filler in the authored text. The second sentence partially restates the dual-mode idea from the first, a minor redundancy; the trailing pricing block is auto-injected and not the author's conciseness burden.

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?

An output schema exists and the input schema fully documents all three parameters including pagination semantics, so the description need not explain returns. It still omits any hint about how far back news goes or how results are ordered, a small gap for a news tool but not one that blocks correct invocation.

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

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

Schema description coverage is 100%, so the schema already carries the meaning of limit, cursor, and ticker (including "Omit for broad market news"), making 3 the correct baseline. The description's ticker guidance duplicates rather than extends the schema, adding no new syntax or constraint detail.

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

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

States a specific verb and resource ("Get recent news articles") and immediately clarifies the two operating modes: ticker-specific news vs. broad market news. No sibling among the get_financial_* tools overlaps with news retrieval, so the agent can route to it unambiguously from the name and first sentence.

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 tells the agent how to select between the two modes ("Pass a ticker for company-specific news, or omit the ticker for general market news"), which is the main decision point. It stops short of naming alternatives for adjacent questions (e.g., filings or earnings coverage), so no exclusions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, covering the safety profile. The description adds the useful EOD/historical granularity but says nothing about pagination via cursor, default interval behavior, or what happens when no ticker is supplied.

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

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

One front-loaded sentence stating the core purpose, plus a clearly delimited pricing block. Nothing is wasted, though the pricing boilerplate dominates the visible text relative to the useful content.

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

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

The tool has 6 parameters, zero required, and an output schema, yet the description gives no default semantics (default interval, behavior with no ticker, cursor pagination flow). An agent cannot tell from the description how to invoke it correctly with an empty argument set.

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

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

Schema description coverage is 83%, so the schema already documents cursor, ticker, dates, and interval, and the description adds nothing param-specific. Baseline 3 applies since the schema carries the load.

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

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

States a specific verb and resource ('Get end-of-day (EOD) historical price data for stocks'), which is clear. However, it never names or contrasts with the obvious sibling get_financial_prices_snapshot, leaving the historical-vs-snapshot distinction to inference.

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

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

No guidance on when to use this tool versus alternatives such as get_financial_prices_snapshot or batch_quote. The word 'historical' implies usage but no explicit context or exclusions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint, so the safety profile is covered. The description usefully adds that the data is real-time and lists the returned fields, but says nothing about pricing/auth behavior beyond the injected billing note or about latency/freshness guarantees.

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 core sentence is front-loaded, tight, and waste-free, leading with the operation and then the payload. The appended pricing block is injected boilerplate rather than authored content and mildly dilutes the signal.

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?

An output schema exists, so return values need not be explained, and the description redundantly summarizes them anyway. However, the schema marks 'ticker' as optional (required list is empty) while the description implies a stock must be named, and no guidance resolves that ambiguity.

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

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

Schema description coverage is 100% with a single well-documented 'ticker' parameter, so the baseline is 3. The description adds no format, exchange-suffix, or casing guidance beyond what the schema already states.

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

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

The description gives a specific verb and resource ('Get the real-time price snapshot for a stock') and enumerates the returned fields (current price, day change, day change percent). It implicitly distinguishes itself from the sibling get_financial_prices by emphasizing 'snapshot' and 'real-time', but does not name or contrast that sibling explicitly, so it falls short of a 5.

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

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

There is no statement of when to use this tool versus get_financial_prices, get_financial_financial_metrics_snapshot, or the batch_quote/batch_use siblings. The word 'snapshot' hints at a lighter/faster alternative but the agent must infer that from the name alone.

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

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

Annotations already establish that this is a safe, read-only, closed-world operation. The description adds useful context beyond annotations by saying it returns categories, servers, tool counts, and the dedicated endpoint, and that it is free. It omits auth/rate-limit details, but those are less critical given the read-only 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?

The description is front-loaded with what the tool returns and is generally efficient. The parenthetical about tool-router and the endpoint URL add some density, but each part contributes usage or content context.

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

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

With zero parameters, read-only annotations, and an output schema available, the description supplies enough context for correct invocation. It explains the catalogue contents and gives the category-specific endpoint alternative, leaving no critical gap for an agent.

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

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

The tool has zero parameters, so parameter semantics are not a meaningful differentiator. The schema has no properties to explain, and the description does not need to document any inputs.

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

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

The description clearly states that this tool gives a catalogue overview: categories, servers per category, tool counts, and a dedicated endpoint. The resource is specific and recognizable, though sibling differentiation is only partial because it references 'tool-router' rather than the listed siblings like search/use.

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

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

It gives a clear alternative: use the category-specific endpoint if you only need one category, rather than going via search. It also notes the tool is free and AIsa-only, but it does not explicitly state when to call list_categories instead of search or use.

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

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

The description presents a read-only retrieval operation ('Search for specific financial metrics'), while the annotations declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false. The read verb and the destructive/write annotation are opposite claims about the tool's side effects, and the description adds no context (auth needs, cost beyond the pricing note, side effects) to reconcile them.

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 substantive sentence is front-loaded and wastes no words. The trailing aisa-pricing block is injected boilerplate that does not help tool selection, but it is clearly delimited and does not obscure the purpose statement.

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?

An output schema exists, so return values need not be explained, and the nested body schema documents the individual fields. What is missing is the behavioral picture: the annotations imply a destructive/non-idempotent operation that the search framing never addresses, and there is no guidance on valid line-item identifiers or result limits for a nested-object search tool.

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

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

Top-level schema description coverage is 0% (the single 'body' parameter is undocumented), so the description must carry weight. It partially does: 'list of tickers' maps to tickers and 'specific financial metrics' maps to line_items, and the statement list maps to the domain. It says nothing about period (annual/quarterly/ttm) or limit, and gives no syntax for valid line-item names.

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

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

The description gives a specific verb ('Search') plus the resource ('specific financial metrics') and the statement scope (income statements, balance sheets, cash flow statements) and the input axis ('a list of tickers'). This is enough to separate it from the single-statement siblings like get_financial_financials_income_statements. It stops short of naming its closest sibling, post_financial_financials_search_screener, so it is not a 5.

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

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

There is no when-to-use or when-not-to-use guidance, no prerequisites, and no alternatives named. The phrase 'for a list of tickers' hints at a multi-ticker use case but does not tell an agent when to pick this over post_financial_financials_search_screener or get_financial_financials.

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

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

The description reads as a non-mutating query ('Search for stocks by filtering'), yet annotations declare readOnlyHint=false and destructiveHint=true. This is a direct conflict between the described behavior and the declared safety profile, matching the contradiction pattern. The description also omits rate/limit behavior and auth/pricing context beyond boilerplate.

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 core sentence is short, front-loaded, and waste-free, with the key scope stated immediately. The appended pricing boilerplate adds noise but is platform-injected rather than authored content.

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?

An output schema exists so return values need not be explained, but for a screener with a nested, filter-driven body the description supplies no usage guidance, no sibling routing, and no clarification of the annotation conflict. An agent cannot confidently select or invoke it from the description alone.

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?

Top-level schema coverage is 0% (the sole 'body' param is undocumented), so the description is expected to compensate but does not. It never explains the filters array, the operator model (gt/lt/gte/lte/eq vs 'in' for ticker/cik), or the limit parameter, adding only the field domain.

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

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

States a specific verb ('Search') and resource ('stocks') and scopes the field domain (income statements, balance sheets, cash flow statements). It is clear but does not distinguish itself from the near-identical sibling 'post_financial_financials_search_line_items' or the 'get_financial_financials_*' endpoints.

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?

No when-to-use guidance, no prerequisites, and no named alternatives despite a crowded sibling set (search_line_items, get_financial_financial_metrics, get_financial_financials). The agent must infer routing entirely on its own.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds workflow behavior the annotations cannot: the has_full_schema flag gates a required batch_get_schema call, and the next step after search is batch_quote, not batch_use. It stops short of disclosing retrieval limits or catalog breadth that would push it to a 5.

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

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

It is a dense run of imperatives rather than flowing prose, but each sentence carries a distinct rule (scope, language, workflow branch, negative cases, result interpretation) and the most important scoping guidance is front-loaded. Slightly more compression would help.

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

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

With an output schema present, the description need not explain return values, and it correctly avoids doing so while still referencing the output fields that drive the workflow (has_full_schema, next_steps_guidance). A mutation-free, well-annotated search tool is adequately covered, though catalog scope ('AIsa-only', no external providers) could be stated more explicitly.

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

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

Schema coverage is 100%, so the structured baseline is 3. The description adds genuine meaning beyond the schema by telling the agent to write the query in English and to place tickers, URLs, providers, or identifiers in known_fields, which is non-obvious routing guidance for a nested free-form object.

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 opens with a specific verb+resource: 'Discover AIsa tools and Plans for external data or actions.' It also separates this discovery step from the sibling execution tools by naming batch_get_schema, batch_quote, and batch_use and stating when each follows, so an agent can place it in the workflow without opening schemas.

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

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

It gives explicit when-to-use ('tasks needing external data or actions'), when-not ('tasks that only need supplied content or general knowledge'; no standalone rewriting, translation, summarization, formatting, or calculations), and named alternatives (batch_get_schema when has_full_schema=false, batch_quote rather than batch_use). It also specifies query language and atomic-query style, leaving little to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the agent knows this is a state-changing, open-world operation. The description adds only the deprecation status and says nothing about what gets mutated, spend behavior (despite a max_price_usd param), or authorization needs.

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

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

A single clause with zero waste; the deprecation notice and the replacement are front-loaded. It is terse by design for a deprecated endpoint, though it is under-specified rather than optimally efficient.

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?

Has an output schema and annotations, which reduces the burden, but a 4-parameter operation tool with a deprecation notice gives no information about what it executes or whether it remains functional. For an agent deciding between this and batch_use, the description is thin.

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

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

Schema description coverage is 100%, so all four parameters (operation_id, arguments, search_id, max_price_usd) are already documented in the schema. The description adds no parameter meaning on top, so the baseline 3 applies.

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

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

The description never states what the tool does — no verb or resource. It only labels the tool as deprecated and points to a replacement, leaving the actual capability ('Run an AIsa operation' from the title) unexplained. An agent must infer the purpose from the title and schema alone.

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

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

It explicitly routes the agent to the alternative ('use batch_use instead'), which is exactly the guidance needed for a deprecated tool. It doesn't explain when, if ever, this tool should still be called (e.g., during a migration window), 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.