afv-library/skills/platform-data-and-tooling-api-context-get/references/usage_guide.md

# Data + Tooling API Skill — Usage Guide

Supplementary reference for `platform-data-and-tooling-api-context-get`. Load only when needed; the core rules
live in `SKILL.md`.

- **API version:** 67.0 (summer-26)
- **Generated:** 2026-07-23 20:16:53

## Worked Examples

### Example 1: Build a filtered SOQL query (section-specific)

**User**: "Query open high-value opportunities with their account name."

1. Load only the `fields` section of `assets/enterprise_api/Opportunity.json`.
2. Confirm `Amount` (Filter, Sort), `StageName` (Filter), and `AccountId`
   (reference, relationship_name = `Account`).
3. Generate:
   ```sql
   SELECT Id, Name, Amount, Account.Name
   FROM Opportunity
   WHERE IsClosed = false AND Amount > 100000
   ORDER BY Amount DESC
   ```
Token savings: ~80% vs loading the whole Opportunity file with its WSDL segment.

### Example 2: Safe DML (respect read-only fields)

**User**: "Update the account rating and its formula health score."

1. Load `fields` on `assets/enterprise_api/Account.json`.
2. `Rating` has `Update` → writable. A formula field has no `Create`/`Update`
   → read-only; attempting to set it fails. Only include writable fields in the
   `update` payload.

### Example 3: Tooling API code coverage

**User**: "What fields give per-class Apex code coverage?"

1. Load `fields` on `assets/tooling_api/ApexCodeCoverageAggregate.json`.
2. Note `NumLinesCovered`, `NumLinesUncovered`, `ApexClassorTriggerId` (lowercase "or" — check exact casing per object, don't assume `Or`).
3. Query via the Tooling endpoint (`/services/data/vXX.0/tooling/query`), per
   `supported_rest_api_http_methods`.

## Relationship Traversal

- Parent (child→parent): use `relationship_name` — `Owner.Name`, `Account.Industry`.
- Custom lookups: `__c` id field, traverse with `__r` (`Foo__r.Name`).
- Child (parent→children): use the child relationship name in a subquery, e.g.
  `SELECT Id, (SELECT Id FROM Contacts) FROM Account`.
- Polymorphic (`WhoId`, `WhatId`, `OwnerId` on some objects): `refers_to` lists
  multiple targets — use `TYPEOF` for surface-specific fields.

## Section Glossary

| Section | Meaning |
|---|---|
| `fields` | field API names, types, properties, and (enterprise) relationship columns |
| `fields_columns` | which columns each `fields` entry carries |
| `usage` | (enterprise) notes on how the sObject is used |
| `associated_objects` | (enterprise) related objects — **unstructured prose, not indexable JSON**; parse the markdown-style bullet list. Whether a named associated object resolves to a real file in `assets/enterprise_api/` depends on whether Salesforce crawled it as its own docs page: names ending in `Share` or `OwnerSharingRule` reliably do (Salesforce documents these per-object); names ending in `ChangeEvent` or `Feed` reliably don't (documented only generically, never as a separate page); names ending in `History` are inconsistent (sometimes crawled separately, sometimes not) — always verify with a file check before assuming either way, don't trust the name alone in any direction. |
| `ispersonaccount_fields` | (enterprise) fields present only when Person Accounts are enabled — rare; present on very few objects |
| `field_reference` | (enterprise) a **separate, largely disjoint** field catalog (label/length/precision/scale, no query/DML properties) — NOT a superset of `fields`. Check it when a field isn't in `fields`. See `field_reference_columns` for its column shape. |
| `supported_soap_calls` | (tooling) SOAP operations the record supports |
| `supported_rest_api_http_methods` | (tooling) REST methods the record supports |
| `wsdl_segment` | raw WSDL schema for the object (verbose; skip by default) |

## Field Properties Cheat Sheet

| Property | Enables |
|---|---|
| Create | set on `insert` |
| Update | set on `update` |
| Filter | use in `WHERE` |
| Sort | use in `ORDER BY` |
| Group | use in `GROUP BY` |
| Nillable | may be null (non-nillable = required on insert) |

`properties` is a single string with tokens separated by `", "` — **always split on
`", "`, never on whitespace alone.** Some tokens are multi-word (`Restricted picklist`,
`Defaulted on create`); splitting on whitespace fragments them into garbage tokens.
A field with `Defaulted on create` and no `Nillable` is not strictly required on
insert — Salesforce supplies a default if omitted.

---

*Generated by `skill-generator/scripts/generate_data_and_tooling_skill.py`.*