Intent Spec — finance.book_tax_consultation

FULL ID:       finance.book_tax_consultation
VERSION:       v1.0.0
STATUS:        draft
LAST UPDATED:  2026-05-14
DOMAIN:        finance
PRIMARY AGENT: FinanceAgent
TTBS WEIGHTS:  time=0.20 taste=0.20 budget=0.20 safety=0.40

User books a Chartered Accountant (CA) or tax-practitioner consultation for personal or small-business income-tax matters. Covers ITR filing, TDS / TCS issues, capital-gains computation, foreign-income disclosures, advance-tax planning, GST queries (sole proprietor / freelancer), notices from the Income Tax Department, and rectifications. Distinct from generic financial advisory (which is broader wealth planning) and from will / estate planning. Partner exemplars: ClearTax, Quicko, TaxBuddy, H&R Block India, Vakilsearch, IndiaFilings, local CA networks aggregated through marketplaces.

SECTION 1 — INTENT IDENTITY

User wants to schedule a paid consultation with a qualified tax professional. Distinct from:

• finance.book_financial_advisor_session — broader wealth / portfolio advice not specific to tax
• finance.create_will_or_estate_plan — succession & estate, not taxation
• finance.invest_in_mutual_fund — transactional investing
• compliance.verify_kyc — document verification, not advice
• Generic legal consultation — out of scope; v1.1+ legal.book_lawyer_consultation

The professional MUST be one of: Chartered Accountant (CA, ICAI), Tax Return Preparer (TRP, CBDT empanelled), Cost Accountant (CMA) for indirect-tax matters, or Advocate practicing in tax. Bookkeepers / accounting clerks not qualified to advise on Income Tax Act provisions are rejected by ingest.

Single intent per case file. Recurring consultations (monthly bookkeeping retainers) route to v1.1+ finance.subscribe_tax_retainer.

SECTION 2 — NATURAL LANGUAGE COVERAGE

CLASSIFIES IN

• "Book a CA for ITR filing"
• "I got a notice from income tax, need help"
• "Tax consultant for capital gains on shares"
• "CA appointment this week, near Banjara Hills"
• "Help me file ITR-3 for freelance income"
• "I need to plan my advance tax payment"
• "Foreign salary tax, need a CA"
• "GST registration for my freelance business"
• "Best tax advisor for NRI returns"
• "Online tax filing consultation with a real CA"

CLASSIFIES OUT — BORDERLINE NO

• "Buy mutual funds" → finance.invest_in_mutual_fund
• "Make a will" → finance.create_will_or_estate_plan
• "Verify my PAN" → compliance.verify_kyc
• "Legal lawyer for property dispute" → out of scope v1
• "Audit my company books" → out of scope v1; statutory audit is a different engagement
• "Apply for a personal loan" → finance.apply_personal_loan
• "Investment advice" → finance.book_financial_advisor_session

MULTI-INTENT TRIGGERS

• "CA + will preparation" → finance.book_tax_consultation + finance.create_will_or_estate_plan
• "Capital gains advice + sell my old car for the capital loss" → finance.book_tax_consultation + marketplace.sell_used_car
• "Tax filing + new health insurance for 80D deduction" → finance.book_tax_consultation + finance.buy_health_insurance

SECTION 3 — INPUT (TOMO → PROVIDER)

{
  "intent": "finance.book_tax_consultation",
  "request_id": "req_01J9Z...",
  "user_locale": "en-IN",
  "user_currency": "INR",
  "user_location": { "lat": 17.4475, "lng": 78.3563, "city": "Hyderabad", "pincode": "500032" },
  "consultation_request": {
    "matter_kind": "itr_filing",                  // STRICT ENUM §6
    "tax_year_assessment": "2026-27",             // ISO assessment year string
    "user_persona": "salaried_individual",        // STRICT ENUM §6
    "estimated_income_band_inr": "10_to_25_lakh", // STRICT ENUM §6
    "complexity_signals": [                       // STRICT ENUM array §6
      "capital_gains_equity",
      "foreign_dividend"
    ],
    "has_notice": false,
    "notice_section": null,                       // e.g. "139(9)" when has_notice=true
    "preferred_mode": "video",                    // STRICT ENUM §6
    "preferred_language": "en",                   // STRICT ENUM §6
    "preferred_slot_window": {
      "start": "2026-06-01T09:00:00+05:30",
      "end":   "2026-06-05T20:00:00+05:30"
    },
    "preferred_duration_minutes": 45,
    "preferred_gender_of_professional": "no_preference"
  },
  "ttbs_user_band": {
    "time":   "balanced",
    "taste":  "balanced",
    "budget": "good",
    "safety": "great"
  },
  "session_context": { "tomo_session_id": "ses_01J9Z...", "user_dna_hash": "dna_v3_a7c9..." }
}

