Ekklo

Use this when reading prospects. WHEN TO USE - This is the primary lead read tool, not customer CRM. COMMON MISTAKES - For fields to collect, answer without tools. EXAMPLES - {"method":"list","stage":"discovery"}

prospect_read

Use this when reading questionnaires, assessments (bilans), or client submissions. WHEN TO USE - This is the primary questionnaire read tool, not the writer. - pending = completed assessments awaiting review; overdue = clients late on a recurring bilan. - assignments accepts optional customer_id/questionnaire_id filters; copy assignment_id for submissions. COMMON MISTAKES - Do not write here — use save_questionnaire. EXAMPLES - {"method":"pending"}

questionnaire_read

Use this when writing appointments. WHEN TO USE - No id=create; id=patch; _delete:true deletes. - Read schedule_read(method=appointments,id=...). Echo expected_participant_ids, expected_participant_record_ids, expected_waitlist_entry_ids, even []. - cancel_many: appointments[]; max 20 reviewed IDs/snapshots/refund choices. Partial commits: check outcomes; reread failures. - refund_participant_ids: omit=credit policy; []=none; user IDs=credits. No card refund. - Group: is_group_class:true + coach-specified capacity > 0; ask if unknown; never guess. Omitted updates keep capacity. Individual capacity is optional. - recurrence_rule: create only; credits/email hit occurrence 1; send_email defaults false. COMMON MISTAKES - This is the primary RDV writer; blocks=save_calendar_event; sessions=save_program(schedule_session). EXAMPLES - {"client":"...","product":"...","start_time":"2026-06-16T10:00:00Z"}

save_appointment

Use this when writing autoflows, steps or client assignments. WHEN TO USE - This is the primary autoflow writer. - Create, then add_step(type, action_payload). COMMON MISTAKES - Read IDs with autoflow_read first. - Assignment needs client write access. EXAMPLES - {"method":"create_empty_assignment","customer_id":"<id>"}

save_autoflow

Use this when updating availability. Send ONE target. WHEN TO USE - This is the primary availability writer, not events. Targets: booking_rules (rules + 7 notification toggles); opening_hours (bookable per-weekday hours); calendar_settings (display window only); add/delete_exceptional_date (SpecialDay accepts time_slots[]). COMMON MISTAKES - Send one target object. - opening_hours = bookable hours; calendar_settings = display window only. EXAMPLES - {"method":"opening_hours","opening_hours":[{"day_of_week":"Monday","is_open":true,"time_slots":[{"start_time":"09:00","end_time":"18:00"}]}]}

save_booking_config

Use this when writing events: blocks, reminders, meetings, sessions, tasks. WHEN TO USE - This is the primary event writer, not the booker. Book a client RDV with save_appointment; a program session with save_program(schedule_session). Set calendar_id if the default calendar is read-only. Set create_meeting:true (+ email_receiver) to add a Google Meet link. - Repeating ("tous les vendredis pendant 3 mois"): event.recurrence_rule on create. COMMON MISTAKES - event_type=appointment is rejected here. - Timed creates need start/end. EXAMPLES - {"event":{"title":"Day off","event_type":"out_of_office"}} - {"event":{"title":"Bloc","event_type":"out_of_office","start_time":"2026-06-19T14:00:00+02:00","end_time":"2026-06-19T18:00:00+02:00","recurrence_rule":"FREQ=WEEKLY;COUNT=13"}}

save_calendar_event

Use this when inviting/updating customers. WHEN TO USE - update_customer routes here. This is the primary customer writer, not notes. - Before update/settings/resend, call customer_read(method="get", customer=...) and copy the returned etag into expected_etag. - Inviting emails the client by default. Say which channel you are using first; send_email:false returns a message to share instead. See learn_ekklo("clients"). COMMON MISTAKES - The notes field is the structured summary stored on the customer profile. Customer note records are created/updated with save_customer_note. EXAMPLES - {"method":"invite","email":"marie@example.com","first_name":"Marie","last_name":"Martin"} - {"method":"update","customer":"Marie","expected_etag":"W/\"...\"","notes":"Prefers morning sessions."}

save_customer

