soi-mcp

by mcpwright

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.1
Disambiguation5/5
Each tool targets a distinct facet of SOI data: validation, income, distribution, tax, credits, deductions, filing status, comparison, state aggregates, and raw field access. No two tools overlap in purpose, making selection unambiguous.
Naming Consistency5/5
All tool names follow a clear verb_noun pattern with lowercase and underscores: lookup_zip, get_income, get_agi_distribution, compare_zips, etc. The variation in verbs (lookup, get, compare) is natural and consistent with each tool's action.
Tool Count5/5
With 10 tools, the set is well-scoped for a domain-specific SOI server. Each tool covers a major data category, and the count fits comfortably within the ideal 3-15 range without redundancy or bloat.
Completeness5/5
The surface covers the full range of SOI data categories: counts, income, tax, credits, deductions, filing status, comparison, state-level totals, and a raw field escape hatch. There are no obvious dead ends or missing lifecycle operations for the stated purpose.
Average 4.5/5 across 10 of 10 tools scored. Lowest: 3.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 8 commits in the last 12 weeks
- Last stable release on June 4, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds important behavioral context beyond the annotations: it explains that a 0 may be IRS-suppressed rather than a true zero, which is a critical interpretation caveat. It also states the return includes counts, amounts, and percentages. Since annotations already convey read-only and open-world semantics, this additional note about data suppression provides meaningful insight, though it does not cover all possible edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, starting with a clear purpose statement, then a focused parameter explanation, then return details, and finally a brief caveat. Every sentence earns its place with no unnecessary filler. It is well-structured and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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, the description does not need to enumerate every return field, but it still summarizes the key outputs (counts, amounts, SALT, percent itemized). It explains the zip_code parameter and provides the crucial IRS-suppression caveat. With the annotations indicating read-only and open-world behavior, this description is complete for making a correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only defines zip_code as a string with no description (0% schema coverage). The description compensates by specifying 'a 5-digit US ZIP' and explaining what the parameter is used for (returns deduction measures for that ZIP). This adds the necessary format and semantic meaning beyond the schema, but could go further with examples or valid values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Deduction measures for a ZIP: standard vs. itemized, plus SALT,' which clearly identifies the resource (deductions) and scope (ZIP). The tool name 'get_deductions' supplies the verb, and the distinction from sibling tools like get_income or get_tax is implicit. However, the description lacks an explicit verb phrase, so it falls just 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.
Usage Guidelines2/5
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 the sibling tools. It does not mention alternative tools like get_tax or compare_zips, nor does it state any exclusions or prerequisites. The only implied context is that it is for ZIP-level deduction measures, but the description does not explicitly help the agent decide between this and related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is established. The description adds transparency by specifying the data source ('IRS 00000 state-total row') and listing the exact fields returned, which enriches the behavioral context beyond the annotations.
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 efficiently structured: the first sentence states the purpose, the second details the parameter, and the third lists the returned fields. Every sentence contributes useful information without unnecessary verbosity.
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?
With a single well-documented parameter and an output schema present, the description is nearly complete for a simple retrieval tool. It covers source, returned fields, and parameter format, leaving only minor gaps like error handling, but these are not critical given the output schema and annotation context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only defines the 'state' parameter with no description (0% schema coverage). The description fully compensates by explaining accepted formats (2-letter USPS code or full state name) with examples, providing essential semantic value.
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 clearly states the tool's purpose: to retrieve state-level SOI totals and AGI distribution from the IRS state rollup. It names the specific resource and differentiates from siblings by focusing on state-level aggregates rather than zip-level or single-metric tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for state-level aggregate data but does not explicitly state when to use it over alternatives. No exclusions or alternative tool names are mentioned, so usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and open-world hints. The description adds valuable behavioral details: the exclusion of ZIPs with fewer than 100 returns and the specific data returned (state, counts, tax year). It does not contradict annotations and enhances understanding beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose. Every sentence adds value: the ZIP format, the use case, and the exclusion rule. No redundancy or irrelevant information.
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?
For a simple single-parameter lookup with an output schema, the description covers the essential context: what it does, when to use it, and key constraints. It does not describe the not-found behavior, but the output schema likely handles that, and the annotations cover safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by defining 'zip_code' as a 5-digit US ZIP and noting the exclusion threshold. It adds practical meaning beyond the schema's basic property definition, though it could specify validation rules more explicitly.
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 clearly states the tool's purpose: to confirm a ZIP has SOI data and return counts. It uses specific verbs and identifies the resource (ZIP), and distinguishes itself from siblings by positioning as a validation first call.
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 explicitly recommends this as a 'good first call' before requesting more detail, giving clear usage context. It does not name alternative tools or provide when-not-to-use scenarios, but the context is sufficient for a simple lookup tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint, the description discloses IRS suppression behavior for 0 counts, a critical nuance not captured in annotations. It also defines 'elderly returns' as age 65+, adding valuable specificity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient, covering purpose, parameters, and a caveat in three concise sentences with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with an existing output schema, the description completely covers the input format, return metrics, and an important data-quality note. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides type/name, but the description explains that zip_code must be a 5-digit US ZIP. This is essential for correct invocation and adds meaning beyond the schema.
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 clearly states the tool returns filing-status mix (single, married-joint, head-of-household) for a ZIP, using the specific verb 'get'. It distinguishes from siblings like get_income or get_agi_distribution by focusing on filing status.
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 ZIP-specific scope is obvious from the description, making the intended use clear. However, it does not explicitly mention when not to use this tool or reference alternatives, so it falls 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, covering safety. The description adds valuable behavioral context: it explains what the broader total liability includes (self-employment tax, other taxes), specifies that amounts are in USD, and clarifies the ZIP format. This goes beyond the schema, though it could mention edge cases (e.g., invalid ZIPs), hence a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first a high-level summary, then parameter detail and return list. Every sentence contributes information without fluff. It is front-loaded with the main purpose and structured logically.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, but the description still explains the returned fields, which is helpful. All relevant context—purpose, parameter, return metrics, currency—is provided. The description is complete for a simple query tool, with no missing operational details expected for this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides the parameter name 'Zip Code' with 0% description coverage. The tool description fully compensates by specifying the exact format ('5-digit US ZIP') and its purpose in the query. This adds meaning beyond the raw schema, making the parameter semantics clear.
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 clearly states the tool retrieves tax measures for a given ZIP code, enumerating specific metrics (income tax, total liability, average per return). It distinguishes from sibling tools like get_income or get_credits by focusing on aggregate tax measures and explicitly noting the broader total tax liability including self-employment tax.
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 context is clear: use this tool when you need tax data for a 5-digit US ZIP code, with a list of returned metrics. It implies when to use this over more specific tools like get_income (which likely focuses on income tax only), but does not explicitly name alternatives or exclusions, 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=true, openWorldHint=true), the description discloses a critical behavioral nuance: 'a bracket showing 0 may be IRS-suppressed (<20 returns in that cell) rather than truly empty', and that this can cause other brackets' shares to be 'slightly overstated'. It also clearly enumerates what is returned (number of returns, total AGI, and share) which goes beyond the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear purpose statement, then compactly details return contents and the suppression caveat in a separate paragraph. Every sentence adds value, and the note is placed at the end to avoid obscuring the main behavior. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, the description doesn't need to spell out every return field, but it does anyway by naming the six brackets and listing the metrics returned. It also covers edge behavior (IRS suppression) and the impact on other shares. This makes the tool fully understandable in context, with no major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description compensates by explaining `zip_code` as 'a 5-digit US ZIP'. This is minimally sufficient for a single-parameter tool. It doesn't clarify whether a numeric string with leading zeros is expected, but the 5-digit US ZIP description covers the core semantic need.
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 clearly states the tool 'Returns the income distribution of a ZIP across the six IRS AGI brackets', naming a specific resource (ZIP income distribution) and the six bracket breakdown. It distinguishes itself from sibling tools by emphasizing 'the income *shape* of a ZIP — what a single median can't show', which contrasts with likely aggregate income tools.
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 clear context on when to use the tool: when the full distribution shape is needed rather than a single median. It doesn't explicitly name alternative tools for other use cases, but the phrase 'what a single median can't show' implies a comparison and sets expectations. The IRS suppression note also helps the user interpret results correctly, which is part of guiding appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint=true annotation, the description discloses return semantics (summed across AGI brackets, includes label and unit), case-insensitivity, error behavior for unknown fields, and the IRS-suppression caveat. This is rich context that heavily informs the agent about outputs and edge cases, far exceeding the annotation baseline.
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 well-structured: a one-sentence purpose lead, followed by parameter details and a caution note. Every sentence carries necessary information, though slightly verbose with the inclusion of examples and caveats. It remains appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's scope, parameters, return value semantics, error behavior, and data caveats. Since an output schema exists, it doesn't need to detail the response shape further. For a 2-parameter read-only tool, this is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description fully compensates by defining both parameters: zip_code as '5-digit US ZIP' and field as a 'SOI field code' with examples (A00100, N1) and case-insensitivity. This gives complete practical meaning to the schema's bare property names.
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 clearly states the tool's function: 'Raw value of a single SOI field for a ZIP — an escape hatch.' This specifies a distinct resource (single SOI field) and verb (get raw value), and differentiates it from siblings by emphasizing it's a raw/escape-hatch access to underlying data rather than a standardized aggregate tool.
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 implies usage context via 'escape hatch' and notes the tool is 'Limited to the fields held in the local store (the same ones the other tools draw on).' This gives clear sense of when to use it (raw field access, when other tools don't expose it) but does not explicitly name alternatives or state when not to use it, leaving some implicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint, the description adds essential behavioral details: results sorted descending, ZIPs without SOI data listed last, and suppressed zeros potentially not representing true zeros. This significantly enhances transparency for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet complete, front-loading the core action and then providing param semantics and behavior in a well-structured format. The metric list, while lengthy, is necessary and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description does not need to explain return values, but it still covers sorted order and missing-data handling. Both parameters are fully specified, making the tool's behavior complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite zero schema description coverage, the description fully explains both parameters: `zips` as a list of 5-digit US ZIPs and `metric` with every possible enum value enumerated. This adds complete meaning beyond the bare schema.
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 clearly states the tool ranks several ZIPs by a single metric, specifically highest value first. It distinguishes itself from sibling tools by focusing on comparison across multiple ZIPs rather than single-lookup getters.
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 clearly conveys when to use this tool (comparing several ZIPs on one metric) and implies the scope of input. It does not explicitly state alternatives or when-not-to-use, but the context of siblings and the unique compare functionality provides clear usage context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations, notably the IRS-suppression caveat where a zero may not be a true zero, plus the output components and USD units. This significantly helps interpretation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly structured: purpose sentence, parameter and return detail, then an essential caveat. Every sentence earns its place, and the most critical information is front-loaded. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, detailed return structure is covered externally. The description provides the purpose, the one parameter's format, the breakdown logic, and a crucial data-quality caveat, making it complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description compensates by explicitly defining `zip_code` as a '5-digit US ZIP', adding format and meaning beyond the schema's bare string type. With only one required parameter, this fully covers the parameter semantics.
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 'Refundable-credit take-up for a ZIP' and explicitly names the EITC and additional child tax credit, clearly distinguishing this from sibling tools focused on income, AGI, deductions, or filing status. It uses a specific verb and resource, making the tool's purpose immediately identifiable.
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 clearly implies use when ZIP-level refundable credit data is needed, and enumerates the exact breakdowns returned (e.g., by number of qualifying children). It does not explicitly name alternative tools or state when not to use it, so it stops short of full exclusion guidance, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the readOnly/openWorld annotations: it explains data covers filed tax returns only, average AGI is a mean not median, and AGI omits nontaxable income. These caveats help the agent avoid misinterpretation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary line, a detailed list of returned components, and a crucial note. Each sentence adds value, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations declaring read-only/open-world and an output schema available, the description covers all essential behavioral and interpretive context. It provides ample detail for a single-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides a title 'Zip Code', but the description details that `zip_code` is a 5-digit US ZIP and explains how it is used. This high-value guidance compensates for the schema's lack of description.
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 clearly states the tool returns income measures for a ZIP, listing specific components (AGI, average AGI, and income components). It distinguishes itself from siblings by focusing on ZIP-level income aggregates with a specific set of metrics.
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?
Clear context is provided for when to use the tool: when ZIP-level income figures are needed. The note about not being comparable to Census median household income acts as an implicit exclusion, though no explicit alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![soi-mcp MCP server](https://glama.ai/mcp/servers/mcpwright/soi-mcp/badges/card.svg)](https://glama.ai/mcp/servers/mcpwright/soi-mcp)

Score Badge

Copy to your README.md:

[![soi-mcp MCP server](https://glama.ai/mcp/servers/mcpwright/soi-mcp/badges/score.svg)](https://glama.ai/mcp/servers/mcpwright/soi-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mcpwright/soi-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server