Fintel Discovery — Financial Intelligence for AI Agents

Get Territory Wealth Profile — Census ACS

GetTerritoryWealthProfile

Read-onlyIdempotent

    Retrieve US Census American Community Survey (ACS) income and wealth proxy
    data for a ZIP code or state. Returns median household income, median home
    value, total household count, and the count and share of households earning
    $100k or more — useful for scoring territory opportunity for financial advisors.

    Key metrics returned:
    - median_hh_income: Median household income (B19013)
    - median_home_value: Median owner-occupied home value (B25077)
    - total_households: Total household count (B11001)
    - hh_100k_plus: Households earning $100k+ (derived)
    - hh_100k_plus_pct: Share of households earning $100k+ (derived)

    Use this tool when:
    - You are scoring a territory for wealth potential by ZIP code
    - You want to compare household income distribution across territories
    - You need a demographic wealth proxy before overlaying advisor AUM data

    Requires cenpy Python package and optionally a free Census API key
    (api.census.gov/data/key_signup.html).
    Source: US Census Bureau ACS 5-Year estimates. Free with optional API key.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`params`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description mainly adds useful context: the dependency on cenpy, the optional Census API key, the ACS 5-Year source, and that income/share metrics are derived. This goes beyond the annotations 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.

Conciseness4/5

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

The description is organized and front-loaded: purpose, key metrics, use cases, then requirements/source. The metric bullet list is useful and not padded. The only minor redundancy is mentioning the free/optional API key twice, which keeps it from a perfect score.

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

Completeness4/5

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

The description covers what the tool returns, why it is useful, when to use it, the external dependency, and the data source. Since an output schema exists, it does not need to fully document return structure. It is slightly incomplete about edge cases such as missing or conflicting zip_code/state arguments and how the generic fin parameters interact with the territory profile.

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

Parameters3/5

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

The schema description coverage is reported as 0%, so the description carries some burden. It does identify the core selectors ('ZIP code or state') and mentions the optional census_api_key, but it does not clarify whether one selector is required, what happens when both are provided, or how the fin-specific parameters such as wholesaler_ids and source_resource_id affect invocation. The nested input schema fills part of this gap.

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

Purpose5/5

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

The description opens with a specific verb and resource: 'Retrieve US Census American Community Survey (ACS) income and wealth proxy data for a ZIP code or state.' It also names the exact returned metrics, making the tool's purpose unmistakable, especially against sibling tools focused on tickers, funds, and broker data.

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

Usage Guidelines4/5

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

The description provides explicit 'Use this tool when' bullets that give clear invocation context for territory wealth scoring and demographic comparison. It does not name a specific alternative tool or give explicit 'when not to use' guidance, but the use cases are concrete enough to route an agent appropriately.

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

All Fintel Discovery — Financial Intelligence for AI Agents tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A3.9/5.0

Disambiguation4/5

Most tools target a distinct resource and action, with clear separation between search and detail tools (e.g., SearchIAPDFirm vs GetIAPDFirmDetail, SearchBrokerCheck vs GetBrokerCheckDetail). A few pairs like SearchBrokerCheck and SearchBrokerCheckFirm could cause momentary confusion, but descriptions clarify individual vs firm scope.

Naming Consistency4/5

The dominant pattern is consistent: Search* for discovery, Get* for retrieval, with CamelCase throughout. Minor deviations like LookupTicker and MapInstrumentIds introduce different verbs, and SearchBrokerCheck does not explicitly signal 'individual' unlike SearchBrokerCheckFirm, but the overall convention remains predictable.

Tool Count2/5

With 32 tools, the surface is quite heavy and exceeds the 25+ threshold for 'too many.' While the financial intelligence domain is broad, several search/detail pairs and overlapping data-source tools could be consolidated to reduce cognitive load for agents.

Completeness4/5

The toolset covers major workflows well: 13F holdings, fund fee comparison, advisor due diligence, macro data, price history, options, and identifier mapping. Minor gaps exist, such as no standalone real-time quote tool, no news/sentiment data, and no direct CUSIP-to-company-name search, but these are workable around.

Resources

Need Help?