AIWorkHub provides 3 tools for managing agent instruction files in repositories. All tools have explicit schemas with typed parameters and enums, which is solid. However, descriptions are terse (most under 100 chars), parameter descriptions are minimal or generic, and output schemas are completely undocumented. The tool names are action-verb-based ('preview', 'inspect', 'apply') but lack clarity on what resource they operate on without reading the description. All three tools accept a 'provider' enum and 'repo_root' string, properly constrained. The main weaknesses are: (1) no documented return type/schema for any tool, (2) terse descriptions that don't explain WHEN to use each tool vs the others, (3) no explanation of error conditions or recovery guidance, (4) no actionable differences between 'preview' and 'inspect' from description alone. The write-gating on apply_instruction is good security practice (write=False default), but it's not mentioned in the description. Tools appear well-engineered internally (managed markers, idempotence, path-escaping validation visible in code), but the surface API contract is underspecified for LLM consumption.

• Document return schemas for all three tools. Specify fields returned for preview (e.g., apply_plan, diffs), inspect (e.g., marker_count, managed_block_valid, validity_errors), and apply (e.g., dry_run_plan on write=False, applied_changes on write=True).
• Expand tool descriptions to 150-200 chars. Clarify use cases: preview → 'See what changes would be made without modifying files'; inspect → 'Check if managed markers are valid before applying'; apply → 'Activate the tool-use policy block, with optional dry-run'.
• Add a 'Returns' section to each tool description documenting output schema, or reference it explicitly: 'Returns object with {field_name: type, ...}'.
• Document error conditions and recovery guidance. Example: 'If provider is invalid, call with provider omitted to see all three. If write fails due to permission, ensure core.writes_allowed() is enabled.'
• Clarify the relationship between 'preview' (all three providers by default) and 'inspect' (single provider required) in their descriptions. State explicitly when to call each.
• Add a note that the write parameter's default (false) enables safe exploration, explicitly say 'Set write=True only after previewing the changes'.