US compliance and books health

Who Median is, what it does, who it is for, how onboarding works, and how to get in touch or book an intro call.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Median's published pricing: the flat monthly fee by revenue band under $1M in annual revenue, the per-account and per-ledger-entry meter that scoping is based on above $1M, what is included, and add-on pricing for tax, R&D credits, and sales tax.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List the services Median offers (daily bookkeeping, tax filing, R&D tax credits, CFO advisory) with a short summary and page link for each.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List published articles from the Median blog, newest first. Optionally filter by category or a search term matched against the title.

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "description": "Match against the post title."
    },
    "category": {
      "type": "string",
      "description": "Filter to one category slug or name."
    },
    "limit": {
      "type": "integer",
      "description": "How many posts to return (default 20, max 50)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch the full text of one published Median blog post by its slug.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "description": "Post slug, e.g. 'how-to-switch-bookkeeping-services'."
    }
  },
  "required": [
    "slug"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Refinement step, NOT the place to start: call list_compliance_obligations first, then call this to narrow what is still genuinely open. Returns the facts that flip an answer, such as whether an employer of record is the legal employer. Pass every fact you already know and it returns only what those facts leave unsettled. These are things for YOU to look up in the user's own documents. They are not a questionnaire to send the user.

{
  "type": "object",
  "properties": {
    "company_name": {
      "type": "string",
      "maxLength": 120,
      "description": "Optional, and the only identifying thing this tool records. Median stores it to see which companies use this tool and may follow up. It changes nothing about the answer, so omit it if the user has not agreed to share it. Send the legal entity name only, never an address, EIN or anything from a document."
    },
    "entity_type": {
      "type": "string",
      "enum": [
        "c-corp",
        "s-corp",
        "llc",
        "llc-single-member",
        "partnership",
        "benefit-corp",
        "nonprofit"
      ],
      "description": "Legal entity type."
    },
    "formation_state": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "description": "Two-letter state of formation, e.g. 'DE'."
    },
    "formation_date": {
      "type": "string",
      "description": "ISO date the entity was formed."
    },
    "fiscal_year_end": {
      "type": "string",
      "description": "MM-DD, e.g. '12-31'. Defaults to 12-31."
    },
    "tax_year": {
      "type": "integer",
      "description": "Tax year under review. Defaults to last calendar year."
    },
    "operating_states": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 2,
        "maxLength": 2
      },
      "description": "States where the company operates."
    },
    "employee_states": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 2,
        "maxLength": 2
      },
      "description": "States where W-2 employees work."
    },
    "contractor_states": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 2,
        "maxLength": 2
      },
      "description": "States where 1099 contractors work."
    },
    "sales_states": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 2,
        "maxLength": 2
      },
      "description": "States with customers."
    },
    "revenue_band": {
      "type": "string",
      "enum": [
        "pre-revenue",
        "under-250k",
        "250k-1m",
        "1m-5m",
        "over-5m"
      ],
      "description": "Gross annual revenue as a band, never an exact figure: 'pre-revenue', 'under-250k', '250k-1m', '1m-5m' or 'over-5m'. Drives revenue-scaled thresholds such as state franchise tax minimums and economic nexus. Leave unset if unknown; the tool asks for it rather than guessing."
    },
    "foreign_owned": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "const": "unknown"
        }
      ],
      "description": "Whether any non-US person owns 25% or more. Leave unset if genuinely unknown."
    },
    "payroll_model": {
      "type": "string",
      "enum": [
        "eor",
        "client-is-employer",
        "peo",
        "contractors-only",
        "none",
        "unknown"
      ],
      "description": "Critical. An employer of record holds state registrations under its own entity, so the answer flips entirely on this."
    },
    "payroll_provider": {
      "type": "string",
      "maxLength": 60,
      "description": "The provider's name only, e.g. 'Deel', 'Gusto', 'Rippling'. Not account numbers, not employee details, not anything else."
    },
    "formation_platform": {
      "type": "string",
      "enum": [
        "stripe-atlas",
        "clerky",
        "firstbase",
        "attorney",
        "self",
        "other",
        "unknown"
      ],
      "description": "Decides whether a bundled first-year registered agent explains a missing fee."
    },
    "presence_type": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "enum": [
          "office",
          "coworking",
          "virtual-mailbox",
          "founder-home",
          "employees-only",
          "none"
        ]
      },
      "propertyNames": {
        "minLength": 2,
        "maxLength": 2
      },
      "description": "Per-state presence, e.g. { NY: 'virtual-mailbox' }."
    },
    "sells_saas": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "const": "unknown"
        }
      ],
      "description": "Whether the product is SaaS. New York taxes SaaS as prewritten software."
    },
    "extensions_filed": {
      "type": "object",
      "additionalProperties": {
        "type": "boolean"
      },
      "description": "Whether a tax extension was filed, keyed 'US' for federal and by state code, e.g. { US: true, NY: false }. OMIT a key you are unsure about: no deadline is asserted for an unknown key, because assuming an extension tells a late filer they have months in hand."
    },
    "registered_in": {
      "type": "object",
      "additionalProperties": {
        "type": "boolean"
      },
      "propertyNames": {
        "minLength": 2,
        "maxLength": 2
      },
      "description": "Whether the company is already registered to do business in a state, e.g. { NY: false }. Drives obligations that only begin at registration."
    },
    "answers": {
      "type": "object",
      "additionalProperties": {
        "type": "boolean"
      },
      "description": "Answers to the yes/no threshold questions this tool asks, keyed by the threshold id shown in the question, e.g. { \"foreign-accounts-over-10k\": false, \"ny-sales-over-500k\": false }. Without this the same questions repeat forever and the obligations behind them can never resolve. Omit a key you genuinely do not know."
    },
    "answered": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Only for confounders with no matching fact field above (who-paid, prepaid-multi-year). For everything else pass the fact itself, e.g. payroll_model: 'eor', not answered: { 'payroll-model': 'eor' }."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

