prompt-optimizer: clarify tool disclosure — provider-native tool array vs. in-prompt policy

[dcramer]

Affected files:

• skills/prompt-optimizer/references/core-patterns.md (the <tools> section of the portable skeleton, around the "Portable agent prompt skeleton" block)
• skills/prompt-optimizer/references/transformed-examples.md (Example 1's <tools> block)
• skills/prompt-optimizer/references/model-family-notes.md (all three provider sections — none mention tool disclosure mechanics)

What's unclear today

The <tools> section in the skeleton reads:

<tools>
Available tools:
When to use them:
When to avoid them:
</tools>

Example 1 in transformed-examples.md fills it with prose like "Use tools to inspect the workspace before assuming facts." The skill never disambiguates tool schema disclosure (handled by the provider-native tools array on the API request — Anthropic, OpenAI, Gemini) from tool policy (when/why/whether to call them — the only thing the system prompt should carry).

A naive reader, especially when creating a new agent prompt, is nudged toward enumerating tool names, descriptions, or argument schemas in the <tools> section. That duplicates what the provider already surfaces to the model via the native tool parameter and bloats the prompt without adding signal.

Concrete example from the field

While simplifying a harness prompt that wraps @mariozechner/pi-agent-core (Anthropic tool-use under the hood), we found a line: "Active MCP tools registered for this turn: X, Y, Z. Call them directly by name." — reading pi-agent's agent-loop.js + the Anthropic provider showed tools are already disclosed via the native tools array with full schemas. The in-prompt line was pure duplication. Dropping it cost nothing and removed a section.

Suggested fix

1. In core-patterns.md, add a short note near the skeleton that the <tools> section is for behavioral policy only — tool names/descriptions/schemas are disclosed to the model by the provider-native tool parameter (Anthropic tools, OpenAI tools, Gemini tools), and restating them in the prompt is redundant.
2. In model-family-notes.md, add one line to each provider section noting that tool schema disclosure is handled by the API's native tool parameter.
3. Consider reframing the Example 1 <tools> block as <tool_policy> or similar so the distinction is visible in the reference example.

Why it matters

In layered agent runtimes (harness + skill framework + pi-agent-style loop), redundant tool enumeration is one of the easier wins when simplifying a prompt. The current skill guidance neither invites nor blocks it — it just doesn't mention the distinction, so authors re-list tools out of habit.