ielts-study-plan

IELTS Buddy Study Data Interface

This Skill only describes the study data interface. Before calling, first followAgent API Configurationto bind and check the capabilities actually available to the current account.

Interface

Capability group	Data or action	Call constraints
ielts_study_plans_list、ielts_study_plans_get	Read plans and complete tasks	Use the returned exact planId, task ID, and revision; do not guess IDs; the next item is chosen by the caller based on facts.
ielts_courses_search_sections、ielts_practice_search_parts、ielts_dictation_search_materials、ielts_mock_search_papers	Discover the exact content and stable contentRef	that can be written to a plan; the content is chosen by the caller; the server only returns factual candidates.
ielts_study_plans_create	Create a plan from selected tasks	Each task must include the server-returned contentRef, a China calendar date, and morning、afternoon or evening time slot.
ielts_study_plans_update、ielts_study_plans_change_tasks、ielts_study_plans_replan、ielts_study_plans_delete	Modify title/goal, atomically add, modify, or delete completed tasks, reschedule incomplete tasks, or delete a plan	Read the plan before writing;change_tasks is not a partial plan patch,replan replaces incomplete tasks as a whole.
ielts_notifications_get_status、ielts_notifications_configure_wechat_task_reminders	Read WeChat iLink status, enable or disable WeChat delivery for existing tasks	Pass only the exact taskId; the reminder tool does not create tasks, nor modify dates or time slots.
ielts_learning_route_read、ielts_learner_read_profile、ielts_learning_pull_events	Learning paths, profiles, and historical facts	For paths use view:"route" or view:"progress"; keep missing fields unknown, do not fabricate data.
ielts_assets_search、ielts_resources_related、ielts_prep_search_guides、ielts_prep_read_guide、ielts_prediction_search_hits	User assets, exam preparation content, exam room records, candidate questions, and related resources	Keep exam room records and candidate questions layered; use only server-returned records,contentRef and optional links.
ielts_learning_push_events	Record study events that have occurred and have evidence	Do not write suggestions, drafts, or inferences as events.

python3 scripts/ielts_buddy_api.py capabilities
python3 scripts/ielts_buddy_api.py call ielts_study_plans_list --json '{}'

Boundaries

• The plan's goals, priorities, and task content are decided by the caller and the user; the server only stores confirmed data.
• When describing a saved plan, base it on the actual tasks, dates, time slots, durations, and statuses most recently returned by the interface; do not present drafts or speculation as saved facts; only claim creation or modification after the write interface succeeds; paginated results do not represent the complete plan; when existing results are sufficient, there is no need to query repeatedly.
• contentRef only accepts practice_part、mock_paper、course_section or listening_dictation; directly reuse the object returned by the catalog tool, do not manually complete content snapshots.
• To modify a plan title or goal use update; to change specific tasks use change_tasks; to replace incomplete arrangements as a whole use replan, do not mix them.
• workflows/ is an independent optional recommendation layer and is not part of this Skill's interface contract.

Lists and details

Querying study records takes two steps: first read the list summary, then as needed use the returned reviewTarget to call ielts_review_read_snapshot to view the details of a practice session or a completed mock exam subject; for intensive listening use attemptId to call ielts_dictation_read_attempt, for unsubmitted regular practice use sessionId to call ielts_practice_read_session. Do not expand details one by one just to list records. Before use, rely on the current account's capabilities.

In the list, sessionId is the practice count,partId is the distinct passage; distinguish zero answers, answered but not submitted, and submitted, and do not infer an IELTS score from the accuracy of partial questions. When a complete record is needed, paginate by nextOffset、nextCursor or nextPage until hasMore=false; when an empty page has a subsequent cursor, you still need to continue.observationTruncated=true or coverage.sourceTruncated=true indicates the data is still incomplete, and you must not claim to have retrieved everything. The plan list contains only summaries; use planId to call ielts_study_plans_get to get the task page.

Footprint and learning statistics

Cross-product activity uses ielts_footprints_list. Directly reading the server-side summary、dailyCounts、todayCounts and total；activities only covers this page; its length or date distribution cannot be used to recalculate historical totals, heatmaps, streaks, or this week's counts. When only querying statistics, there is no need to pull the entire timeline.

For footprints, preferentially use nextCursor as-is as the cursorof the next request, keeping kinds/query/timeRange unchanged. The statistics scope is statisticsScope=filtered_history, the time zone is Asia/Shanghai, and the daily counts cover the 28 days up to the day of asOf . Video progress for the same chapter on the same day is collapsed into one display activity, while the raw events are retained.

ielts_learning_pull_events synchronizes raw learning evidence; the numeric cursor and the footprint's string cursor are not interchangeable, and their item counts should not be compared directly. When the webpage does not show records, first check pagination and coverage scope, and do not use ielts_learning_push_events to backfill facts that already exist. When missing fields or coverage.sourceTruncated=true are returned, maintain the conclusion of "incomplete", and rely on the currently deployedfootprint API documentation.