Compras Divididas MCP

Critical rules

• Send amount as a 2-decimal string ("120.50"), never as a float.
• For recurrence operations, always use a 50/50 split with split_config={"mode":"equal"}.
• Send external_id for WhatsApp/integration events to enable safe deduplication.
• Do not guess participant_id; discover it with list_participants before creating movements.
• Send occurred_at when backfilling history; if omitted, the API uses the current timestamp in America/Sao_Paulo.
• Create refunds only with an original purchase reference (original_purchase_id or original_purchase_external_id).
• Keep post-tool messages direct, in Portuguese, and with emoji.
• Template compliance is mandatory: select exactly one template variant for the executed tool (success, error, or empty) and only replace placeholders.
• Do not add headings, explanations, JSON dumps, tool traces, or any extra lines before/after the template output.

Intent mapping for installment shorthand

• Treat installment expressions as recurrence creation (create_recurrence), not as one-off purchases (create_movement).
• Supported shorthand patterns:
  • <description> <amount> <installments>x (example: Smartphone 500 12x)
  • <description> <amount>x<installments> (example: Smartphone 500x12)
• Parsing rules:
  • description: text before the amount token.
  • amount: installment amount, normalized to a 2-decimal string ("500.00").
  • installments: integer after x; when installments >= 2, create a fixed-duration recurrence.
• Recurrence payload construction for shorthand:
  • start_competence_month: month provided by user; otherwise current competence month.
  • end_competence_month: start_competence_month + installments - 1 months (inclusive).
  • reference_day: explicit day from user; otherwise current day in America/Sao_Paulo.
  • split_config: always {"mode":"equal"}.
• Only use create_movement for these patterns when the user explicitly asks to register a single purchase.

Recommended sequences

Register a purchase

1. Call list_participants and map the sender to requested_by_participant_id.
2. Call create_movement with type="purchase", amount, description, and external_id (when available).
3. Persist the returned id to make future refunds easier.

Register a recurrence

1. Call list_participants and map valid participant IDs.
2. Call create_recurrence with description, amount, payer_participant_id, requested_by_participant_id, split_config={"mode":"equal"}, reference_day, and start_competence_month.
3. Optionally include end_competence_month for fixed-duration recurrences.
4. Confirm status=active and keep the returned recurrence id for future lifecycle operations.

Manage recurrence lifecycle

1. Call list_recurrences with optional filters (status, year, month, limit, offset) to locate target rules.
2. Call edit_recurrence to update fields (for example amount, description, reference_day) while keeping split_config={"mode":"equal"}.
3. Use clear_end_competence_month=true in edit_recurrence when you need to remove an existing end month.
4. Call end_recurrence to end a recurrence logically (status transition to ended), optionally passing end_competence_month.

Register a refund without a purchase_id

1. Call list_movements with year, month, and filters (type="purchase", amount, description, participant_id, external_id) to locate the purchase.
2. Prefer original_purchase_id when it is available.
3. Use original_purchase_external_id when the purchase_id is not available and the external identifier is trustworthy.

Close the monthly reconciliation

1. Call get_monthly_summary with auto_generate=true to validate the partials.
2. Call get_monthly_report with auto_generate=true for the on-demand consolidated view (same response schema).
3. Communicate transfer.amount, transfer.debtor_participant_id, and transfer.creditor_participant_id.

Auto-generate recurrent entries before consultation

1. Always call get_monthly_summary and get_monthly_report with auto_generate=true.
2. Do not use auto_generate=false in this skill.

Detailed reference

Read references/api_reference.md for the full contract for each tool:

• required and optional parameters
• validations and limits
• response format
• common errors and corrective action

Read references/response_templates.md to format every post-tool answer:

• one success template and one failure template per tool
• direct PT-BR text with emojis
• placeholders with deterministic filling rules
• mandatory output contract for every tool response

Response formatting policy

• Never answer raw JSON after using a tool.
• Always convert the result to the corresponding PT-BR template.
• Keep at most 3-6 lines when possible.
• Include only actionable fields (IDs, values, competence month, transfer).
• Respect the template line order and labels exactly as documented.
• If a placeholder value is missing, apply the fallback rules in references/response_templates.md instead of inventing new wording.