Martol Agent defines 5 tools with complete input schemas and generally good descriptions. However, there are significant gaps in output schema documentation, error handling guidance, and some parameter descriptions lack actionable detail. Tool naming follows verb_noun conventions well (action_*, brief_*, doc_*). The action_submit tool has a sophisticated nested schema with simulation and impact tracking, but lacks guidance on what the LLM should do if approval is denied or times out. Most parameter descriptions are present and clear, but output structures are not documented for any tool, forcing LLMs to infer response formats. Error handling is absent, no guidance on retryability, user-fixable vs fatal errors, or recovery steps.

• Add a 'Returns' section to each tool description documenting the output schema. Example: 'Returns: {action_id: integer, status: string (submitted|approved|rejected|expired), submitted_at: ISO8601, approved_by?: string, rejection_reason?: string}'.
• For action_submit: Add explicit error handling guidance. 'If the action is rejected, call action_status to retrieve the rejection_reason and present it to the user. If status is 'expired' (>24h), resubmit with updated description.'
• For action_submit: Clarify that 'simulation' is optional (move from required if present in JSON Schema). Add: 'Omit simulation if you cannot reliably predict outcomes. The server will display a default warning card.'
• For doc_search: Document query constraints. 'query must be 1-500 characters, natural language. Returns up to top_k chunks from uploaded PDFs/docs with filenames, relevance (0.0-1.0), and text snippets (max 500 chars each).'
• For brief_update: Add max length constraints. 'goal, stack, conventions, notes: 1-5000 chars each. phase: 1-200 chars. All fields optional; only provided fields are updated.'
• For action_status: Document possible status values and response fields. 'Returns {action_id, status: (submitted|pending_approval|approved|rejected|expired|executed), created_at, decided_at?, decided_by?, rejection_reason?, execution_result?}'.
• Add a 'Composition' section to docs noting that action_submit → action_status is a two-step approval workflow. Clarify that agents should not poll action_status in a tight loop; define a backoff strategy or event-based notification model.

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

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