Anti-fabrication preamble: Provider may not list a non-ICAI / non-CBDT-empanelled professional as a "CA." Credential mis-statement is per-se ingest rejection. TOMO does not surface raw income — only band. Partner cannot quote a higher fee in response to a higher income band; matching is by complexity not income.

SECTION 4 — PROVIDER TOOLS

Tool 1: search_tax_professionals

PURPOSE:      Up to 20 candidate professionals matching matter_kind + persona + slot window + language
SLA:          p50 ≤ 600ms, p95 ≤ 1800ms, p99 ≤ 4000ms
RATE LIMIT:   60 req/min
IDEMPOTENCY:  request_id; 90s cache (calendar availability volatile)
RETRY:        1 on 429, 2 on 5xx

Tool 2: get_professional_detail

PURPOSE:      Full profile + bio + ICAI registration + reviews + sample work product
SLA:          p50 ≤ 400ms, p95 ≤ 1200ms
RATE LIMIT:   120 req/min
IDEMPOTENCY:  professional_id; 24h cache (profile is stable)
RETRY:        1 on 5xx

Tool 3: hold_slot

PURPOSE:      Soft-lock a calendar slot for 10 minutes while user confirms
SLA:          p50 ≤ 700ms, p95 ≤ 2000ms
RATE LIMIT:   30 req/min
IDEMPOTENCY:  request_id; same id returns same hold
RETRY:        No retry on hold creation

Tool 4: confirm_booking

PURPOSE:      Convert hold → confirmed booking + create video link / address + payment lock
SLA:          p50 ≤ 1200ms, p95 ≤ 3500ms
RATE LIMIT:   30 req/min
IDEMPOTENCY:  request_id
RETRY:        No retry

Tool 5: cancel_booking

PURPOSE:      Cancel + compute pro-rated refund per published policy
SLA:          p50 ≤ 800ms, p95 ≤ 2500ms
RATE LIMIT:   30 req/min
IDEMPOTENCY:  booking_id
RETRY:        1 on 5xx

Tool 6: submit_documents_pre_consultation

PURPOSE:      Encrypted upload (Form 16, AIS, 26AS, capital gains statement) ahead of session
SLA:          p50 ≤ 1500ms, p95 ≤ 5000ms (file dependent)
RATE LIMIT:   10 uploads / booking
IDEMPOTENCY:  booking_id + content hash
RETRY:        1 on 5xx

SECTION 5 — RESPONSE SHAPE

TaxProfessional

