Calera FINSEC — Certified SEC Memory

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

Annotations already declare readOnlyHint=true and title, so the description adds value by stating 'Deterministic mathematical execution with zero language model confabulation,' which reassures the agent of no hallucination risk. This goes beyond the bare annotations, but could further detail edge cases (e.g., handling of missing periods or negative values).

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 two concise sentences, front-loaded with the core purpose and followed by a key behavioral guarantee. Every sentence earns its place without redundancy.

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

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

Given the output schema exists and parameters are fully described in the schema, the description covers the essential context for a deterministic computation tool. It lacks mention of error handling or period validation, but for a well-typed tool with an output schema, this is nearly 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?

With 100% schema description coverage, the description does not need to elaborate on parameters. However, it provides no parameter-specific details beyond the schema, such as clarifying that 'company' expects ticker or name consistently, or that 'low_tokens' only affects output, not behavior. Baseline 3 is appropriate as 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 specific language: 'Exact compound annual growth rate (CAGR) calculation over verified SEC filing facts,' clearly indicating a resource (SEC filings) and verb (compute). It distinguishes itself from siblings by mentioning deterministic execution and zero confabulation, which contrasts with potential LLM-based tools like query_financial_sec.

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 accurate CAGR calculations but does not explicitly state when to use it over siblings like lattice_arith_evaluate or query_sec_metric_exact. Alternatives are not named, and no when-not-to-use guidance is provided, leaving the agent to infer context.

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

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

The annotations already declare readOnlyHint=true, so the agent knows this is a read-only computation. The description adds that the solver is 'deterministic' and 'zero-error' and operates over 'verified' metrics, which provides modest extra context beyond the annotation. However, it does not disclose authentication needs, rate limits, or data sourcing details.

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 sentence that efficiently conveys the core purpose. It front-loads 'Deterministic zero-error algebraic solver' and lists operations. It is concise, though it could be slightly more structured for readability.

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 8 parameters (1 required, 7 optional dependent on the operation) and an output schema, the description is too sparse. It does not explain that the 'metric', 'company', 'periods', etc. parameters are conditional on the chosen 'op'. The output schema exists, so return values are covered, but operational context 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 lists the operation names in parentheses but does not add any meaning beyond what the schema already provides for each parameter. No parameter-specific semantics are introduced.

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 tool performs arithmetic operations (cagr, ratio, multiply, divide, yoy_series, product_chain) over verified SEC EDGAR financial metrics. It uses a specific verb ('algebraic solver') and resource, but does not explicitly differentiate from sibling tools like compute_sec_cagr.

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 provides no guidance on when to use this tool versus its siblings (e.g., compute_sec_cagr, query_financial_sec). It does not mention prerequisites, contextual triggers, or when not to use it.

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

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

The annotation already declares readOnlyHint=true, so the tool is safe for reads. The description goes further: it discloses that the tool does not invent numbers, that it returns SAFE_REFUSAL instead of hallucinating, and that monetary answers use the filer's default currency unless FX conversion is requested. This fully documents the honest-failure behavior and currency default, which is critical guidance beyond the annotation.

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 highly efficient: three sentences, each with a distinct purpose. No fluff. It front-loads the core purpose, then adds the critical SAFE_REFUSAL nuance, then the currency defaults. Every sentence earns its place, and the total length is appropriate for the complexity (4 parameters, nuanced behavior).

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 presence of an output schema (so return structure is documented), 4 parameters fully described, and strong annotations, the description covers everything an agent needs: purpose, refusal behavior, currency handling, and parameter semantics. There's no missing guidance for the complexity level.

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 description adds meaning: it explains the 'query' field should be natural language, optionally with 'in USD', and clarifies that 'target_currency' uses audited annual-average rates with provenance. The 'usd_only' boolean is also contextualized as forcing USD conversion. The description adds value by tying parameters to real-world behavior (FX conversion, provenance tracking) that the schema alone doesn't capture.

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 it queries Certified SEC facts, returns verified values with provenance or SAFE_REFUSAL, and explains how to handle that response (success-of-honesty). It is distinct from siblings like 'query_sec_metric_exact' or 'compute_sec_cagr' by emphasizing verified/provenance data and honest refusal.

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 explicitly tells the agent when to use this tool (for certified, provenance-backed answers) and provides corrective guidance: treating SAFE_REFUSAL as a success-of-honesty not a tool failure, and how to request FX conversion via parameters or natural language hints. This helps avoid confusion with sibling tools that might invent or compute values.

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 annotation already declares readOnlyHint=true, so the agent knows this is a safe read operation. The description adds valuably beyond that by revealing 'Server-side verified fact with provenance' (meaning results are authoritative and cite sources) and 'SAFE_REFUSAL when missing' (meaning the tool will explicitly decline rather than hallucinate), which is critical behavioral context for a retrieval tool. It also states 'No LLM math,' warning against the tool being used for computation. The only gap is not explaining the format or pagination of the response, but the output schema likely covers that.

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 sentence plus two short phrases: 'Exact EDGAR metric recall for company+metric+period. Server-side verified fact with provenance; SAFE_REFUSAL when missing. No LLM math.' Every part earns its place—purpose, data source/quality, error handling, and behavioral constraint. It is front-loaded and dense with useful 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 the tool's complexity (4 parameters, 3 required), the presence of an output schema to explain return values, and the annotation readOnlyHint=true, the description is complete. It covers the core purpose, the data's verified nature, refusal behavior, and a key limitation (no math). There are no apparent gaps for an agent to make a mistake in invoking this 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?

