Using the Oak National Academy connector well

Oak is a curriculum resource: key stages, subjects, units, lessons and the assets, quizzes and transcripts attached to them. Most requests are about finding the right node in that structure and reading what it holds. Get the structure right first; everything else depends on it.

1. Confirm what you are working with

Before the first lookup, establish three things and say them to the user in one line:

• Connection. Oak was connected through sign-in. If a call fails with an authorisation or sign-in error, the connection has lapsed. Ask the user to reconnect Oak in their Claude settings and do not retry in a loop.
• Key stage and subject. Most curriculum tools are keyed by key stage and subject. If the user says "Year 8 maths", map it to the key stage first. If the user has not said which key stage or subject, ask once rather than guessing.
• Scope of the request. One lesson, one unit, a whole subject, or a comparison. The scope decides which tool you start with.

2. Choose the right tool level

Work down the hierarchy and stop at the level the user needs. Use the narrowest tool that answers the question.

Need	Start with
Broad orientation: what Oak covers, what a topic contains	explore-topic, browse-curriculum, get-curriculum-model
Which key stages, subjects, programmes exist	get-key-stages, get-programmes
Units within a subject	get-key-stages-subject-units, get-programmes-units
Lessons within a subject or unit	get-key-stages-subject-lessons
Material for one lesson	get-lessons-summary, get-lessons-quiz, get-lessons-transcript, get-lessons-assets
Assets or questions at subject or programme level	get-key-stages-subject-assets, get-key-stages-subject-questions, get-programmes-assets, get-programmes-questions
Concept links	get-keywords, get-keyword-graph, get-prior-knowledge-graph, get-misconception-graph
Recent content changes	get-changelog-latest, get-changelog

Rules of thumb:

• Do not pull every lesson in a subject to answer a question about one unit. Get the units, pick the one, then get its lessons.
• Use the graph tools (keyword, prior knowledge, misconception) only when the user wants sequencing or pupil-misunderstanding context. They are not needed for a simple lesson summary.
• fetch and download-asset retrieve a specific item you already have an identifier or link for. Do not use them to search.
• get-changelog-latest answers "has this changed recently?" Use it before telling a teacher that a resource is current.

3. Search and page without flooding context

Oak's listings can be long. Keep each call to what the next decision needs.

• Read the list of names or identifiers first, then open only the two or three items that are relevant.
• If a result is paginated, fetch the next page only when the first page does not contain what you need. Say how many items you have seen and how many more exist.
• Summarise long material (transcripts, full quizzes) rather than reproducing it. Quote a short phrase where a teacher needs exact wording.
• Keep a running list of the identifiers you have checked so you do not fetch the same lesson twice.

4. Handle empty results and access errors

• Empty result. Check the spelling and the key stage before concluding the content does not exist. Try the parent level (subject instead of unit) once. If still empty, say Oak does not appear to have material for that exact request and suggest the nearest match.
• Permission or access error. Report the error plainly, do not retry more than once, and do not invent the missing content. Say what you could not retrieve.
• Partial failure. If one lesson in a sequence fails, deliver the rest and list the gap by name.
• Rate limits. Slow down: batch the requests you need and reuse results you already hold.

5. Read-only by nature, with one rule

Oak's connector is used to read curriculum content. None of the listed tools is designed to change anything in Oak or in the teacher's school records. You do not need a change approval step for lookups. The one rule that still applies: if you are asked to save, send or share anything outside the conversation (a file, an email, a class page), do not do it from this connector. Produce the content in the conversation and let the user take it from there.

Common patterns and traps

• Assuming the key stage. "Year 5" and "KS2" overlap but are not identical in every case. Confirm which one the user means before you pull material.
• Mixing programmes with units. Programmes and key stage subject units are different structures. A programme can be the right answer for one school and the wrong one for another. Name which structure you used.
• Trusting a summary over the lesson. The summary is a guide. For a claim about what a pupil does in a lesson, check the lesson's own material before stating it.
• Pulling everything. Long lists fill context and bury the answer. Narrow the scope first.
• Treating empty as absent. An empty result at one level often means the wrong level was asked, not that nothing exists.
• Retrying a sign-in failure. Repeated calls will not fix a lapsed connection. Ask the user to reconnect.
• Quoting from memory. Oak content changes. For specific wording, unit names or lesson titles, read them from the connector in this conversation.

Output

Connection: <connected | access error: what it said>
Scope: <key stage, subject, unit or lesson checked>
Tools used: <names, in order>
Found: <what Oak holds for this request, with identifiers or titles>
Not found or not retrieved: <gaps, errors, pages not read>
Next step for the teacher: <one line>

Rules

• Do not invent Oak content, lesson titles, unit names or quiz questions. If it is not returned, say it was not found.
• Never reproduce whole transcripts or full quizzes unless the user asks; summarise and quote briefly.
• Do not retry a failed sign-in or authorisation call more than once. Ask the user to reconnect.
• Do not treat a changelog-empty result as proof that content is current; say what you checked.
• Do not save, send or share anything outside the conversation through this connector without the user's explicit yes.
• Do not include pupil names or personal data in any Oak call.

Done when

• The key stage, subject and scope are stated and match what the user asked.
• Every claim about Oak content traces to a tool result in this conversation.
• Gaps, errors and unread pages are listed under "Not found or not retrieved" rather than smoothed over.