TaxProfessional:
  professional_id: { type: string, constraint: REQUIRED, opaque }
  full_name: { type: string, constraint: REQUIRED }
  credentials:
    primary: { type: enum, constraint: REQUIRED, STRICT ENUM §6, values: [CA_ICAI, CMA_ICAI, advocate_tax, TRP_CBDT] }
    icai_membership_number: { type: string, constraint: REQUIRED, semantics: "Verifiable on icai.org for CA/CMA; bar council for advocate; CBDT TRP id for TRP" }
    years_of_practice: { type: int, constraint: REQUIRED, ≥0 }
    additional_certifications: { type: array<enum>, constraint: REQUIRED, STRICT ENUM §6, may be empty }

  specialties: { type: array<enum>, constraint: REQUIRED, STRICT ENUM §6, may NOT be empty }
  languages_spoken: { type: array<enum>, constraint: REQUIRED, STRICT ENUM §6, may NOT be empty }
  modes_supported: { type: array<enum>, constraint: REQUIRED, STRICT ENUM §6, values from preferred_mode }

  fee_inr:
    base_consultation_inr: { type: int, constraint: REQUIRED, INR_INTEGER, ≥0 }
    per_extension_15min_inr: { type: int, constraint: REQUIRED, INR_INTEGER, ≥0 }
    gst_inr: { type: int, constraint: REQUIRED, INR_INTEGER, ≥0, semantics: "18% on professional fees" }
    total_first_session_inr: { type: int, constraint: REQUIRED, INR_INTEGER }

  rating:
    average_score: { type: float, constraint: REQUIRED, 0.0-5.0 }
    review_count: { type: int, constraint: REQUIRED, ≥0 }
    response_time_minutes_median: { type: int, constraint: REQUIRED, ≥0 }
    completion_rate_pct: { type: float, constraint: REQUIRED, 0-100 }

  city: { type: string, constraint: REQUIRED }
  state: { type: enum, constraint: REQUIRED, STRICT ENUM §6 (state codes) }
  in_person_available: { type: boolean, constraint: REQUIRED }
  in_person_address: { type: string, constraint: REQUIRED, semantics: "Empty string when in_person_available=false" }

  available_slots:
    type: array<object>
    constraint: REQUIRED, may NOT be empty (otherwise omit professional)
    shape:
      slot_id: { type: string, constraint: REQUIRED }
      starts_at: { type: string, constraint: REQUIRED, ISO_DATETIME }
      ends_at: { type: string, constraint: REQUIRED, ISO_DATETIME }
      mode: { type: enum, constraint: REQUIRED, STRICT ENUM §6 }

  partner_reference:
    source: { type: string, constraint: REQUIRED }
    deeplink: { type: string, constraint: REQUIRED, HTTPS URL }

SlotHold

SlotHold:
  hold_id: { type: string, constraint: REQUIRED }
  professional_id: { type: string, constraint: REQUIRED }
  slot_id: { type: string, constraint: REQUIRED }
  hold_expires_at: { type: string, constraint: REQUIRED, ISO_DATETIME, semantics: "≥10 minutes ahead of hold creation" }
  fee_locked_inr: { type: int, constraint: REQUIRED, INR_INTEGER }

ConfirmedBooking

ConfirmedBooking:
  booking_id: { type: string, constraint: REQUIRED, immutable }
  professional_id: { type: string, constraint: REQUIRED }
  professional_name: { type: string, constraint: REQUIRED }
  starts_at: { type: string, constraint: REQUIRED, ISO_DATETIME }
  ends_at: { type: string, constraint: REQUIRED, ISO_DATETIME }
  mode: { type: enum, constraint: REQUIRED, STRICT ENUM §6 }
  meeting_url: { type: string, constraint: REQUIRED, HTTPS URL, semantics: "Empty string when mode=in_person" }
  in_person_address: { type: string, constraint: REQUIRED, semantics: "Empty string when mode≠in_person" }
  fee_paid_inr: { type: int, constraint: REQUIRED, INR_INTEGER }
  invoice_url: { type: string, constraint: REQUIRED, HTTPS URL }
  rescheduling_policy:
    free_reschedules_remaining: { type: int, constraint: REQUIRED, ≥0 }
    cutoff_hours_before_session: { type: int, constraint: REQUIRED, ≥0 }
  cancellation_policy:
    full_refund_until: { type: string, constraint: REQUIRED, ISO_DATETIME }
    partial_refund_until: { type: string, constraint: REQUIRED, ISO_DATETIME }
    partial_refund_pct: { type: int, constraint: REQUIRED, 0-100 }
  documents_submission_url: { type: string, constraint: REQUIRED, HTTPS URL }

CancellationResult

CancellationResult:
  booking_id: { type: string, constraint: REQUIRED }
  cancelled_at: { type: string, constraint: REQUIRED, ISO_DATETIME }
  refund_amount_inr: { type: int, constraint: REQUIRED, INR_INTEGER, ≥0 }
  refund_method: { type: enum, constraint: REQUIRED, STRICT ENUM §6, values: [original_payment, bank_transfer] }
  refund_eta_days: { type: int, constraint: REQUIRED, 0-15 }
  cancellation_fee_inr: { type: int, constraint: REQUIRED, INR_INTEGER, ≥0 }