Use this when writing notes. WHEN TO USE - create_customer_note routes here. This is the primary note writer. - Call customer_read(method="notes", customer=...) first. Copy the customer customer_etag for create, or that note's note_etag for update/delete, into expected_etag. COMMON MISTAKES - Use customer text if id missing. EXAMPLES - {"method":"create","customer":"Marie","content":"Prefers mornings.","expected_etag":"W/\"...\""}

save_customer_note

Use this when updating establishment. WHEN TO USE - This is the primary establishment writer, not billing/FAQ. - method="profile" also edits coaching_goals/disciplines/starred_goals/starred_disciplines (omit=keep, []=clear). - Credits: method="credit_settings" configures the feature; "gift_credits" (customer + amount) ADDS credits; "adjust_credits" (customer + new_balance) SETS an exact balance. Whole numbers only. COMMON MISTAKES - Do not create FAQs here. - gift_credits adds to the balance; adjust_credits replaces it. Do not confuse them. EXAMPLES - {"method":"profile","profile":{"name":"Coach Paris"}} - {"method":"gift_credits","customer":"Marie","amount":10}

save_establishment

Use this when writing catalogue exercises. WHEN TO USE - This is the primary exercise writer; program prescriptions use save_program. - Before create, use training_read methods get_exercise_filter_options, list_repetitions and list_resistances. - Send one exercise with name, youtube_url, body_part, target_body_part, equipment, repetition_unit_id, resistance_unit_id and instructions. Unit IDs must be returned UUIDs. - youtube_url must be a real YouTube video (watch, youtu.be, embed or Shorts). If unavailable, ask the coach or reuse an existing catalogue exercise. COMMON MISTAKES - Never invent units, classifications or video URLs; uploads/images/other providers are unsupported. - No parallel partial creates. Fix every reported field before retrying; do not repeat the same failed call. - Update with exercise.id; omitted fields stay unchanged. EXAMPLES - {"method":"favorite","exercise":{"id":"<exercise_id>"}}

save_exercise

Use this when logging a client's habit on the coach's behalf (create, edit, or delete a habit log). WHEN TO USE - This is the primary habit-log writer, not the metric/measure logger (use save_metric_log for numbers) and not the reader. - CREATE: assignment_id + log_date + value (value is free text, e.g. "6", "8 glasses", "done"). UPDATE: id + changed fields. DELETE: id + _delete:true. - log_date accepts YYYY-MM-DD or ISO 8601, so you can backfill history. COMMON MISTAKES - Find assignment_id via customer_read(method='habit_assignments'); a log id via get_habit_logs. - For numeric measures (weight, body fat), use save_metric_log. EXAMPLES - {"assignment_id":"<id>","log_date":"2026-01-15","value":"8 glasses"}

save_habit_log

Use this when writing templates. WHEN TO USE - This is the primary template writer, not sender. COMMON MISTAKES - Do not save drafts unless asked. EXAMPLES - {"template":{"name":"Weekly check-in","content":"How was it?"}}

save_message_template

Use this when logging a client's metric / measure (mesure) on the coach's behalf (create, edit, or delete a numeric log). WHEN TO USE - This is the primary measure-log writer, not the habit logger (use save_habit_log for free-text habits) and not the reader. - CREATE: assignment_id + date + value (value is a number, e.g. 80.5 kg or 18 percent body fat). UPDATE: id + changed fields. DELETE: id + _delete:true. - date accepts YYYY-MM-DD or ISO 8601, so you can backfill history. - unit (optional): pass the RAW number + its unit (e.g. value:180, unit:"lb"); the server converts to canonical. Units: weight (kg/lb/lbs), length (cm/mm/m/in/ft). Do NOT convert yourself; omit if already canonical (kg/cm). COMMON MISTAKES - Find assignment_id via customer_read(method='metric_assignments'); a log id via get_metric_logs. - value must be numeric; for free-text habits use save_habit_log. EXAMPLES - {"assignment_id":"<id>","date":"2026-01-15","value":80.5}

save_metric_log

Use this when creating/editing the coach's reusable recipes or custom food items. WHEN TO USE - This is the primary nutrition LIBRARY writer (recipes + custom foods), not a client's meal plan (use save_nutrition_plan). - create_recipe ingredients each need a food_id from nutrition_library_read(search_food_items). - update/delete take recipe_id or food_item_id. COMMON MISTAKES - Do not invent or reuse a food_id across ingredients. EXAMPLES - {"method":"create_food_item","name":"Oats","calories":380,"proteins":13,"carbs":67,"fats":7}

