flux7-mesh defines 10 tools with mixed quality. Most tools have basic descriptions (10-50 chars), but lack depth on WHEN to use them or what they return. Input schemas are present but sparse: many tools have minimal parameters with no type constraints or enums. Critical gaps: no output schemas documented, no error handling guidance, no parameter validation rules stated. Tool names are reasonable (verb_noun style) but descriptions are too terse. The governance-focused tools (approval.*, grant.*) are better documented than basic utilities (echo, risky_tool). No evidence of idempotency markers, permission gates, or audit trail patterns.

• Rename 'risky_tool' to a verb_noun form that reflects its actual action (e.g., 'trigger_risk_event', 'execute_risky_operation'). Add a 50-150 char description explaining what it does, when to use it, and what side effects occur.
• Document output schemas for all tools. For list tools (approval.pending, grant.list, mesh.catalog), specify: array of objects, per-item field names/types, total count or pagination cursor. For single-item tools (get_order, fs.read_file), specify returned fields and their types.
• Expand tool descriptions to 50-200 chars. Include: (1) what the tool does, (2) when to use it vs similar tools, (3) what it returns or side effects. Example: 'Create a temporal grant allowing an agent to call tools matching a glob pattern for a specified duration. Supervisor-only. Returns grant ID and expiration time.'
• Add parameter constraints and validation rules to descriptions. For grant.create: 'duration must be a Go duration string (e.g., 1h, 30m, 5s); agent must be a valid agent ID; tools pattern uses glob syntax (*, ?).' For approval.resolve: 'decision must be one of: approve, deny.'
• Add error handling guidance to tool descriptions. E.g., fs.read_file: 'Returns error if path does not exist or is not readable. Try listing the directory first with a discovery tool.' approval.resolve: 'Returns error if approval ID not found or already resolved. Call approval.pending to see available IDs.'

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry