The Hallucination of Structured Data: AI Agent Data Interpretation Challenges Seen Through a Job Search API

Title

Structured Data's Hallucination: AI Agent Data Interpretation Challenges Seen Through a Job Search API

Meta Description

A developer built a job search API and found half of the salary structured data was noise: multiple salaries for the same job, 30% non-numeric strings, chaotic currency formats. This article analyzes the key implications for AI Agent data consumption and API design — the schema isn't the product, the interpretation layer is.

Article Content

A developer built a job search API that returned clean JSON-formatted fields for positions, companies, locations, and salaries. Everything was perfect during testing, but when he handed the API to an AI Agent — for price comparison, salary-based filtering, and monitoring new jobs — he discovered that half of the salary fields were noise. This case reveals a neglected truth: formalization of structured data does not equal semantic usability, and for AI Agents that rely on data to make decisions, the quality of the interpretation layer is the real product value.

Same Job, Three Salaries, Four Numbers

A "Senior Engineer" position posted by the same company in Berlin appeared three times, with salary ranges of €70–90k, €85–110k, and one with no salary at all. The deduplication key (title + company) itself wasn't the problem — the data was. The developer eventually adopted normalized title + company + location clustering, treating salary as a distribution rather than a point value.

This exposes the fundamental contradiction of aggregation-type data APIs: the same position posted at different times, through different recruitment channels, by different HR representatives may carry completely inconsistent compensation information. If an Agent treats each salary as a certain fact, its decisions will be skewed.

For developers building Agent systems, this means salary fields need to carry "source" and "timestamp" metadata so that downstream reasoning can reasonably judge which number is more credible.

Limitations of Deduplication Keys and Clustering Strategies: Traditional deduplication relies on exact-match keys (such as "title + company"), but the job market naturally has soft duplicates — the same position may have slightly different titles due to channel, language, or posting time differences (e.g., "Senior Engineer" vs. "高级工程师"), which exact keys would miss. A more robust approach is fuzzy clustering: normalize titles and company names (lowercase, remove modifiers, unify language), then combine geographic location and time windows for similarity grouping. After clustering, salary should no longer be treated as a point value but modeled as a distribution (e.g., median, quantiles, or union of intervals) for downstream Agents to consume by confidence level. Additionally, each salary should be accompanied by metadata such as source channel, scraping time, and HR attribution, enabling Agents to dynamically assess credibility rather than blindly trusting a single number.

"Competitive" Is Also a Value — Don't Throw Away 30% of the Market

About 30% of positions had strings where the schema expected numbers. The developer's first instinct was to discard these rows. But this instinct was wrong — it meant throwing away one-third of the market information.

The correct approach is: parse what can be parsed, flag what cannot, and let the caller decide. Strings like "competitive," "negotiable," and "based on experience" are themselves signals indicating that the position's salary is not transparent — which is precisely an important dimension for market analysis.

This relates to how AI Agents consume data. Agents, unlike human UIs, cannot simply "ignore" empty fields — they need explicit flags to determine which data can participate in reasoning and which should trigger fallback logic.

Failure to Normalize Currency Equals Lies

£60k, 60000 GBP, 60,000£, €60.000 — European decimal points use commas, symbol positions are inconsistent, and gross/net/TC labels are buried in descriptions. Without normalization, any cross-regional salary comparison is meaningless.

The developer added a normalization layer that extracts amount + currency + period (year/month/hour) and uniformly converts to annualized figures. Although errors still occur sometimes, errors are consistently filterable rather than randomly chaotic. This distinction is crucial: what Agent systems need is not perfect data, but predictable error patterns.

For any AI application handling multi-source geographic data, currency normalization should not be optional — it should be an essential layer of the data pipeline.

Technical Details of Amount Normalization: Currency normalization goes far beyond exchange rate conversion — it encompasses three orthogonal dimensions: amount parsing (handling thousands separators, decimal point symbols, currency symbol positions), currency identification (inferring ISO 4217 codes from symbols, codes, or context), and period standardization (year/month/day/hour conversion). European number formats often use commas as decimal points (e.g., €60.000 means sixty thousand euros), while Anglo-American formats do the opposite, requiring parsers with geographic awareness. Additionally, distinguishing gross from total compensation (TC) requires extraction from text labels or descriptions. After normalization, a unified structure should be output (e.g., {amount: 95000, currency: 'EUR', period: 'year', type: 'gross'}), with the original string preserved as an audit trail. Even if parsing errors exist, as long as error patterns are consistent (e.g., a particular source is always misread), downstream systems can circumvent them through filtering rules — this is more manageable than random chaos.

The Description Field Is the Real Salary Source

Structured salary fields are often just placeholders. The real numbers are often hidden in sentences like "compensation up to €95k, depending on experience." The developer added a lightweight extraction layer that grabs candidate numbers from descriptions and marks them as estimated: true, preventing downstream Agents from treating them as authoritative data.

This design decision is worth adopting: the same piece of data should be consumed differently at different confidence levels. High-confidence structured fields can be used directly for filtering and sorting, while low-confidence extracted values can only be used for exploratory analysis or as secondary sorting factors.

Design Principles for Confidence Tagging: Attaching confidence labels to data (such as confidence: high/medium/low or estimated: true) is core to building reasoning-oriented APIs. High-confidence sources include direct structured fields (such as Schema.org's baseSalary) or official disclosures; medium confidence can come from consistent extraction across multiple descriptions; low confidence comes from single fuzzy matches or third-party estimates. Agents should consume data accordingly in tiers: high-confidence data for hard filters (e.g., "salary > 80k") and primary sort keys; medium-to-low confidence data for exploratory analysis, supplementary sorting factors, or triggering human review. Additionally, the API should return source_note explaining data provenance, such as "extracted from job description, original text: 'compensation up to €95k'," allowing Agents to transparently cite it in their reasoning chain. This design explicitly exposes data uncertainty rather than hiding it, thereby preventing downstream systems from making overconfident decisions.

API Design Needs to Shift from "Display" to "Reasoning"

The core shift in this case is a mindset change: from "API returns well-structured data for humans to view" to "API returns semantically annotated data for Agents to reason about."

The developer's final API returns raw fields plus confidence hints and source_note. The data is messier, but actually usable.

This has direct implications for teams building Agent applications or data pipelines: the schema isn't the product — interpretation is. If your API output will be consumed by AI Agents, the time spent on normalization and confidence tagging is far more valuable than optimizing field names and documentation formats.

The developer packaged the entire solution into a single endpoint (keyword + location input, returning normalized deduplicated positions), which can serve as a reference implementation for the data layer in Agent toolchains.

One-line Summary

When building job search APIs for AI Agents, semantic data usability matters more than format regularity — normalization and confidence tagging are essential.

Paragraph Summary

A developer's job search API performed perfectly in human testing but exposed serious problems when handed to an AI Agent: the same position had multiple contradictory salary versions, about 30% of salary fields were non-numeric strings (like "competitive"), chaotic currency formats made cross-regional comparison fail, and real salaries were often hidden in description text. The article points out that formalization of structured data does not equal semantic usability — for Agents that rely on data to make decisions, interpretation layer quality is the product value. Solutions include: treating salary as a distribution rather than a point value, clustering for deduplication; preserving and flagging unparseable strings; implementing a currency normalization layer; extracting salaries from descriptions and marking them as estimated; and having the API return semantic annotations like confidence and source_note. The core insight: Agent-facing API design should shift from "display-oriented" to "reasoning-oriented" — the schema isn't the product, interpretation is.