FORBIDDEN FIELDS

• paid_placement_score, ad_bid, sponsored_rank, promotion_priority, referral_kickback
• editor_pick, tomo_recommended, top_choice, featured_professional
• commission_padded_fee, partner_revenue_share
• ai_generated_professional_photo — professional headshots must be real, verified at onboarding
• inflated_years_of_practice, inflated_review_count
• urgency_text ("Slots filling fast — book now") unless available_slots.length ≤ 2
• client_real_names in testimonials — must be initials only
• success_guarantee_text ("Save ₹50,000 guaranteed!") — tax outcomes are case-specific; forbidden

SECTION 6 — CONTROLLED VOCABULARIES

consultation_request.matter_kind:
  values:
    itr_filing:                    "Income-tax return filing"
    notice_response:               "Response to IT Department notice"
    capital_gains:                 "Capital gains computation & planning"
    foreign_income:                "Foreign income / DTAA / Schedule FA"
    tds_tcs:                       "TDS / TCS dispute or correction"
    advance_tax_planning:          "Advance tax estimation"
    presumptive_taxation:          "44AD / 44ADA / 44AE consultation"
    business_tax:                  "Sole-prop / LLP / partnership taxation"
    gst_freelancer:                "GST for individual professional"
    rectification_142_154:         "Rectification or revision filing"
    refund_followup:               "Refund delay / mismatch query"
    general_planning:              "Annual planning, deductions, exemptions"

consultation_request.user_persona:
  values: [salaried_individual, freelancer, business_owner_sole_prop, partner_in_firm, director_in_company, nri, senior_citizen, hni, first_time_filer]

consultation_request.estimated_income_band_inr:
  values:
    under_5_lakh, 5_to_10_lakh, 10_to_25_lakh, 25_to_50_lakh,
    50_to_1_crore, 1_to_2_crore, above_2_crore
  resolution_order: "Partner sees ONLY band; raw income transmitted to professional only after booking confirmation."

consultation_request.complexity_signals:
  values:
    capital_gains_equity, capital_gains_property, capital_gains_crypto,
    foreign_dividend, foreign_salary, dtaa_applicability, esop_taxation,
    schedule_fa_filing, multiple_form_16, business_income, freelance_44ADA,
    presumptive_44AD, gst_combined, hra_house_loan_combined,
    section_54_54F_reinvestment, ltcg_grandfathering, dividend_above_5k,
    crypto_vda_section_115BBH

consultation_request.preferred_mode / modes_supported / ConfirmedBooking.mode:
  values:
    video:     "Video call (Zoom / Google Meet / partner-hosted)"
    audio:     "Voice call"
    in_person: "Office or home visit"
    chat:      "Async chat with response SLA"

consultation_request.preferred_language / languages_spoken:
  values: [en, hi, te, ta, kn, ml, mr, bn, gu, pa, or, as, ur]

TaxProfessional.credentials.primary:
  values:
    CA_ICAI:        "Chartered Accountant, ICAI member"
    CMA_ICAI:       "Cost Accountant, ICAI of CMA"
    advocate_tax:   "Advocate enrolled with Bar Council, practising tax"
    TRP_CBDT:       "Tax Return Preparer empanelled by CBDT"

TaxProfessional.specialties:
  values: (subset of consultation_request.matter_kind)

state:
  values:
    AP, AR, AS, BR, CG, GA, GJ, HR, HP, JH, KA, KL, MP, MH, MN, ML, MZ, NL, OD,
    PB, RJ, SK, TN, TS, TR, UP, UK, WB,
    AN, CH, DN, DD, DL, JK, LA, LD, PY

CancellationResult.refund_method:
  values: [original_payment, bank_transfer]

SECTION 7 — TTBS DIMENSIONS

TIME (weight = 0.20):
  signals_used:
    - available_slots earliest start vs preferred_slot_window.start
    - response_time_minutes_median (lower preferred)
    - modes_supported includes preferred_mode
  weighting:
    earliest_slot_fit: 0.55
    response_time: 0.30
    mode_match: 0.15
  user_band_handling:
    fast: prefer next-24h slots even at +30% fee
    balanced: standard
    flexible: relax to 7-day window for lower fee

