Hamster AI Tools
Treat an agent tool's generated JSON Schema as its prompt contract. Make the valid call shape obvious before relying on validation errors or repair.
Design the input contract
- Put every machine-readable constraint in Zod:
- Use
.min(), .max(), .length(), .int(), .positive(), enums, z.uuid(), optional/default fields, and discriminated unions as appropriate.
- Prefer native Zod constraints over prose because the AI SDK converts them to JSON Schema keywords the model can use.
- Give model-correctable bounds an actionable Zod error message. State how to rewrite the value for a valid retry (for example, synthesize repeated evidence or split independent operations), not only the numeric limit. Keep the native constraint so the generated JSON Schema still carries
minLength, maxLength, or the equivalent keyword.
- Reuse canonical shared schemas and constants; do not duplicate enum members or validation limits.
- Use field-local
.describe() text only for semantics Zod cannot express:
- Explain what the value means, when to choose it, where to obtain it, cross-field relationships, and side effects.
- Do not repeat lengths, ranges, enum members, required/optional status, UUID format, or other constraints already present in the generated schema.
- Keep descriptions concise and actionable. Avoid implementation details and generic filler.
- Use refinements only for constraints that native Zod cannot represent:
- Attach the issue to the relevant
path and write an actionable message that states how to correct the input.
- Use
superRefine for cross-field invariants. Describe the relationship on the involved fields because refinements may not survive JSON Schema conversion.
- Do not depend on a thrown validation error as the model's first source of guidance.
- Treat transforms as execution behavior, not model guidance. Confirm that the input-side constraints and descriptions still appear after conversion.
Inspect what the model receives
Render the actual tool schema through the same AI SDK conversion used in production:
import { asSchema } from '@ai-sdk/provider-utils';
const jsonSchema = asSchema(tool.inputSchema).jsonSchema;
Inspect properties, required, enums, formats, bounds, descriptions, and union structure. Do not approve a schema by reading only its Zod source.
Add a contract test for every new or materially changed model-facing schema. Assert both layers separately:
- Structural guidance is represented by JSON Schema keywords such as
minLength, maxLength, enum, and format.
- Descriptions contain only the semantic guidance that cannot be encoded structurally.
- Required fields and union branches match the tool's execution contract.
- Correctable validation failures expose the intended retry guidance through the Zod issue message. Assert the issue
code, path, and message so a generic default cannot silently return.
Follow the repository's test-driven-development skill: change the contract test first, observe the intended failure, then change the schema.
Handle tool-call repair
- Use the AI SDK's
experimental_repairToolCall hook for model-generated calls that fail parsing or validation.
- Keep orchestration wiring thin. Put reusable repair dispatch in the orchestration repair module and tool-specific repair beside the tool.
- Parse with the AI SDK/provider utility used by the codebase; do not add bespoke
JSON.parse wrappers.
- Repair only lossless structural defects deterministically. Revalidate the complete repaired payload against the canonical Zod schema.
- Never repair semantic text by truncating, slicing, dropping fields, or otherwise discarding context to satisfy a bound. Return no repair so the multi-step model can retry from the full conversation context. If a dedicated model-based repair is justified, require structured output against the canonical schema and instruct it to preserve every material fact.
- Return no repair for ambiguous, missing, authorization-sensitive, or semantically invalid input. Never invent IDs, enum choices, or user intent.
- Bound repair to one attempt and preserve observability. Repair is a safety net, not a substitute for a strong schema.
Review checklist
- Inspect the generated JSON Schema, not just Zod.
- Encode structure in Zod and semantics in
.describe().
- Avoid duplicated constraints in prose.
- Make refinement errors field-specific and actionable.
- Test the model-facing contract and execution validation.
- Use official AI SDK repair and parsing APIs.
- Keep tool-specific logic out of the core orchestrator.
- Compare detail quality with adjacent tools before declaring the contract complete.
Key files
| File |
Purpose |
apps/ai/src/modules/ai-agent/tools/ |
Agent tool implementations and specs |
apps/ai/src/modules/ai-agent/orchestration/core-tool-call-repair.ts |
Shared repair dispatch for core agents |
apps/ai/src/modules/ai-agent/agents/core-agent/core-orchestrator.agent.ts |
Thin AI SDK repair-hook wiring |
packages/shared/src/schemas/ |
Canonical shared Zod schemas and limits |
1---2name: hamster-ai-tools3description: "Design, implement, review, and repair model-facing AI SDK tools in apps/ai, including Zod input schemas, field descriptions, JSON Schema conversion, validation-error loops, tool-call repair hooks, and contract tests. Use whenever adding or changing an agent tool, diagnosing tool input validation failures, or reviewing whether a tool gives the model enough guidance."4metadata:5 source: https://skillmd.com/skills/gethamster/hamster-ai-tools6---78# Hamster AI Tools910Treat an agent tool's generated JSON Schema as its prompt contract. Make the valid call shape obvious before relying on validation errors or repair.1112## Design the input contract13141. Put every machine-readable constraint in Zod:15 - Use `.min()`, `.max()`, `.length()`, `.int()`, `.positive()`, enums, `z.uuid()`, optional/default fields, and discriminated unions as appropriate.16 - Prefer native Zod constraints over prose because the AI SDK converts them to JSON Schema keywords the model can use.17 - Give model-correctable bounds an actionable Zod error message. State how to rewrite the value for a valid retry (for example, synthesize repeated evidence or split independent operations), not only the numeric limit. Keep the native constraint so the generated JSON Schema still carries `minLength`, `maxLength`, or the equivalent keyword.18 - Reuse canonical shared schemas and constants; do not duplicate enum members or validation limits.192. Use field-local `.describe()` text only for semantics Zod cannot express:20 - Explain what the value means, when to choose it, where to obtain it, cross-field relationships, and side effects.21 - Do not repeat lengths, ranges, enum members, required/optional status, UUID format, or other constraints already present in the generated schema.22 - Keep descriptions concise and actionable. Avoid implementation details and generic filler.233. Use refinements only for constraints that native Zod cannot represent:24 - Attach the issue to the relevant `path` and write an actionable message that states how to correct the input.25 - Use `superRefine` for cross-field invariants. Describe the relationship on the involved fields because refinements may not survive JSON Schema conversion.26 - Do not depend on a thrown validation error as the model's first source of guidance.274. Treat transforms as execution behavior, not model guidance. Confirm that the input-side constraints and descriptions still appear after conversion.2829## Inspect what the model receives3031Render the actual tool schema through the same AI SDK conversion used in production:3233```typescript34import { asSchema } from '@ai-sdk/provider-utils';3536const jsonSchema = asSchema(tool.inputSchema).jsonSchema;37```3839Inspect `properties`, `required`, enums, formats, bounds, descriptions, and union structure. Do not approve a schema by reading only its Zod source.4041Add a contract test for every new or materially changed model-facing schema. Assert both layers separately:4243- Structural guidance is represented by JSON Schema keywords such as `minLength`, `maxLength`, `enum`, and `format`.44- Descriptions contain only the semantic guidance that cannot be encoded structurally.45- Required fields and union branches match the tool's execution contract.46- Correctable validation failures expose the intended retry guidance through the Zod issue message. Assert the issue `code`, `path`, and message so a generic default cannot silently return.4748Follow the repository's `test-driven-development` skill: change the contract test first, observe the intended failure, then change the schema.4950## Handle tool-call repair5152- Use the AI SDK's `experimental_repairToolCall` hook for model-generated calls that fail parsing or validation.53- Keep orchestration wiring thin. Put reusable repair dispatch in the orchestration repair module and tool-specific repair beside the tool.54- Parse with the AI SDK/provider utility used by the codebase; do not add bespoke `JSON.parse` wrappers.55- Repair only lossless structural defects deterministically. Revalidate the complete repaired payload against the canonical Zod schema.56- Never repair semantic text by truncating, slicing, dropping fields, or otherwise discarding context to satisfy a bound. Return no repair so the multi-step model can retry from the full conversation context. If a dedicated model-based repair is justified, require structured output against the canonical schema and instruct it to preserve every material fact.57- Return no repair for ambiguous, missing, authorization-sensitive, or semantically invalid input. Never invent IDs, enum choices, or user intent.58- Bound repair to one attempt and preserve observability. Repair is a safety net, not a substitute for a strong schema.5960## Review checklist6162- Inspect the generated JSON Schema, not just Zod.63- Encode structure in Zod and semantics in `.describe()`.64- Avoid duplicated constraints in prose.65- Make refinement errors field-specific and actionable.66- Test the model-facing contract and execution validation.67- Use official AI SDK repair and parsing APIs.68- Keep tool-specific logic out of the core orchestrator.69- Compare detail quality with adjacent tools before declaring the contract complete.7071## Key files7273| File | Purpose |74| --- | --- |75| `apps/ai/src/modules/ai-agent/tools/` | Agent tool implementations and specs |76| `apps/ai/src/modules/ai-agent/orchestration/core-tool-call-repair.ts` | Shared repair dispatch for core agents |77| `apps/ai/src/modules/ai-agent/agents/core-agent/core-orchestrator.agent.ts` | Thin AI SDK repair-hook wiring |78| `packages/shared/src/schemas/` | Canonical shared Zod schemas and limits |