treasury-fiscaldata-mcp-server

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral details beyond annotations: it describes the output structure (source tool, query parameters, timestamps, row count, column schema) and the list of source tools that materialize dataframes.

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 consists of two succinct sentences. The first states the core function and output details; the second provides usage guidance and a prerequisite. No superfluous 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 is simple (list dataframes), and an output schema exists, the description covers all necessary context: what it lists, why to use it (before treasury_dataframe_query), and a configuration requirement. No gaps remain.

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% with a single optional parameter 'name'. The description adds the semantic nuance that omitting the parameter lists all active dataframes, while providing it filters to a specific table. This adds some meaning beyond the schema, but the schema already describes the parameter well.

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 specifies the tool lists DataCanvas dataframes materialized by four specific treasury tools. It distinguishes from sibling 'treasury_dataframe_query' by stating it should be used before that tool to discover table names and column types.

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 states usage context: 'Use this tool before treasury_dataframe_query to discover table names and column types.' Also provides a prerequisite: 'Requires CANVAS_PROVIDER_TYPE=duckdb.' While it does not enumerate when not to use it, the guidance is clear and actionable.

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?

Beyond annotations (readOnlyHint, idempotentHint), the description details rejected operations (DDL, DROP, etc.) and that all columns are VARCHAR, which is critical for querying. No contradiction with annotations.

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

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

Single paragraph that front-loads the core action, then restrictions, then CAST caveat. Efficient but could be slightly more structured with bullet points for clarity.

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 complexity (4 params, output schema exists), the description is fully complete: explains data type peculiarities, restrictions, and suggests using a sibling tool first. No missing behavioral 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 100% with detailed descriptions, so baseline is 3. The tool description adds extra context like default row_limit and register_as format, but no schema-level gaps exist.

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 'Run a single-statement SELECT against DataCanvas dataframes' and lists which sibling tools register the dataframes, distinguishing it from those and from treasury_dataframe_describe which lists tables.

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 says to use treasury_dataframe_describe before querying to get table names. Provides an example SQL query with CAST hints. Lacks explicit 'when not to use' but the read-only restrictions implicitly guide usage.

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 and idempotent behavior. The description adds valuable context: the API only records debt on business days, records go back to 1993-01-04, and series results beyond 500 rows are spilled to DataCanvas. No contradictions with annotations.

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

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

The description is well-structured and informative, covering modes, constraints, and integration points. It is not overly long, though it could be slightly more concise. Every sentence adds value, and key details are front-loaded.

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

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

Given 5 parameters with high schema coverage, annotations, and an output schema, the description covers all necessary aspects: modes, business day constraint, historical depth, series handling, and DataCanvas integration. No missing context for agent 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 100%, so the schema already documents parameters well. The description adds some context (e.g., business day requirement for date, start_date history) but does not significantly enhance understanding beyond the schema descriptions. Baseline 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: fetching national debt data broken into publicly-held and intragovernmental holdings. It specifies three distinct modes (latest, date, series) and distinguishes from sibling tools like treasury_get_exchange_rates and treasury_get_interest_rates by focusing on debt.

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 clear guidance on when to use each mode: 'latest' for most recent, 'date' for a specific business day, 'series' for a date range with optional DataCanvas integration. It explains constraints like business days and the 500-row spill threshold. However, it does not explicitly state when not to use the tool or provide direct comparisons to 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?

Annotations already declare readOnlyHint and idempotentHint. The description adds that rates are published quarterly, provides the meaning of the rate format, and explains result registration for large series. This enriches behavioral understanding without contradicting 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 a single, well-structured paragraph of five sentences. It front-loads the core purpose and each sentence provides essential information without redundancy. No waste.

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 complexity (5 parameters, output schema exists), the description covers the core purpose, limitations (not for transactions), publication schedule, rate format, and result registration behavior. It is sufficiently complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the rate meaning 'foreign currency units per 1 USD' and the purpose of canvas_id for large result sets. It enhances parameter understanding.

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

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

The description explicitly states the tool retrieves official Treasury reporting exchange rates for ~130 countries, a specific resource and verb. It clearly distinguishes from sibling tools like treasury_get_debt and treasury_get_interest_rates by focusing solely on exchange rates.

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 warns that these are not market exchange rates and are unsuitable for financial transaction pricing, which guides when not to use. It also provides the latest available quarter, giving temporal context. While it doesn't explicitly compare to siblings, the purpose is distinct enough.

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 and idempotentHint, so the description does not need to reiterate safety. It adds value by noting monthly updates, the exact security types covered, and the date-context example. No contradictions with annotations.

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

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

The description is efficient, front-loaded with the main purpose, and each sentence adds information. The example date and rates are somewhat verbose but ground the output. Could be slightly trimmed, but still well-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 tool has an output schema (not shown but present), the description does not need to detail return values. It adequately covers modes, filtering, update frequency, and offloading results via canvas_id. For a tool with 5 parameters, this is sufficiently 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 coverage is 100%, so baseline is 3. The description adds meaning beyond schema: it explains the purpose of 'latest' vs 'series', warns about end-of-month dates for start_date, and tells agents to use exact strings for security_type. It also clarifies canvas_id usage for dataframe registration.

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 ('returns') and resource ('average interest rates Treasury pays on its outstanding securities by security type'), clearly distinguishing this tool from siblings like treasury_get_debt or treasury_dataframe_query. It also provides concrete examples of security types and sample data.

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 explains the two modes ('latest' vs 'series') but does not explicitly state when to use this tool versus sibling tools like treasury_dataframe_query or treasury_get_debt. There is no 'when-not-to-use' guidance or mention of alternative 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 declare readOnlyHint and idempotentHint, so description is not required to repeat those. The description adds behavioral context (catalog is curated, typos cause errors) that enriches agent understanding without contradicting 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?

Four sentences, front-loaded with primary purpose, no wasted words. Efficiently covers purpose, usage, and warnings.

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 catalog discovery tool with 2 optional params and output schema, the description fully covers the catalog's nature, sibling relationship, error prevention, and categories. No gaps given the tool's complexity.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining the 'search' parameter's use case (narrow when category uncertain) and lists category options, providing context beyond schema property descriptions.

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 action ('Browse the curated catalog'), specifies what it returns (endpoint paths, field names, descriptions, update cadence), and distinguishes it from sibling treasury_query_dataset by noting it is used for discovery before querying. This is specific and differentiated.

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 instructs to use this tool before treasury_query_dataset to avoid 400 errors from typos, and clarifies that the catalog is curated but any endpoint can be passed directly to the sibling. Provides clear when-to-use and when-not-to-use boundaries.

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 and idempotentHint, but the description adds useful operational details: response values are all strings, 'null' string means no value, filter syntax with operators, and canvas_id registration. 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?

Two paragraphs, front-loaded with purpose. Every sentence adds value—no redundancy. Efficiently covers usage, parameters, and edge cases.

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 7 parameters, output schema exists, and complex interactions with other tools, the description is thorough. Covers prerequisites, errors, data types, and integration with DataCanvas. No gaps.

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

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

Schema coverage is 100%, baseline 3. Description adds significant meaning: filter syntax with operators, date format, sort prefix '-', canvas_id behavior, and warnings about typos. Enhances understanding beyond 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 states the tool queries any Treasury Fiscal Data endpoint with specific operations (path, fields, filters, sort, page). It distinguishes from siblings like treasury_list_datasets and treasury_dataframe_query by mentioning the correct workflow.

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 instructs to call treasury_list_datasets first for correct parameters and warns about typos causing 400 errors. Provides guidance on when to use canvas_id for large datasets. Could mention when not to use, but context is clear.

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