skills(experimental): fix VARIANT accessors + ai_query error field in databricks-ai-functions

[malcolndandaro]

Summary

Eval-driven improvement of the databricks-ai-functions (experimental) skill. I ran the skill through a full SkillForge L1–L5 evaluation (7 ground-truth cases, WITH-vs-WITHOUT controlled experiment), found that the skill was making the agent worse than no skill on three cases, diagnosed the root cause of each against the live Databricks docs, and fixed them. All corrections reconcile the skill to its own canonical reference content and the official function docs.

What the eval found (baseline): L5 Output 0.53, with 5 regressions across 3 cases (the skill steered the agent to wrong output that it got right without the skill):

Case	Root cause in the skill
ai_parse_document	Internal contradiction — the documented output-schema tree shows document:{pages, elements} + error_status, but the example queries used parsed:pages[*].elements[*].content / parsed:error. The agent noticed the conflict, stopped to verify against docs, and ran out of turns before answering.
ai_extract	Body taught the legacy ARRAY(...) → STRUCT → dot access while the reference said it returns a VARIANT; nothing warned that dot notation returns NULL silently on a VARIANT. The agent produced a confused hybrid.
ai_query (failOnError => false)	The skill described the returned struct's error field as .error in several places; the docs confirm it is errorMessage.

What changed:

1. ai_parse_document accessors — corrected examples to parsed:document:pages / parsed:document:elements / parsed:error_status (colon-notation), matching the schema tree, references/4, and the ai_parse_document docs. (SKILL.md Pattern 3 + references/1)
2. ai_extract VARIANT access — standardized on the JSON-string schema, colon-notation access (result:response:field), and an explicit "dot notation returns NULL on a VARIANT — always use colon" note. (SKILL.md Quick Start + references/1)
3. ai_extract version distinction — added a concise note that the current form (JSON-string schema) is v2.1 → returns a VARIANT (not a STRUCT), vs the legacy ARRAY(...) → STRUCT form. (references/1)
4. ai_query error field — corrected .error → .errorMessage (the failOnError => false struct is {response, errorMessage} per the ai_query docs). (SKILL.md + references/2 + references/4)

Result (clean re-eval): all 3 regressing cases now POSITIVE (ai_extract, ai_parse_document, ai_translate → WITH-skill 1.0); needs_skill gaps 5 → 1; positives 22 → 29; L5 Output 0.53 → ~0.58–0.61. Fix #4 (ai_query field name) is a docs-confirmed mechanical correction that directly targets the one remaining regression + needs_skill.

Scope: prose only — SKILL.md + 3 references/*.md. No frontmatter / name / description change, so agents/openai.yaml and manifest.json are unaffected. eval/ artifacts are intentionally not committed (consistent with the rest of the repo).

Documentation safety checklist

• Examples use least-privilege permissions (no unnecessary ALL PRIVILEGES, admin tokens, or broad scopes)
• Elevated permissions are explicitly called out where required
• Sensitive values are obfuscated (placeholder workspace IDs, URLs, no real tokens)
• No insecure patterns introduced (e.g. disabled TLS verification, hardcoded credentials)