The input schema has 100% description coverage, with clear descriptions for all four parameters. The description does not add additional meaning beyond the schema descriptions themselves, but it does tie them together contextually by stating the inputs are 'company+metric+period' and noting the optional 'low_tokens' parameter (though not explicitly named). Since schema coverage is complete, a baseline score of 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 clearly states the tool's purpose: 'Exact EDGAR metric recall for company+metric+period.' It specifies a verb ('recall'), a resource ('EDGAR metric'), and the required inputs (company, metric, period). This distinguishes it from siblings like 'compute_sec_cagr' (which uses arithmetic) and 'query_sec_sector_peers' (which targets peers).

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 explicitly notes 'Server-side verified fact with provenance; SAFE_REFUSAL when missing. No LLM math.' This tells the agent when the tool will return a verifiable result versus refuse (SAFE_REFUSAL), and that it should not be used for mathematical derivations or guessing. It lacks explicit guidance on when to prefer alternatives like 'compute_sec_cagr' for growth rates or 'query_financial_sec' for broader searches, but the sibling names and the 'No LLM math' hint provide adequate contextual clues.

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 provide readOnlyHint=true, so the description adds value by disclosing that results are 'certified' and 'dynamically derived from SEC filing SIC codes and 10-K business segment disclosures.' This explains the data source and derivation logic beyond what annotations cover, without contradicting them.

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

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

Two sentences: the first covers what the tool does and its derivation, the second gives usage context. No redundancy, front-loaded with core purpose. Every sentence earns its place.

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

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

The description explains the peer group derivation and primary use case, which complements the existing output schema and readOnlyHint annotation. It does not cover error scenarios or details about limit/period parameters, but the schema fills those gaps. Overall adequate for a dynamic screening tool with rich structured data.

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 baseline is 3. The description indirectly relates sector_or_industry and metrics parameters ('SIC codes', 'XBRL metrics') but does not add any new syntax, format, or behavioral details beyond the schema descriptions. No extra value is provided for the remaining parameters.

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

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

The description clearly states the tool returns 'certified SEC EDGAR XBRL metrics across an industry peer group' and specifies the dynamic derivation method using SIC codes and 10-K disclosures. This distinguishes it from siblings like query_sec_metric_exact (which likely targets single companies) and query_financial_sec (a broader name).

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 explicitly advises 'Use this for sector screening or when no specific company ticker is provided.' This gives a clear when-to-use condition and implies an alternative scenario (having a ticker). It does not name specific sibling tools, but the guidance is sufficient and not misleading.

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 'readOnlyHint' annotation already tells the agent this is a read-only operation, so the description doesn't need to restate that. The description adds useful context about the scope (SEC data, not market data) and the 12-pack structure. No contradictions with annotations are present.

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 two concise sentences with no fluff. The first sentence establishes the core value (certified packs, with an example), and the second sentence clarifies exclusions. Every word earns its place.

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

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

The tool has 4 parameters (all described in schema), an output schema, and strong annotations. The description adequately covers the domain and exclusions. It doesn't explain the return format, but that's covered by the output schema. Minor gap: it doesn't clarify that 'period' is optional, but the schema does.

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%, and all parameters are described clearly in the schema. The description doesn't add new meaning beyond stating the packs are 'certified' and listing 'dcf_valuation_inputs historical FCF' as an example. Baseline 3 is appropriate since the schema already 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 clearly states the tool retrieves certified SEC/EDGAR valuation input packs and explicitly lists 12 packs including 'dcf_valuation_inputs historical FCF'. It distinguishes itself from siblings by specifying what it does NOT provide ('Not market EV, P/E...'), helping an agent differentiate it from nearby tools like 'query_sec_metric_exact' or 'lattice_arith_evaluate'.

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 tells the agent when to use this tool—for certified SEC valuation packs—and crucially, what not to use it for (market EV, P/E, trading DCF, macro gauges). This is strong guidance. However, it doesn't mention alternatives explicitly (e.g., 'use query_sec_metric_exact for single metrics'), so it falls just short of a 5.

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

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

The description adds that the overview is 'complete' and 'structured', and lists the domains covered. However, it does not disclose behavioral traits such as caching behavior, authentication requirements, or response size. Since annotations already provide readOnlyHint=true, the bar is lower, and the description provides adequate addition without contradiction.

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, front-loaded sentence that efficiently conveys the tool's purpose without wasted words. It starts with the action verb 'Returns' and lists the key content areas, making it easy to parse.

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's complexity (returning a structured overview of multiple domains), the description is reasonably complete. It lists the covered areas and the existence of an output schema covers return structure. However, it does not address how the 'low_tokens' parameter modifies the response, which is a minor 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%, with the single optional boolean parameter 'low_tokens' having its own schema definition. The description does not mention this parameter or explain how it affects the output. Therefore, it adds no additional meaning beyond the schema, resulting in the baseline score of 3.

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 tool returns a 'complete structured overview' of certified EDGAR valuation packs, deterministic financial arithmetic operations, SEC calculations, and product scope boundaries. This specific verb+resource breakdown distinguishes it from sibling tools like compute_sec_cagr or query_financial_sec, which are focused on specific computations or queries.

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 provides no guidance on when to use this tool versus its siblings. It does not suggest using it for discovery before calling specific tools, nor does it mention any prerequisites or exclusions. The usage context is only implied by the tool's role as an overview, but this is not explicitly stated.

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