Supplementary reference material for the `platform-metadata-api-context-get` skill. Load this file only when you need the deeper background below; the core decision tree, section-loading rules, generation requirements, and troubleshooting live in `SKILL.md`.
## Why Token Optimization Matters
### Context Window Constraints
Claude has a finite context window (200K tokens). Loading the full metadata-type corpus would consume:
- **~15MB of JSON data**
- **~75,000 tokens** (approximately 40% of available context)
- **Reduced space** for your actual code and conversation
This leaves less room for:
- Your project's code files
- Conversation history
- Generated responses
- Multi-turn problem solving
### Cost Implications
Token usage directly impacts costs:
- **Input tokens**: Every loaded file counts toward input cost
- **Repeated requests**: Loading files multiple times multiplies costs
- **Cache misses**: Large contexts may not fit in prompt cache
### Performance Trade-offs
Loading all files affects performance:
- **Slower response times**: More tokens to process
- **Reduced relevance**: LLM must search through more irrelevant data
- **Context dilution**: Important information gets buried in noise
### Best Practices
✅ **DO**:
- **Use programmatic JSON parsing** to extract only needed sections (Python json.load(), Node.js JSON.parse(), etc.)
- **Load only specific sections** from each JSON file (fields, description) not the entire file
- Load 1-5 specific metadata types relevant to your task
- Check the `sections` array first to see what's available
- Use the index table to find related types
- Skip WSDL segments and sample definitions unless explicitly needed
- Cache frequently used sections (fields for CustomObject, Flow, Profile)
❌ **DON'T**:
- **NEVER use the `read_file` tool or other whole-file readers on the metadata-type JSON files** (loads entire file into context)
- Load entire JSON files when you only need 1-2 sections
- Load every metadata type at once
- Load files "just in case" you might need them
- Repeatedly load the same files in a conversation
- Include WSDL segments unless you need schema validation
- Load declarative_metadata_sample_definition unless examples are required
### Example: Good vs. Bad
**Bad** (wastes ~75,000 tokens):
```text
"Load all metadata types so I can reference them"
```
**Better** (uses ~500 tokens):
```text
"Show me the CustomObject and CustomField metadata types"
```
**Best** (uses ~150 tokens):
```text
"Show me only the 'fields' section from CustomObject.json"
```
The section-specific approach uses **500x fewer tokens** while providing exactly what you need.
## Token Size Reference
Approximate token counts for different loading strategies:
| What You Load | Approx. Tokens | Use Case |
|---------------|----------------|----------|
| Single section (fields only) | 50-200 | ✅ **BEST** - Quick field reference |
| Single section (description) | 20-100 | ✅ Overview/understanding |
| 2-3 sections from one type | 150-500 | Most common use case |
| Entire single type (small) | 100-500 | Small types without WSDL |
| Entire single type (large) | 500-2,000 | ❌ **Wasteful** - includes unused WSDL |
| 5 related types (entire files) | 2,000-5,000 | ❌ Use section-specific loading instead |
| 50 types (entire files) | 25,000-35,000 | ❌ Never do this |
| The full metadata-type corpus | ~75,000 | ❌ Catastrophic waste |
**Note**: Loading only specific sections (fields, description) typically reduces token usage by **60-80%** per file compared to loading entire files with WSDL segments and examples.
## Usage Examples
### Example 1: Creating a CustomObject (Section-Specific)
**User**: "I need to create a custom object metadata file for a Student object"
Several metadata types are authored as **a pair** of files in SFDX source format: a source file with the actual content, and a sibling `<base>.<ext>-meta.xml` carrying deployment metadata. The JSON's `content` field (when present, base64-encoded) corresponds to the source file on disk:
| AuraDefinitionBundle | bundle dir with `.cmp`/`.app`/`.evt` + `.js` + `.css` etc. | `bundle-meta.xml` inside the dir |
| LightningComponentBundle | bundle dir with `.html`/`.js`/`.css` | `bundle.js-meta.xml` inside the dir |
When a JSON file contains a `content` field of type `base64`, that's the SOAP-API artifact equivalent of the disk source file. Authors write the source file directly; the `-meta.xml` sidecar carries fields like `apiVersion` and `status`.
#### Child Metadata Types (legacy MDAPI vs SFDX source format)
Some metadata types appear in the index but are **child elements** of a parent type, not standalone files. Examples: `ValidationRule`, `WebLink`, `RecordType`, `CompactLayout`, `ListView`, `BusinessProcess`, `FieldSet`, `SharingReason`, `Index` — all nested under `CustomObject`. Their JSON files lack `file_information` and `directory_location` because the legacy MDAPI form serializes them inline inside the parent `.object` file.
In modern **SFDX source format**, these child types are decomposed into their own files under the parent object directory:
```text
force-app/main/default/objects/MyObject__c/
├── MyObject__c.object-meta.xml
├── fields/
│ └── MyField__c.field-meta.xml
├── validationRules/
│ └── My_Rule.validationRule-meta.xml
├── recordTypes/
│ └── My_RT.recordType-meta.xml
├── webLinks/
│ └── My_Link.webLink-meta.xml
├── compactLayouts/
│ └── My_Layout.compactLayout-meta.xml
└── listViews/
└── My_View.listView-meta.xml
```
The JSON's `declarative_metadata_sample_definition` shows the legacy inline form (e.g., `<validationRules>` inside `<CustomObject>`). When authoring in SFDX source format, take the inner element of that sample, drop it into its own file under the appropriate sub-directory, and add the standard `<?xml ...?>` + namespace wrapper using the type name as the root (e.g., `<ValidationRule xmlns=...>`).