TASTE (weight = 0.20):
  signals_used:
    - languages_spoken intersection with preferred_language
    - past consultation with same professional (DNA)
    - rating.average_score
    - specialty exact match with matter_kind
  weighting:
    language_match: 0.30
    dna_repeat: 0.30
    rating: 0.20
    specialty_match: 0.20

BUDGET (weight = 0.20):
  signals_used:
    - fee_inr.total_first_session_inr
    - fee_inr.per_extension_15min_inr (signals risk of overflow)
  weighting:
    total_first_session: 0.80
    extension_rate: 0.20
  user_band_handling:
    ok:    cheapest passing safety floor (credentials verified)
    good:  balanced fee vs rating
    great: senior practitioner regardless of fee

SAFETY (weight = 0.40):
  signals_used:
    - credentials.primary in [CA_ICAI, CMA_ICAI, advocate_tax, TRP_CBDT]
    - credentials.icai_membership_number verifiable
    - credentials.years_of_practice ≥3 (floor)
    - rating.completion_rate_pct ≥90
    - response_time_minutes_median ≤120 for non-urgent
    - complexity_signals matched by specialties
  weighting:
    credentials_verified: 0.40
    years_practice: 0.20
    completion_rate: 0.15
    complexity_match: 0.15
    response_time: 0.10
  user_band_handling:
    fast: relax years_practice floor to 1
    balanced: floor 3 years
    great: floor 10 years + only CA_ICAI or advocate_tax

Locked weights: time 0.20 / taste 0.20 / budget 0.20 / safety 0.40. Safety dominates because mis-advice on tax has Income-Tax Act consequences for the user. Budget is moderate — fees vary 2-5× but quality variance is greater than cost variance.

SECTION 8 — COMPLETION CONTRACT

POST /api/v1/cpc/mcp_provider/<your_partner_id>
Body:
{
  "intent":           "finance.book_tax_consultation",
  "external_id":      "<booking_id>",
  "request_id":       "<request_id>",
  "amount_inr":       300,    // NET partner commission only — typically 15-30% of professional fee
  "gst_inr":          54,
  "tips_inr":         0,
  "pass_through_inr": 1500,   // fee remitted to the professional
  "closed_at":        "2026-06-02T17:30:00+05:30",
  "status":           "completed",
  "matter_kind":      "itr_filing",
  "mode":             "video",
  "duration_minutes": 45,
  "professional_credential": "CA_ICAI"
}

Important: User pays the full fee (e.g. ₹1,500). Partner's NET commission (~₹300) is the only amount_inr. Professional's share rides in pass_through_inr. TOMO charges 10% × ₹300 = ₹30. HMAC-SHA256 canonical body, 5-min replay window.

Follow-up sessions for the same matter ID file a new completion with the same external_id_root and a session-counter suffix. No automatic retainer billing — every session is explicit.

SECTION 9 — WIDGET

TaxConsultationWidget (planned). Interim: ProfessionalListingWidget.

Field mapping:
  - full_name + credentials.primary pill (e.g. "CA, ICAI")
  - years_of_practice → "12 yrs practice"
  - specialties → chip row (top 3 visible, "+N more")
  - rating.average_score + review_count → star pill
  - fee_inr.total_first_session_inr → big price
  - available_slots earliest → "Next: Tue 11 AM"
  - languages_spoken intersection with user pref → language chip
  - in_person_available → location pill (with city)
  - response_time_minutes_median → "Responds in ~30 min" pill

SECTION 10 — CACHING POLICY

SECTION 11 — ERROR CODES

SECTION 12 — SANDBOX → PRODUCTION CHECKLIST

