Module tool_value_model 

Tool value model — Paper 3 §“how to build tools right”.

ToolValueModel is a machine-readable description that every provider attaches to each tool it ships. The Paper 3 enrichment planner reads these models to decide which tools to call, in what order, and which fields of each response are worth keeping under a given turn budget.

Design echoes Paper 2’s [profiles.data] axis: the model is plain serde-compatible data, ships with sensible per-provider defaults, and can be overridden through a [tools.<name>] block in pipeline_config.toml without recompiling. The schema lives here (in devboy-core) so provider crates can populate it without taking a dependency on the executor or the pipeline.

See docs/research/paper3_corpus_findings.md for the empirical basis of the default values, and Paper 3 (issue tracker P-3) for the planner that consumes them.

Structs

CostModel

What the call costs in tokens, latency, dollars, and how long the result stays valid in cache.

FieldGroup

One named subset of fields from a tool’s response. Providers carve the full result into groups so the planner can drop low-value fields without dropping the call entirely.

FollowUpLink

Edge in the empirically observed follow-up graph. After tool A fires, the planner consults A’s follow_up list to decide which tools to speculatively prefetch.

ToolValueModel

Provider-shipped, user-overridable description of how a tool fits into the enrichment knapsack.

Enums

SideEffectClass

Side-effect classification — controls whether a tool is safe to run speculatively (i.e. before the LLM asks for it).

ValueClass

How important the tool’s output is to the agent’s task.