START HERE. Given whatever you know about a company, return the federal and state compliance obligations that apply, ordered by urgency with overdue items first, plus the specific questions that unblock the rest. Call it immediately with partial facts rather than interviewing the user first: it is designed for incomplete input, and every fact you are missing comes back as one precise question instead of the dozen generic ones you would otherwise ask. Then answer those and call it again. Defaults to a short actionable view; relay it roughly as written rather than expanding it into an essay, and pass detail='full' only when the user asks for evidence tiers and remediation detail. Covers US federal plus CA, CO, DE, FL, GA, IL, MA, NJ, NY, PA, TX and WA; every other state is reported honestly as not yet covered. This never tells you whether you are compliant, only what to check.

{
  "type": "object",
  "properties": {
    "company_name": {
      "type": "string",
      "maxLength": 120,
      "description": "Optional, and the only identifying thing this tool records. Median stores it to see which companies use this tool and may follow up. It changes nothing about the answer, so omit it if the user has not agreed to share it. Send the legal entity name only, never an address, EIN or anything from a document."
    },
    "entity_type": {
      "type": "string",
      "enum": [
        "c-corp",
        "s-corp",
        "llc",
        "llc-single-member",
        "partnership",
        "benefit-corp",
        "nonprofit"
      ],
      "description": "Legal entity type."
    },
    "formation_state": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "description": "Two-letter state of formation, e.g. 'DE'."
    },
    "formation_date": {
      "type": "string",
      "description": "ISO date the entity was formed."
    },
    "fiscal_year_end": {
      "type": "string",
      "description": "MM-DD, e.g. '12-31'. Defaults to 12-31."
    },
    "tax_year": {
      "type": "integer",
      "description": "Tax year under review. Defaults to last calendar year."
    },
    "operating_states": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 2,
        "maxLength": 2
      },
      "description": "States where the company operates."
    },
    "employee_states": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 2,
        "maxLength": 2
      },
      "description": "States where W-2 employees work."
    },
    "contractor_states": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 2,
        "maxLength": 2
      },
      "description": "States where 1099 contractors work."
    },
    "sales_states": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 2,
        "maxLength": 2
      },
      "description": "States with customers."
    },
    "revenue_band": {
      "type": "string",
      "enum": [
        "pre-revenue",
        "under-250k",
        "250k-1m",
        "1m-5m",
        "over-5m"
      ],
      "description": "Gross annual revenue as a band, never an exact figure: 'pre-revenue', 'under-250k', '250k-1m', '1m-5m' or 'over-5m'. Drives revenue-scaled thresholds such as state franchise tax minimums and economic nexus. Leave unset if unknown; the tool asks for it rather than guessing."
    },
    "foreign_owned": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "const": "unknown"
        }
      ],
      "description": "Whether any non-US person owns 25% or more. Leave unset if genuinely unknown."
    },
    "payroll_model": {
      "type": "string",
      "enum": [
        "eor",
        "client-is-employer",
        "peo",
        "contractors-only",
        "none",
        "unknown"
      ],
      "description": "Critical. An employer of record holds state registrations under its own entity, so the answer flips entirely on this."
    },
    "payroll_provider": {
      "type": "string",
      "maxLength": 60,
      "description": "The provider's name only, e.g. 'Deel', 'Gusto', 'Rippling'. Not account numbers, not employee details, not anything else."
    },
    "formation_platform": {
      "type": "string",
      "enum": [
        "stripe-atlas",
        "clerky",
        "firstbase",
        "attorney",
        "self",
        "other",
        "unknown"
      ],
      "description": "Decides whether a bundled first-year registered agent explains a missing fee."
    },
    "presence_type": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "enum": [
          "office",
          "coworking",
          "virtual-mailbox",
          "founder-home",
          "employees-only",
          "none"
        ]
      },
      "propertyNames": {
        "minLength": 2,
        "maxLength": 2
      },
      "description": "Per-state presence, e.g. { NY: 'virtual-mailbox' }."
    },
    "sells_saas": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "const": "unknown"
        }
      ],
      "description": "Whether the product is SaaS. New York taxes SaaS as prewritten software."
    },
    "extensions_filed": {
      "type": "object",
      "additionalProperties": {
        "type": "boolean"
      },
      "description": "Whether a tax extension was filed, keyed 'US' for federal and by state code, e.g. { US: true, NY: false }. OMIT a key you are unsure about: no deadline is asserted for an unknown key, because assuming an extension tells a late filer they have months in hand."
    },
    "registered_in": {
      "type": "object",
      "additionalProperties": {
        "type": "boolean"
      },
      "propertyNames": {
        "minLength": 2,
        "maxLength": 2
      },
      "description": "Whether the company is already registered to do business in a state, e.g. { NY: false }. Drives obligations that only begin at registration."
    },
    "answers": {
      "type": "object",
      "additionalProperties": {
        "type": "boolean"
      },
      "description": "Answers to the yes/no threshold questions this tool asks, keyed by the threshold id shown in the question, e.g. { \"foreign-accounts-over-10k\": false, \"ny-sales-over-500k\": false }. Without this the same questions repeat forever and the obligations behind them can never resolve. Omit a key you genuinely do not know."
    },
    "detail": {
      "type": "string",
      "enum": [
        "brief",
        "summary",
        "full"
      ],
      "description": "Default 'brief': what applies, when it is due, and the questions, with no evidence or remediation detail. Around a third the length of 'summary' and it is what a founder can actually act on. 'summary' adds one check and one next step per item. 'full' adds every evidence tier, innocent explanation and remediation step and runs to several thousand words, so use it only when the user asks for that depth. Prefer staying brief and calling get_evidence_recipe or explain_obligation for the one or two items that actually matter."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

For one obligation, return exactly how to prove it: which sources settle the question, which are only corroborating, what each state's public registry does and does not expose, and the innocent explanations for missing evidence. Use this before concluding anything is missing.

{
  "type": "object",
  "properties": {
    "obligation_id": {
      "type": "string",
      "minLength": 1,
      "description": "Obligation id from list_compliance_obligations."
    }
  },
  "required": [
    "obligation_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Plain-English detail on a single obligation: what it is, why it exists, the deadline, the cost, the penalty, the exact remediation steps, and the government source.

{
  "type": "object",
  "properties": {
    "obligation_id": {
      "type": "string",
      "minLength": 1,
      "description": "Obligation id, e.g. 'de-registered-agent'."
    }
  },
  "required": [
    "obligation_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

START HERE for a books health check. Given whatever you know about a business, return the bookkeeping checks that apply to it, grouped by dimension, each with where to look, the innocent explanations to rule out first, and what it costs if it is real. Call it immediately with partial facts rather than interviewing the user first: unknown facts keep checks in the list rather than dropping them, so nothing is silently skipped. Cash-basis businesses correctly get a shorter list. This never says whether books are correct, only what to look at.

{
  "type": "object",
  "properties": {
    "company_name": {
      "type": "string",
      "maxLength": 120,
      "description": "Optional, and the only identifying thing this tool records. Median stores it to see which businesses use this tool and may follow up. It changes nothing about the answer, so omit it if the user has not agreed to share it. Send the business name only, never a balance, an account number or anything copied out of a document."
    },
    "ledger": {
      "type": "string",
      "enum": [
        "qbo",
        "xero",
        "other"
      ],
      "description": "Which ledger the books live in. Visible in the header of any export."
    },
    "basis": {
      "type": "string",
      "enum": [
        "cash",
        "accrual"
      ],
      "description": "Cash or accrual, printed at the top of most profit and loss reports. This matters more than anything else here: several revenue checks do not apply on a cash basis."
    },
    "processors": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40
      },
      "description": "Payment processors that hold a balance before paying out, e.g. ['stripe','paypal']. Names only. Drives the single most-missed check."
    },
    "bills_ahead": {
      "type": "boolean",
      "description": "Whether anything is billed ahead of delivery: subscriptions, retainers, annual plans."
    },
    "has_raised": {
      "type": "boolean",
      "description": "Whether the business has raised on a SAFE, note or priced round, or taken a loan."
    },
    "payroll_model": {
      "type": "string",
      "enum": [
        "own-payroll",
        "eor",
        "peo",
        "contractors-only",
        "none"
      ],
      "description": "How people are paid."
    },
    "has_contractors": {
      "type": "boolean",
      "description": "Whether 1099 contractors are paid."
    },
    "charges_sales_tax": {
      "type": "boolean",
      "description": "Whether sales tax is charged anywhere."
    },
    "needs_segment_reporting": {
      "type": "boolean",
      "description": "Whether any part of the business needs separate reporting: locations, programs, product lines, more than one entity."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Full detail on a single books health check: what it is, exactly where to look in the ledger, every innocent explanation to rule out before concluding anything, what it costs if it is real, what fixing it involves, and whether it is inside what Median does.

{
  "type": "object",
  "properties": {
    "check_id": {
      "type": "string",
      "minLength": 1,
      "description": "Check id from list_books_checks, e.g. 'rec-processor-balance-unreconciled'."
    }
  },
  "required": [
    "check_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Score a books health check from the statuses you actually evidenced. Returns the weighted score, the band, a per-dimension breakdown and the findings ranked worst first. Two rules a plain average does not give you: a confirmed critical caps the grade, and the band is WITHHELD entirely when too little was evidenced, because a flattering number off three checks is the part people quote. Report the withheld state rather than supplying a band yourself.

{
  "type": "object",
  "properties": {
    "company_name": {
      "type": "string",
      "maxLength": 120,
      "description": "Optional, and the only identifying thing this tool records. Median stores it to see which businesses use this tool and may follow up. It changes nothing about the answer, so omit it if the user has not agreed to share it. Send the business name only, never a balance, an account number or anything copied out of a document."
    },
    "ledger": {
      "type": "string",
      "enum": [
        "qbo",
        "xero",
        "other"
      ],
      "description": "Which ledger the books live in. Visible in the header of any export."
    },
    "basis": {
      "type": "string",
      "enum": [
        "cash",
        "accrual"
      ],
      "description": "Cash or accrual, printed at the top of most profit and loss reports. This matters more than anything else here: several revenue checks do not apply on a cash basis."
    },
    "processors": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40
      },
      "description": "Payment processors that hold a balance before paying out, e.g. ['stripe','paypal']. Names only. Drives the single most-missed check."
    },
    "bills_ahead": {
      "type": "boolean",
      "description": "Whether anything is billed ahead of delivery: subscriptions, retainers, annual plans."
    },
    "has_raised": {
      "type": "boolean",
      "description": "Whether the business has raised on a SAFE, note or priced round, or taken a loan."
    },
    "payroll_model": {
      "type": "string",
      "enum": [
        "own-payroll",
        "eor",
        "peo",
        "contractors-only",
        "none"
      ],
      "description": "How people are paid."
    },
    "has_contractors": {
      "type": "boolean",
      "description": "Whether 1099 contractors are paid."
    },
    "charges_sales_tax": {
      "type": "boolean",
      "description": "Whether sales tax is charged anywhere."
    },
    "needs_segment_reporting": {
      "type": "boolean",
      "description": "Whether any part of the business needs separate reporting: locations, programs, product lines, more than one entity."
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "check_id": {
            "type": "string",
            "minLength": 1
          },
          "status": {
            "type": "string",
            "enum": [
              "confirmed",
              "clear",
              "unresolved"
            ]
          }
        },
        "required": [
          "check_id",
          "status"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "description": "One entry per check you actually worked. Send check ids and statuses only: never figures, balances, account numbers or names."
    }
  },
  "required": [
    "results"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}