AgentReady Scoring

A composite score that tells agents how ready product data is for automated decision-making.

Design Principle: Your threshold, your rules. All data comes back with quality signals attached. You set the bar for what's trusted, flagged, or rejected.

What is AgentReady Scoring?

AgentReady scoring evaluates extracted product data across five active dimensions (a sixth, access_readiness, activates when Web Bot Auth adoption reaches detection threshold) to produce a single score (0-100) indicating how suitable the data is for autonomous agent workflows like purchasing, comparison, or inventory management.

Dimensions

Dimension	Weight	Description
Completeness structured_data_completeness	0.30	Percentage of expected fields present. Core fields (title, price, currency) weighted more heavily.
Semantic Richness semantic_richness	0.20	Category depth, attribute count, variant coverage, and description quality.
UCP Compatibility ucp_compatibility	0.20	How well the extracted data maps to the Universal Commerce Protocol schema.
Pricing Clarity pricing_clarity	0.15	Base price, currency, sale price, and B2B signals like bulk pricing and MOQ.
Inventory Signals inventory_signal_quality	0.15	Stock status specificity, quantity information, lead time, and backorder signals.
Access Readiness access_readiness	0.00	Agent accessibility score. Activates when Web Bot Auth adoption reaches detection threshold. Currently all test corpus URLs are fully open.

In API responses, these dimensions appear under their full names: structured_data_completeness, semantic_richness, ucp_compatibility, pricing_clarity, inventory_signal_quality, access_readiness.

AgentReady scores use a 0-100 scale. Per-field confidence scores (from the extraction pipeline) use a separate 0-1 scale. See Confidence Scoring for the field-level system.

Usage

Inline with extraction

Add include_score=true to any enrichment request:

{
  "url": "https://www.uline.com/Product/Detail/S-19318/Kraft-Paper/30-lb-Kraft-Paper-Sheets-8-1-2-x-11",
  "include_score": true
}

Standalone scoring

Score existing product data via POST /api/score:

{
  "product": {
    "title": "30 lb Kraft Paper Sheets - 8 1/2 x 11",
    "price": 92.00,
    "currency": "USD",
    "brand": "Uline",
    "sku": "S-19318",
    "availability": "InStock"
  }
}

Response Example

{
  "agent_readiness_score": 87,
  "scoring_breakdown": {
    "structured_data_completeness": {
      "score": 92,
      "weight": 0.30,
      "weighted_contribution": 27.6,
      "details": {
        "title": "present",
        "price": "present",
        "description": "present",
        "availability": "present",
        "images": "present",
        "brand": "present",
        "categories": "missing",
        "specs": "present"
      }
    },
    "semantic_richness": {
      "score": 68,
      "weight": 0.20,
      "weighted_contribution": 13.6,
      "details": {
        "category_count": 3,
        "attribute_count": 4,
        "variant_signals": 1,
        "description_length": 220
      }
    },
    "ucp_compatibility": {
      "score": 85,
      "weight": 0.20,
      "weighted_contribution": 17.0,
      "details": {
        "required_present": 3,
        "required_total": 3,
        "optional_present": 5,
        "optional_total": 8,
        "ucp_mapping_valid": true
      }
    },
    "pricing_clarity": {
      "score": 80,
      "weight": 0.15,
      "weighted_contribution": 12.0,
      "details": {
        "base_price": true,
        "currency": true,
        "sale_price": false,
        "bulk_pricing_detected": true,
        "moq_detected": false
      }
    },
    "inventory_signal_quality": {
      "score": 75,
      "weight": 0.15,
      "weighted_contribution": 11.25,
      "details": {
        "stock_status": true,
        "stock_status_value": "in_stock",
        "quantity_available": false,
        "lead_time_detected": true,
        "backorder_detected": false
      }
    },
    "access_readiness": {
      "score": 100,
      "weight": 0.00,
      "weighted_contribution": 0,
      "details": {
        "access_level": 5,
        "access_label": "fully_open",
        "feature_flag_active": false,
        "note": "Access readiness scoring activates when Web Bot Auth adoption reaches detection threshold."
      }
    }
  },
  "scoring_version": "2026-04-08-v1",
  "methodology_url": "https://shopgraph.dev/methodology"
}

