FinFam Financial Calculators

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds the dependency on get_view_signature for input types, which is a behavioral nuance stagn. However, it does not explain output format or any side effects, but annotations cover safety. Meets baseline for annotation-covered traits.

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 stated up front, followed by a brief instruction list. No fluff; each sentence provides value. Slightly longer than necessary due to examples, but still efficient. No redundancy.

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

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

For a 3-param tool with nested inputs and no output schema, the description covers input usage well but fails to describe the return value or outcome of the calculation. It references get_view_signature for types, which helps, but there is no mention of what the tool returns (e.g., calculated result, errors). This is a notable gap given no output schema exists.

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% and the schema has no descriptions. The description thoroughly explains the inputs parameter structure, including the dict format and type mappings (numbers, decimals, integers, booleans) referencing get_view_signature. This compensates for the lack of schema descriptions and adds meaningful guidance.

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 action ('Run a financial calculation') and the resource (a view with inputs). It distinguishes itself from sibling tools like get_view_signature or search_views by focusing on executing the calculation. No ambiguity.

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

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

Provides explicit instructions on how to structure the inputs dict accruing to field types, and references get_view_signature for type conventions. It gives clear context for usage but does not explicitly state when to use versus alternatives or exclusions. Lacks an explicit 'when not to 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it returns null when nothing is published yet, which is useful behavioral context beyond the annotations. It also details the return structure (headline, mood, permalink, sources, story cards), which is helpful.

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 well-structured with a clear first sentence, then usage guidance, return details, and parameter explanation. It is concise and front-loaded with the core purpose, with no wasted words.

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 simplicity (one optional parameter, no nested objects), the description covers purpose, usage, return values, and edge case (null). The output schema exists, so return details are reinforced. The description is complete for an agent to select and invoke 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?

The schema has only one parameter with a default, and the description explains the two allowed values ('today' and 'week') and their meanings. Since schema coverage is 0%, the description fully compensates by defining the parameter semantics clearly.

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 the current FinFam Pulse, a twice-daily money-news digest, and explicitly contrasts it with answering from memory. It distinguishes from siblings like search_pulse by focusing on the current digest rather than searching historical ones.

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 says to use this for 'what's happening in finance / markets / the economy right now' questions instead of answering from memory, and it mentions the period argument for today vs week. It also instructs to cite the permalink and story URLs, providing clear usage guidance.

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 states it 'returns field names, types, defaults, and hints,' which directly describes the output. While the annotations already indicate read-only, idempotent, and non-destructive behavior, the description adds context about the type of information retrieved without contradicting the annotations. It does not mention side effects, but given the 'get' nature, it is sufficiently transparent.

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 concise, consisting of two clear sentences plus brief parameter explanations. It avoids unnecessary fluff and directly conveys the essential information about the tool's purpose and usage. The structure is logical and 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 has a simple schema (two string parameters) and no output schema, the description provides sufficient context: it explains what the tool does, what the parameters mean, and the kind of output expected. It does not elaborate on error handling or edge cases, but for a signature retrieval tool, this is acceptable. The description is complete enough to guide an agent effectively.

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 Args section provides meaningful descriptions for both parameters, explaining that 'owner_username' is the view owner's username (from search results) and 'viewname' is the view's URL slug (from search results). This adds valuable context beyond the schema's basic type information, clarifying the source and purpose of each parameter.

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: retrieving the full input contract for a financial calculator, including field names, types, defaults, and hints. It distinguishes itself from sibling tools like calculate_view (execution), get_view_source (source retrieval), and search_pulse/search_views (search) by emphasizing it provides the necessary input specification before running a calculation.

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 mentions using this tool 'before running a calculation,' indicating the appropriate timing. It also instructs that the arguments come 'from search results,' providing clear guidance on how to obtain the required parameters. This contextualizes usage well and distinguishes it from other tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds useful context by specifying the return format (readable TSV with fields, types, defaults, formulas) and the open-source availability constraint, going beyond what annotations provide.

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 reasonably concise and well-structured, with a clear opening sentence, a usage constraint, return format, and an Args section. It avoids unnecessary fluff, though the Args block could be slightly tighter.

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 simple read-only tool with two parameters and no output schema, the description covers the key aspects: what it does, availability constraints, return format, and parameter meanings. It does not explain error behavior or what happens when a view is not open-source, but this is not critical for the tool's basic use.

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 no parameter descriptions (0% coverage), so the description must compensate. It provides brief definitions for both parameters, including the useful detail that viewname is the URL slug. However, the explanations are minimal and mostly restate the parameter 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 clearly states the tool retrieves source code/formulas for an open-source financial calculator, using a specific verb and resource. It does not explicitly differentiate from siblings like get_view_signature or calculate_view, but the function is distinct enough that purpose is unambiguous.

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

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

The description provides a clear prerequisite: it is only available for views published as open-source. However, it does not explicitly state when to prefer this tool over alternatives such as calculate_view or get_view_signature, so usage guidance is implied rather than fully explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description doesn't need to repeat safety. The description adds behavioral context: it returns one dated edition per query match and explains the result structure (headline, paragraph, permalink, sources, story cards). It also transparently states that the search is not just on the headline but on prose and cards, which is beyond the annotations. No contradictions.

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

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

The description is concise and efficient. It includes a concrete example of queries ('Fed', 'mortgage rates', 'layoffs') and describes parameters in a straightforward list. No fluff, each sentence contributes to understanding what the tool does and how to use it.

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 a moderate complexity (4 parameters, output schema exists). The description is complete: explains result structure, ordering, provides examples, lists category values, and gives defaults/maxima for parameters. Output schema covers return values, so the description doesn't need to. Combined with annotations, this is highly 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?

The description adds semantic meaning beyond the schema. For 'query' it explains what to match: 'Topic or keywords to match'. For 'days' and 'limit' it details defaults and max bounds. For 'category' it lists all possible values (markets, rates, housing, etc.) and explains it filters card category. Although the schema has 0% coverage, the description fully compensates by explaining each parameter's purpose and valid values.

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: 'Search past FinFam Pulse editions by topic' and explicitly lists the resource (FinFam Pulse editions) and the action (search). It distinguishes itself from siblings like get_pulse (which likely retrieves a single edition) and search_views (which searches views) by specifying it searches editions' prose and story cards.

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 provides usage context: it matches both prose and story cards, and each result includes a headline, paragraph, permalink, sources, and matched story cards. It also explains result ordering ('Best match first, newest as the tiebreak'). It differentiates from siblings by noting it's the tool for searching fictional editions (e.g., 'Fed', 'mortgage rates') rather than views.

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, indicating safe read-only behavior. Description is consistent and adds a natural language example but no additional behavioral details like result shape or performance implications. Acceptable but minimal beyond annotations.

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

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

Extremely concise – two bullet-style args with clear inline examples. No fluff, every sentence provides value. Properly front-loaded with one-sentence purpose.

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 search tool with only 2 params and an output schema (present but not shown), the description is matching. It covers query use case and limits. Slightly weak in not mentioning what a 'view' is or handling pagination, but acceptable given simplicity and annotations.

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 has no per-parameter descriptions, so description fully compensates by defining 'query' as natural language with example and 'limit' with default and max. Adds meaningful semantics beyond the bare parameter 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?

Description clearly states 'Search for financial calculators matching a question or topic' – specific verb+resource+scope. It distinguishes 'views' from sibling 'search_pulse' by explicitly naming financial calculators.

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

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

Provides contextual example for query and default/max limit, but does not explicitly say 'use this instead of search_pulse' or describe when alternatives are better. Usage is implied, not contrasted with siblings.

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