save_nutrition_library

Use this when writing nutrition plans. WHEN TO USE - This is the primary writer; method OR plan. Read IDs/expected_etag; retry unchanged. - duplicate_plan: nutrition_plan_id/name, optional customer_id/context_relation_id; draft. - save_meal_template: meal/name; copy_meal_template: template_id. - adjust_to_target: customer_id. COMMON MISTAKES - Resolve homonyms. EXAMPLES - {"plan":{"name":"Cut"}} FIELD NOTES - equivalents[].item_type: Set recipe when using recipe_id. - food_items[].food_id, items[].food_id, items[].recipe_id: nutrition_library_read - food_items[].food_name, items[].food_name, items[].recipe_name: user/nutrition_library_read - food_items[].item_type, equivalents[].item_type, items[].item_type: Fixed list: food,recipe. - meal_id, meal_item_id, nutrition_plan_id: given/nutrition_plan_read - method: create_nutrition_plan add_day_to_nutrition_plan add_meals_with_food_items add_food_items_to_meal update_food_item_in_meal remove_food_item_from_meal add_equivalents_to_meal_item adjust_to_target copy_meal_template save_meal_template duplicate_plan - plan: Child id=stored UUID under its parent; omit for new/copy. food_id/recipe_id=catalogue UUID. - plan.customer_id: provided customer - target_calories: adjust_to_target: kcal/day - target_carbs, target_fats, target_proteins: adjust_to_target: g/day, optional - tolerance: adjust_to_target: percent, default 5

save_nutrition_plan

Use this when writing programs. WHEN TO USE - This is the primary writer; exercises use save_exercise. - program{}: no method; create title/type + is_template=true OR assign_to_customer_id. - Templates: duplicate_program(assign_to_customer_id,start_date); no assign_program. EXERCISE PREFLIGHT - Resolve exercise_name/variants: training_read(resolve_program_references). Ask the coach if ambiguous; use exact exercise_id. Unresolved=no writes. UNITS / VARIANTS - repetition_unit/resistance_unit: name/short/UUID; omit=defaults. Use training_read(list_repetitions/list_resistances). - variants[]: substitutions, not media_variant_id. Merge by id; omit=unchanged. COMMON MISTAKES - training_read(get_program_draft): exact parent IDs; new/copied nodes omit IDs. - Shared/team reads grant no writes; no denial retries. - create_program/create_full_program are not methods. EXAMPLES - {"program":{"title":"A","type":"cycle","is_template":true}} FIELD NOTES - method: duplicate_program publish_program assign_program schedule_session schedule_standalone_session add_session update_session delete_session duplicate_week copy_session add_circuit remove_circuit reorder_circuits add_exercise_to_session add_exercise_to_circuit remove_exercise update_repetitions restore_version - program: training_read ids - program.description, sessions[].description: ''=clear - exercises[].exercise_id: Catalogue UUID from training_read; not the session exercise id. - exercises[].exercise_name, variants[].exercise_name: user/training_read - exercises[].machine_settings: [{notes}]; non-empty replaces, []=clear - repetitions[].fields: RPE/RIR/band/any unit after load+reps; 4 fields max incl. load+reps, a unit once. unit=unit_id/name/library_key (rpe_level 1-10, rir 0-10, band_color, pace_min_per_km/time_s in s); value(+max_value) or option (list unit); empty=athlete fills. Update: omit=keep, []=clear - repetitions[].no_load: true=series without load (bodyweight, RPE-only) - repetitions[].repetition_unit: Coach unit by name/short/UUID (rep,secondes); omit=exercise default; list via training_read(list_repetitions) - repetitions[].resistance_unit: Coach unit by name/short/UUID (kg,%1RM); omit=exercise default; list via training_read(list_resistances) - repetitions[].tempo: Execution tempo: 4 slash-separated phases eccentric/pause-low/concentric/pause-high, e.g. 3/1/x/2 or 0/0/0/0. Use x only for explosive. Empty or 00/00/00/00 = no tempo. Do not use dashes. - exercises[].variants: Substitution variants (drop-set/beginner/alternative exercise), NOT media/image. Each = alternative exercise + its reps + an instructions reason. Merge by id; omit=unchanged. - variants[].exercise_id: Catalogue UUID from training_read; not the variant id. - variants[].instructions: When/why to use (e.g. 'For beginners', 'Drop set'). - circuits[].type: Valid values: monoset,superset,biset,triset,giantset,circuit,amrap,tabata,emom,fortime,separator. Classic use repeat=sets/rounds (biset/triset/giantset = 2/3/4 exercises). Timed modes amrap,tabata,emom,fortime are their OWN type — set the matching config.* (NOT a generic circuit). See learn_ekklo('sport'). - sessions[].estimated_duration: Seconds; pin with is_estimated_duration_override=true, else auto - sessions[].is_estimated_duration_override: true=pin stored duration, false=auto from circuits - sessions[].questionnaire_id: report_session questionnaire you own; ''=detach - program.type: Valid values: day,cycle. - program_id, session_id: training_read