[ ] All six tools implemented
[ ] At least 25 verified professionals in catalog covering matter_kind set
[ ] Every CA_ICAI / CMA_ICAI membership number verifiable on icai.org
[ ] Every advocate_tax bar-council number verifiable
[ ] Every TRP_CBDT id verifiable on CBDT empanelment list
[ ] No bookkeeper / accounting-clerk in catalog
[ ] Languages spoken validated against actual session-recording samples
[ ] Income-band only exposed; raw income never leaves TOMO until booking confirmed
[ ] Cancellation policy publishes free_refund_until + partial_refund details before payment
[ ] Cancellation refund tested end-to-end on test booking
[ ] HMAC signing verified on test CPC webhook
[ ] amount_inr in CPC is COMMISSION (NET), pass_through_inr is professional fee
[ ] All controlled vocabularies respected
[ ] No forbidden fields anywhere
[ ] SLA p95 met (100-call sandbox run)
[ ] GSTIN, privacy policy URL, grievance officer contact uploaded
[ ] Document-upload endpoint encrypts at rest (KMS or equivalent)
[ ] Video link generation uses partner-owned or industry-standard provider
[ ] Customer support: dedicated tax-consultation helpline + email
[ ] Professional onboarding pipeline reviewed (TOMO admin spot-checks 5 random profiles)

SECTION 13 — ANTI-FABRICATION RULES

RULE 1: Professional credentials must be verifiable on the issuing authority's
        public register (ICAI for CA / CMA, State Bar Council for advocate,
        CBDT for TRP). Partners falsely listing credentials = immediate
        suspension. TOMO spot-checks 10% of new listings quarterly.

RULE 2: No paid_placement, ad_bid, sponsored_rank, "featured professional"
        sections that bypass TTBS. Tax advice influenced by commission
        structures is customer-harm.

RULE 3: years_of_practice must reflect actual ICAI / Bar enrolment date.
        Inflated years = suspension. TOMO audits via membership-issuance year.

RULE 4: rating.average_score must be unrounded over the past 12 months of
        real sessions. No "rounded to 4.8 for marketing." TOMO computes a
        shadow score from CPC ledger; >0.4 delta = audit.

RULE 5: review_count must be from completed paid sessions only — not
        signup interest, not free chats, not partner-internal staff.

RULE 6: No success_guarantee text. Tax outcomes depend on facts;
        guaranteeing "you'll save ₹X" is per-se misleading and forbidden.

RULE 7: Client testimonials must use initials only ("R.K.") and cannot
        disclose tax-return specifics (no "saved ₹X via 80C/80D moves").

RULE 8: AI-generated headshots / fake bios forbidden. Onboarding photo +
        government ID required; verified at partner side, sample audited.

RULE 9: Professional cannot quote a fee variant based on the user's
        estimated_income_band. Fees are matter-complexity-priced, not
        income-priced. TOMO ingest scans for income-band-conditional pricing.

RULE 10: Partner cannot promote one professional to multiple matter_kind
         slots they're not specialised in. Specialty list must be the
         professional's declared specialisation, not partner-set keyword bag.

RULE 11: amount_inr in CPC webhook is COMMISSION ONLY. Total fee remitted
         to the professional is pass_through_inr. Partners reporting full
         fee as commission to inflate base = suspension + accounting audit.

RULE 12: notice_section in input is private. Partner MUST NOT cache or
         resell. Notice details are sensitive; TOMO sees partner data-handling
         logs on SOC2 audit.

RULE 13: Audio / video session recordings (if any) belong to the user.
         Partner may not use recordings for training models, marketing, or
         resale. Consent must be re-collected per session, not click-wrap'd
         at signup.

RULE 14: completion_rate_pct must be computed from CPC ledger over past
         90 days. Partners hiding cancellations from CPC = suspension.

RULE 15: Information-completeness score (hidden rank factor weight 0.10)
         rewards full §5 shape. Sparse responses (missing specialties /
         languages / credentials) rank lower automatically.

VERSION HISTORY

v1.0.0 — 2026-05-14 — Initial spec. CA / CMA / advocate-tax / TRP only;
                       bookkeepers rejected by ingest. Income-band only
                       to partner — raw income gated until booking confirmed.
                       Safety-dominant TTBS (0.40) reflecting consequences of
                       mis-advice under Income Tax Act. Net-commission base
                       in §8. ICAI / Bar / CBDT register verification required
                       at onboarding and audited quarterly.