Tool

A toolcontract.ToolDescriptor declares its namespace and policy resource, a SideEffectClass, whether it needs approval and what a grant covers, whether it needs the requester present or their own device, its visibility, its idempotency, whether its result can serve as completion evidence, and a result contract. Nothing dispatches on a tool's name.

The side effect classes are none, read, computation, state_change, workspace_write, external_write, approval, connect, destructive, external_send, external_publish, local_file, platform_reply and site_publish.

The catalog

The kernel tools are read, write, edit, bash, file_read, file_preview, file_delete, file_deliver, plan, equip, skill_search, skill_add, skill_remove, ask_input, conversation_history, memory_search, memory_remember, memory_forget, persona_read and persona_update. Capability tools are added from the capability service's catalog at runtime. docs/tool-catalog.md is generated from the registering code with what each description costs.

At most 15 extension tools are offered to the model at once (toolcontract.MaxExtensionCallableToolCount); kernel tools come on top. What does not fit is reported as a dropped group in the exposure event.

Registration

Providers register through toolcontract.RegisterProviders. A trusted provider that fails to load fails registration; an external provider that fails, or whose names collide with a registered tool, is quarantined and reported. A descriptor missing a required field, a model-visible tool without a result contract, or an object schema that does not set additionalProperties: false is rejected.

Keep input schemas shallow and portable across model providers: string-only enums, no $ref, no exotic format, with enumerated numbers stated in the description and checked by the runtime. The runtime does not enforce all of this; the harness rewrites integer to number and fills empty properties, and nothing rejects const.