Build quality

Tool authoring guide.

Good agent tools are small, typed, explicit, and honest about side effects. This is where developers turn provider APIs into reliable Orchet capabilities.

Design tools around user jobs.

A tool should map to a real action the user expects, not a raw provider endpoint dump.

Weak	Better
api_post_expenses	splitwise_create_expense
run_query	calendar_find_free_slots
action	flight_hold_offer
submit	opentable_reserve_table

Descriptions route the model.

Write operation descriptions as instructions for the planner. Include what the tool does, when to use it, what it cannot do, and what confirmation is required.

Prefer concrete nouns: group_id, amount, currency, description, attendee_count.
Use enums for provider-limited values.
Return ids that can be used by follow-up tools.
Return user-readable summaries that Orchet can quote in chat.

Structured errors.

Do not return provider stack traces. Return stable error codes and recovery hints so Orchet can keep the conversation useful.

JSON

{
  "error": {
    "code": "provider_permission_denied",
    "message": "Splitwise denied permission to create this expense.",
    "retryable": false,
    "user_action": "Reconnect Splitwise with expense creation access."
  }
}

Idempotency and confirmations.

Any write or side-effect tool should accept an idempotency key or natural duplicate guard. Orchet may retry after transient failures, and users will punish double-booking faster than almost any other bug.