save_program

Use this when writing leads. WHEN TO USE - This is the primary prospect writer, not customer writer. COMMON MISTAKES - Do not use save_customer for leads. EXAMPLES - {"first_name":"Alex","email":"alex@example.com"}

save_prospect

Use this when writing or reviewing questionnaires and assessments (bilans). WHEN TO USE - This is the primary questionnaire write tool, not the reader. - create then add_questions_bulk; assign needs customer_id + start_date + assignment_period. - create_submission fills a bilan on behalf of a client; update_submission/delete_submission edits/removes it. Answers are strings; media=https URL. COMMON MISTAKES - Read first with questionnaire_read to get current IDs (assignment_id, question_ids). - For create_submission, backdate with date (YYYY-MM-DD); no client notification is sent. - Number answers use the metric's canonical unit (kg weight, cm length) from questionnaire_read's 'unit', not the client's display unit. EXAMPLES - {"method":"create","title":"Bilan","type":"assessment"} - {"method":"create_submission","assignment_id":"<id>","answers":[{"question_id":"<qid>","answer":"72"}],"date":"2026-01-15"}

save_questionnaire

Use this when reading agenda. WHEN TO USE - This is the primary agenda read tool, not writer. available_slots = computed bookable instants for a prestation (product_id + start_date) — "when can I book service X?"; time_slots is the static config grid. - response_format="concise" for lists; "detailed" before save_calendar_event. - appointments + id reads one owned booking with mutation snapshots, credit payments/policy and refund receipts; bypasses date/list limits. COMMON MISTAKES - available_slots (bookable) is not time_slots (the grid). - Use bounded date ranges. EXAMPLES - {"method":"available_slots","product_id":"...","start_date":"2026-06-22"}

schedule_read

Find citable Ekklo documents by name or title, then use fetch(id). Matches literal substrings of 2-80 characters, returning up to eight owned clients, v2 training programs, nutrition plans and questionnaires per type. Empty or one-character queries return no matches. This is document search, not semantic search or operation discovery.

search

Use this when sending a message or managing a conversation. WHEN TO USE - This is the primary messaging writer, not read/template. - Send text (optionally a content_ref attachment or reply_to_id), OR set method to pin/unpin/edit/delete/mark_read, OR manage a group (create_group/rename_group/add_participants/remove_participant). - See learn_ekklo('messaging') for content_ref payloads and group flows. COMMON MISTAKES - Use provided customer/conversation text; no drafts. content_ref is a structured reference, never a file upload. EXAMPLES - {"customer":"Marie","content":"Confirmed."} - {"method":"pin","conversation_id":"..."}

send_message

Use this when reading sport/training data. WHEN TO USE - This is the primary sport read tool, not writer. - Use response_format="concise" for display-only program summaries; use "detailed" before save_program. - Before save_program uses exercise_name, call resolve_program_references for exact/ambiguous/missing IDs without confirmation. - Series fields (RPE, RIR, band...): get_program_draft(detailed) shows targets and unit_ids; get_session_report, execution_logs and get_exercise_progress show performed values. - To save a draft workout in the library, discover save_component_template. component_template_preview(program_id,draft_id,session_id,type,name,circuit_ids?) returns COMPLETE content, warnings and review_token; show them before coach agreement. component_templates is the inspection reader. COMMON MISTAKES - Do not mutate here. EXAMPLES - {"method":"resolve_program_references","queries":[{"reference":"squat"}]}

training_read