Tools

Cost Tagging

Tools can declare an estimatedCostUsd on their definition. This value is attached to every ToolResult as costUsd and flows into the agent cost dashboard, giving per-tool cost attribution without requiring external instrumentation.

Declaring a cost

typescript
export const imageTool: ToolDefinition = {
  name: 'generate_image',
  description: 'Generate an image with DALL-E',
  estimatedCostUsd: 0.04,   // $0.04 per call
  parameters: z.object({ prompt: z.string() }),
  execute: async ({ prompt }) => {
    return await generateImage(prompt)
  },
}

ToolResult shape

typescript
interface ToolResult {
  toolCallId: string
  name: string
  content: string
  durationMs: number
  costUsd?: number   // populated from estimatedCostUsd
}

Viewing costs

Costs aggregate into the per-agent dashboard. Run npx astra costs or query the /costs API to see a breakdown by tool, agent, and user. See Cost Dashboard for details.

estimatedCostUsd is a static estimate — set it based on the provider's per-call pricing. For variable-cost tools (e.g. LLM calls inside a tool), compute the actual cost inside execute() and return it as part of the result, then handle it in your cost tracking webhook.