Schema Reference

interface AgentReadyScore {
  agent_readiness_score: number;      // Composite score (0-100)
  scoring_breakdown: {
    structured_data_completeness: DimensionScore;  // weight: 0.30
    semantic_richness: DimensionScore;             // weight: 0.20
    ucp_compatibility: DimensionScore;             // weight: 0.20
    pricing_clarity: DimensionScore;               // weight: 0.15
    inventory_signal_quality: DimensionScore;      // weight: 0.15
    access_readiness: DimensionScore;              // weight: 0.00 (stub)
  };
  scoring_version: string;            // e.g. "2026-04-08-v1"
  methodology_url: string;            // Link to methodology docs
}

interface DimensionScore {
  score: number;                      // Dimension score (0-100)
  weight: number;                     // Weight in composite (0.0-1.0)
  weighted_contribution: number;      // score * weight
  details: Record;       // Dimension-specific details
}

Dimension Details

structured_data_completeness

Detail Field	Type	Description
title	string	"present" or "missing"
price	string	"present" or "missing"
description	string	"present" or "missing"
availability	string	"present" or "missing"
images	string	"present" or "missing"
brand	string	"present" or "missing"
categories	string	"present" or "missing"
specs	string	"present" or "missing"
b2b_bonus	number	Bonus points for B2B signals (0-10)

semantic_richness

Detail Field	Type	Description
category_count	number	Number of categories
attribute_count	number	Colors, materials, dimensions
variant_signals	number	Max of color/material variant count
description_length	number	Character count of description

ucp_compatibility

Detail Field	Type	Description
required_present	number	Required UCP fields present
required_total	number	Total required UCP fields
optional_present	number	Optional UCP fields present
optional_total	number	Total optional UCP fields
ucp_mapping_valid	boolean	UCP mapping succeeded

pricing_clarity

Detail Field	Type	Description
base_price	boolean	Base price is present
currency	boolean	Currency code is present
sale_price	boolean	Sale price detected
bulk_pricing_detected	boolean	Bulk/tier pricing detected
moq_detected	boolean	Minimum order quantity detected

inventory_signal_quality

Detail Field	Type	Description
stock_status	boolean	Stock status is present
stock_status_value	string	The availability value
quantity_available	boolean	Quantity info detected
lead_time_detected	boolean	Lead time info detected
backorder_detected	boolean	Backorder info detected

access_readiness

Detail Field	Type	Description
access_level	number	Access level (1-5)
access_label	string	Human-readable access label
feature_flag_active	boolean	Whether access readiness is active
note	string	Explanatory note

B2B Awareness

For B2B products, the scoring system detects and rewards additional fields:

• MOQ (Minimum Order Quantity) — detected from product pages
• Lead time — shipping/delivery time for bulk orders
• Bulk pricing tiers — volume discount breakpoints
• Manufacturer part number — cross-reference capability

Example: URL Prioritization

Before committing pipeline resources, score a batch of supplier URLs. Rank by AgentReady score. Process high-readiness domains first, defer low-scoring URLs for manual review.

const urls = await loadSupplierUrls();  // 50 candidate URLs
const scored = [];

for (const url of urls) {
  const res = await fetch('https://shopgraph.dev/api/enrich', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer sg_live_your_key'
    },
    body: JSON.stringify({ url, include_score: true })
  });
  const data = await res.json();
  scored.push({ url, score: data.agent_readiness_score });
}

// Process highest-readiness URLs first
scored.sort((a, b) => b.score - a.score);

Quantitative triage. Allocate pipeline resources to the URLs most likely to return complete, actionable data.