# Pitfalls Compile-time traps that are easy to miss when deriving tools from `@spec` and `@doc`. Release behaviour is covered in [`design.md`](design.md); the type subset and runtime boundaries are covered in [`design.md`](design.md) and [`number-handling.md`](number-handling.md). ## `@spec` carries no parameter names `@spec f(String.t())` is a value domain, not a record. The schema needs property names, so the library requires annotated arguments: ```elixir @spec get_weather(city :: String.t()) :: ... ``` The quoted AST for that argument is `{:"::", _, [{:city, _, nil}, type]}`, so the name survives compilation. An unannotated argument can also take a name from a `@doc` parameter bullet; otherwise it falls back to the head variable, then `argN`, with a compile-time warning. ## `@spec` is an accumulative attribute `Module.get_attribute(mod, :spec)` contains specs for earlier functions too: ```elixir @spec get_weather(String.t()) :: ... @spec two_specs(integer()) :: ... ``` The library filters by `{name, arity}` and warns when a function has several specs; overloads cannot be represented as one JSON Schema. ## `@doc` is single-valued and consumed immediately `@doc` is not an accumulating attribute. Reading it later can attach the last function's text to every tool, or return `nil`. The library captures it from `@on_definition`, before the attribute is reset; `@doc false` opts a function out. ## JSON Schema `integer` accepts `1.0` Draft 2020-12 defines `integer` as a number with a zero fractional part, so a decoder can produce `1.0`. `ToolCall.Coerce` truncates integral floats and rejects fractional ones. ## `float()` parameters can receive integers `{"type":"number"}` accepts `2`, while `is_float(2)` is false. `ToolCall.Coerce` widens integers to floats before dispatch. ## JSON numbers Elixir cannot represent `1e309` is valid JSON but not a finite Erlang float; the decoder raises before the library sees it. The schema cannot prevent this. See [`number-handling.md`](number-handling.md). ## `@on_definition` fires for private functions and every clause The hook sees private helpers and each clause of a multi-clause function. The library ignores non-`def` callbacks and keeps the first `{name, arity}` entry. ## `@spec` names are documentation, not syntax The compiler allows duplicate and placeholder parameter names: ```elixir @spec f(city :: String.t(), city :: integer()) :: String.t() @spec g(_ :: String.t(), _ :: integer()) :: String.t() ``` The library renames duplicates (`city_2`) and falls back from `_` to the head variable or `argN`, with a warning. Two arities of one function share a tool name; only the first is exposed. ## `@doc` metadata never reaches the `:doc` attribute Metadata-only docs such as `@doc deprecated: "use bar/1"` do not reach the attribute read by `@on_definition`. They also live in the `Docs` chunk, which a stripped release removes. A tool declared that way falls back to its function name; write text as well if the model should see a description. ## `@typedoc` is consumed before `@before_compile` `@typedoc` is consumed by the following `@type` before `@before_compile` runs, so the phase-one IR cannot see it. ToolCall recovers docs-visible `@type` and `@opaque` text in `@after_compile` from the just-compiled `Docs` chunk and stores the enriched literals in a companion module. It is only a fallback parameter description: a `@doc` `## Parameters` bullet or a `@tool_param` description wins. Local alias chains are followed to the nearest documented type, resolving current-module references inside alias bodies; nested uses such as `list(address())` do not inherit the typedoc. `@typep` is different: Elixir discards its typedoc at definition time, so no docs entry exists to recover. A private type is still resolved for the schema, but it never contributes a description. ## Stale typedoc companions are inert and cleaned by a compile or task The companion beam is not registered in Mix's compile manifest. Source-file companions carry a `.source` sidecar with their source path; every ToolCall compile prunes companions whose source file is gone. If no ToolCall module compiles after deleting a source file, or a module was removed from an existing file, run `mix tool_call.clean` before assembling a release. The task also scans companion beams directly, using the parent beam and a live source from either the `.source` sidecar or the beam's `compile_info.source`; a stripped `compile_info` leaves only the parent-beam check. The compile-generation token makes any remaining stale companion unusable by the new module, so it falls back to phase-one data instead of serving stale descriptions. A companion generated by a ToolCall build that predates the `__tool_call_companion__/0` marker is treated as foreign, so upgrade with one `mix clean` or ToolCall warns and skips typedoc enrichment rather than overwriting it. ## A missing `Docs` chunk is not always a problem `docs: false` intentionally omits the chunk. ToolCall skips typedoc silently in that compile and only warns about a missing chunk when docs are enabled. An undecodable or structurally invalid `Docs` chunk is reported as corrupt and falls back to phase-one descriptions. ## `@on_definition` accumulates Unlike `@doc`, `@on_definition` is an accumulating attribute. A `use ToolCall` does not replace another library's definition hook; both callbacks fire, including for generated functions such as `__tools__/0`. ## Remaining design boundaries Some limits are intentional: nested/remote/provider typedoc inheritance, `@typep` typedoc recovery, overloaded specs, two arities of one function, tuple defaults, JSON numbers outside Erlang's finite range, `@doc` metadata-only entries and type-provider typedoc. See the Design boundaries section in [`design.md`](design.md).