Submit a raw incident report from a production system. The report is queued for admin review and synthesis into a permanent Arete lesson. Requires a valid x-agent-key header.
| Name | Required | Description | Default |
|---|---|---|---|
| stack | Yes | ||
| severity | No | ||
| affected_systems | Yes | ||
| incident_summary | Yes | Concise narrative of what happened |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full disclosure burden. It reveals that reports are queued for admin review and synthesis into a permanent Arete lesson, and requires a valid x-agent-key header, which are key behavioral traits. It doesn't mention reversibility or failure modes, but adds valuable context beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences and front-loaded with the main purpose. Every sentence adds new information: purpose, outcome, and authentication requirement. No redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description provides sufficient high-level context about the tool's role and post-submission flow. However, it doesn't detail parameter usage or expected response, leaving gaps for effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 25% of parameters have schema descriptions, and the tool description doesn't mention any parameter semantics. The description doesn't explain what `stack`, `affected_systems`, or `severity` mean, leaving the agent to rely solely on schema names and the single description for `incident_summary`.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool submits a raw incident report from a production system, with a specific verb and resource. It distinguishes itself from sibling tools like query_lessons or complete_task_run by focusing on incident report submission.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use the tool: submitting a raw incident report from a production system. It doesn't explicitly rule out alternatives or mention when not to use it, but the context is clear given the distinct purpose and sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Most task-run and record_* tools are clearly distinct, but query_lessons, query_lessons_full, and query_lessons_premium all describe nearly the same underlying lesson-query action separated mainly by access tier and payment. An agent can easily call the wrong one, especially because 'full' and 'premium' boundaries are unclear.
The tools consistently use snake_case verb_noun names such as start_task_run, complete_task_run, record_reflection, and submit_incident_report. The query_lessons variants use a predictable suffix pattern, and there is no mixing of naming conventions.
Ten tools is a reasonable footprint, but the three query_lessons variants are essentially reimplementations of the same query by payment/access tier. The count is not excessive, though it could be reduced without losing real capability.
The set covers task-run start/completion and lesson querying, but there is no way to read back task runs, reflections, subagent traces, or usage records after submitting them. This makes the task-run side feel mostly write-only and creates a notable gap in a memory-focused server.