finding: add-a-tool omits where function_tool comes from and what a raising tool does

[sagi5060]

Problem

guides/add-a-tool.mdx leaves two things unsaid that a first tool needs, both hit by a clean-room
reviewer following the page:

1. Where function_tool comes from. Line 13 shows:

from agents import function_tool

Nothing on the page says agents is the OpenAI Agents SDK rather than part of agentdeck. A reader who
has just installed agentdeck and read from agentdeck import Deck, Agent reasonably tries
from agentdeck import function_tool, which does not exist. Same omission at concepts/agents.mdx:100
(from agents import AgentOutputSchema).

2. What happens when a tool raises. Nothing states what the caller, the event log, or the HTTP
response sees when a tool raises mid-turn, or how to return a user-facing failure instead. Every
reviewer asked; it is the first thing a real tool needs after the happy path.

Proposed shape

One sentence for the import, at the first occurrence on each page:

`function_tool` comes from the OpenAI Agents SDK (`agents`), which agentdeck installs and passes
through unchanged — tools are the SDK's, not a wrapped agentdeck type.

A short section for failures, showing both halves — the recoverable case handled inside the tool, and
what the run does when it is not:

@function_tool
def lookup_shift(date: str) -> str:
    row = SHIFTS.get(date)
    if row is None:
        return f"no shift on record for {date}"   # the model can act on this; the run continues
    return row

...followed by what an unhandled exception actually produces — which event the log records, what
run() raises, and what the HTTP surface returns — written from the code, not from expectation.

Out of scope: changing any behavior. This is two docs additions.

Notes

• The pass-through is the design (agentdeck owns configuration, the SDK owns execution) — the page
  just never says it, so the boundary reads as an inconsistency instead of a decision.
• Verify the failure section against runtime/service.py's exception path and the serve surface's
  handler before writing it; do not describe intended behavior.

Done when

• guides/add-a-tool.mdx states that agents is the Agents SDK and that tools are passed through
• concepts/agents.mdx does the same at its first from agents import
• add-a-tool.mdx shows a tool returning a handled failure the model can act on
• It states what an unhandled tool exception produces: the event recorded, what the caller sees,
  what HTTP returns — each verified against the code

[sagi5060]

Independently confirmed, with proof of absence

A third clean-room reviewer (agent surface) reached the same conclusion on this page's second half and
ran the grep:

$ grep -rni "tool.*raise\|tool.*exception\|tool.*error\|ToolCallError\|tool_call.*fail" docs/ README.md

Two hits, both unrelated: Tavily's own internal error:-string degrade, and the TypeError for
Workflow.as_tool()'s state argument. Nothing describes what an ordinary tools=[...] callable
raising does to the run.

It ranked this its #5 ask before production, with the reasoning worth keeping: tools that can fail —
a database call, an external API — are the whole point of the tool system, so the failure contract is
not an edge case. It could not test the behavior itself (that needs a model that decides to call the
tool, which its stubbed endpoint could not fake), which is exactly why the docs have to state it.

Note for whoever writes it: #243 changes what an unhandled exception returns over HTTP, so write this
section after that lands, or the "what the caller sees" half will be stale on arrival.