Ouroboros
Server Quality Checklist
Latest release: v0.50.8
- Disambiguation2/5
Many tools are near-duplicates, e.g., execute_seed vs start_execute_seed, evaluate vs start_evaluate, ralph vs start_ralph, and auto vs start_auto. The sync/async distinction is subtle, and the auto/ralph naming is opaque, creating high risk of selecting the wrong tool.
Naming Consistency3/5All tools share the ouroboros_ prefix, but the suffix patterns are inconsistent: some are verb_noun (execute_seed, cancel_job), some are noun_state (job_status, session_status), and proper nouns like ralph lack a verb. The start_* variants are applied selectively, not uniformly.
Tool Count2/5With 34 tools, the set is oversized for its purpose. Many are paired sync/async versions of the same operation, inflating the count without adding functional diversity. This exceeds the comfortable range and creates cognitive overhead.
Completeness4/5The tool surface covers the full lifecycle: interview → seed → execute → evaluate → evolve → rewind, plus job management, AC tracking, drift measurement, and lateral thinking. Both synchronous and asynchronous paths are provided, with no obvious gaps for the domain.
Average 3.9/5 across 34 of 34 tools scored. Lowest: 2.8/5.
See the Tool Scores section below for per-tool breakdowns.
- 202 of 214 community issues answered or closed in the last 6 months
- 679 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that a seed is executed, but does not mention whether execution is synchronous, whether it creates sessions, triggers QA, or modifies state. It gives no context about side effects, long-running behavior, or error handling, which is especially important for a complex tool with 14 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and directly states the purpose and a key usage warning. It is not bloated and the most important information is front-loaded. However, for a tool this complex, the brevity feels more like under-specification than skillful conciseness, so I would not give a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 14 parameters, no annotations, no output schema, and many sibling tools. The description only provides two sentences of high-level context. It does not explain what the tool returns, whether it blocks, how it relates to start_execute_seed, or any operational caveats. This is severely incomplete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes all 14 parameters with 100% coverage, so the description does not need to explain each one. The description adds conceptual context for what a seed is, which supports seed_path and seed_content, but beyond that it does not add meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a seed (task specification), using a specific verb and resource. It also identifies itself as the handler for 'ooo run' commands. However, it does not differentiate itself from the sibling tool ouroboros_start_execute_seed, which likely runs the same operation asynchronously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage guidance is a warning not to run 'ooo' in the shell and to use this MCP tool instead. It provides no guidance on when to choose this over sibling tools like ouroboros_start_execute_seed, ouroboros_auto, or ouroboros_start_auto. No exclusions or alternative selection criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. The phrase 'Request cancellation' hints that the operation may be asynchronous, but it does not disclose side effects, idempotency, or how to check the outcome. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no fluff, which is appropriately concise for the tool's simplicity. However, it omits important contextual information, so it is not maximally effective as a standalone resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no annotations and no output schema, the description is too minimal to be complete. It does not mention that cancellation may be asynchronous, how to verify cancellation, or how it differs from cancel_execution. This leaves significant gaps for an agent attempting to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description itself adds no parameter details, but the schema has 100% coverage for the single parameter (job_id) with a helpful description ('Job ID returned by a start tool'). Since the schema fully documents the parameter, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Request cancellation') and the resource ('a background job'), which is specific and unambiguous. However, it does not explicitly distinguish from sibling tools like ouroboros_cancel_execution, so it misses the top score for sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as ouroboros_cancel_execution, or how it relates to job lifecycle tools (job_status, job_wait). The description does not specify preconditions or expected use cases beyond the obvious cancellation context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the tool 'Returns a list of events matching the specified criteria,' which is minimal. It does not mention pagination behavior, ordering, potential side effects, or that omitting session_id returns events across all sessions—though the schema hints at that. This is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence: 'Query the event history for an Ouroboros session. Returns a list of events matching the specified criteria.' It is front-loaded with the main action and contains zero fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (4 params, no output schema, no annotations), the description is too thin. It lacks essential context such as the meaning of limit/offset defaults, any explanation of event types, and the fact that session_id is optional (despite implying a session is required). No output schema exists to clarify return values, so the description should have provided more detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no extra parameter semantics beyond the schema; it merely refers to 'specified criteria' without explaining any parameter syntax or additional meaning. The schema already documents limit, offset, event_type, and session_id, so no deduction is needed, but no enhancement is provided either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Query the event history for an Ouroboros session' and that it 'Returns a list of events matching the specified criteria.' This is a specific verb+resource pair. It does not explicitly distinguish itself from siblings, but its focus on event history makes it distinct from other Ouroboros tools like query_projection or session_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: this tool should be used when you need to query event history. However, there are no explicit when-to-use vs alternatives, nor any exclusions or comparisons to sibling tools. The description provides no guidance on when to use this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It adds behavioral context with 'latest' and 'summary' implying a non-blocking, summarized status read, and 'background' clarifies the job type. However, it does not disclose return format, error behavior, or explicitly confirm read-only semantics beyond the verb 'Get'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with fully described schema, the description is reasonably complete. However, there is no output schema and the word 'summary' is vague; additionally, the lack of guidance among several job-related sibling tools leaves contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with descriptions for both job_id and view. The tool description adds no parameter-specific meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Get') and specific resource ('latest summary for a background Ouroboros job'), which makes the purpose understandable. It does not explicitly differentiate from sibling tools like ouroboros_job_result or ouroboros_job_wait, so it stops short of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as ouroboros_job_result or ouroboros_job_wait. The description only states what the tool does, without any context about polling, final results, or when it should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It communicates that the tool is a live, read-only snapshot and indicates the output format, which is useful. However, it does not disclose cursor-advance behavior, potential side effects, or failure modes, leaving some ambiguity around the 'cursor' parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. Every word earns its place, and it conveys the essential purpose and output format without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only snapshot tool, the description combined with the schema provides adequate completeness. The return value is described as a markdown snapshot, and all parameters are documented. However, the lack of any mention of error conditions or cursor semantics slightly limits completeness given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the input schema already explains all four parameters including their defaults and meanings. The tool description itself adds no additional parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a render-ready markdown snapshot of the live acceptance-criteria tree for a session, using a specific verb and resource. It is distinct from generic status tools, though it does not explicitly differentiate itself from the sibling tool 'ouroboros_ac_dashboard'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no context for appropriate scenarios, and no exclusions. Usage is only implied by the verb 'Return', leaving the agent to infer when this snapshot is preferred over dashboard or status tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The verb 'Query' implies a read-only behavior and the return list clarifies the expected outcome, but there is no explicit statement about side effects, permissions, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: a focused action verb followed by a concise list of return fields. Every word contributes value, and it is perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with a single parameter and no output schema, the description covers the essentials: what it does and what it returns. It doesn't specify error handling or detailed lifecycle context, but it is largely complete for this use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for lineage_id with a clear description. The tool description adds little beyond naming the resource as an 'evolutionary lineage', so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Query' and the resource 'evolutionary lineage', and lists specific return values (generation count, status, ontology evolution, convergence progress). It does not explicitly differentiate from sibling status tools, which prevents a top score, but the resource is distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus sibling status tools like ouroboros_session_status or ouroboros_project_status. There is no mention of exclusions, prerequisites, or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does not disclose what happens if the job is not complete, whether the result can be retrieved multiple times, or any error behavior. 'Get' suggests read-only, but no explicit safety or side-effect information is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that is clear and wastes no words, making it easy for an agent to quickly grasp the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, no output schema), but the description leaves gaps about return format and behavior for incomplete jobs. Given the many job-related siblings, more differentiation would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the only parameter (job_id as 'Job ID returned by a start tool'), and the description adds marginal context by linking it to a 'completed background job', but does not provide additional format or usage details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('final output for a completed background job'), clearly distinguishing it from sibling tools like job_status (status) and job_wait (waiting). The inclusion of 'completed' sets a condition that adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for a completed background job' implies the tool should only be used after job completion, but it does not explicitly state when to use it versus alternatives like ouroboros_job_status or ouroboros_job_wait, nor does it mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the tool returns information, implying a read-only operation, but does not explicitly state safety guarantees, behavior on invalid session IDs, or any side effects. For a status query, this is minimally acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, directly to the point, with no redundant information. Every word adds value, front-loading the main purpose and then elaborating on the return content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a single parameter and no output schema, the description adequately covers the tool's function and return contents (phase, progress, errors). It is complete enough for an agent to understand what to expect, though it omits potential error scenarios or session lifecycle context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the parameter (session_id) with a clear description 'The session ID to query'. The tool description adds no additional parameter semantics beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' with a clear resource ('status of an Ouroboros session'). It also states what information is returned (phase, progress, errors), which distinguishes it from sibling tools like job status or lineage status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking session status but provides no explicit guidance on when to use this tool versus alternatives like ouroboros_job_status or ouroboros_lineage_status. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It does disclose the behavioral output ('Shows which acceptance criteria passed, failed, or are flaky') and the display modes, which implies a read-only dashboard. However, it does not explicitly state that this is a non-mutating operation, nor does it mention any prerequisites or side effects, which are relevant for a tool in this family.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with three short sentences that each carry critical information: what the tool does, what it shows, and the available modes. There is no filler, and the most important verb-resource pair is front-loaded. This is efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description covers the essential purpose and mode behaviors. It does not explain the return format or the dependency of 'ac_index' on 'mode', but the schema covers the latter. It is complete enough for an agent to understand when and how to invoke it, though a bit more detail on output could improve it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters with 100% coverage, giving a baseline of 3. The description adds meaningful context by explaining the 'full' mode as 'AC x Gen matrix' and 'ac' mode as 'single AC history', which enriches the semantics of the 'mode' parameter beyond the schema's brief description. This added value justifies a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Display per-AC pass/fail compliance dashboard across generations.' It specifies the verb 'Display' and the resource (AC compliance dashboard), and includes what it shows (passed, failed, flaky). However, it does not explicitly distinguish this tool from its sibling 'ouroboros_ac_tree_hud', so it lacks a direct differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when needing a compliance dashboard) and provides mode guidance ('summary' default, 'full', 'ac'), but it does not explain when to use this tool versus alternative sibling tools such as 'ouroboros_ac_tree_hud' or 'ouroboros_lineage_status'. There are no explicit exclusions or alternative recommendations, so usage context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It only lists high-level actions without disclosing side effects, persistence behavior, or nuances like the fact that 'set_default' does not clear other defaults. This is a significant gap for a management tool that modifies state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the tool's purpose and lists the primary actions. Every word earns its place, and it is well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 parameters and multiple actions, the description covers scan, register, query, and set_default, but omits the 'set_defaults' action and provides no detail on behavior or edge cases. However, the schema covers parameters thoroughly, and there is no output schema requiring explanation. Adequate but with room for more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the parameters with detailed descriptions, so the baseline is 3. The tool description adds no additional parameter semantics beyond what the schema already provides, but given full schema coverage, this is acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool manages brownfield repository registrations, listing specific operations: scanning home directory, registering/querying repos, and setting default context. This distinguishes it from sibling tools which focus on jobs, interviews, and execution, not repository management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for usage: scanning the home directory, registering/querying repos, and setting default context for PM interviews. It does not explicitly mention alternatives or when not to use, but the context is sufficiently clear for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses validation behavior (checks existence and terminal state) but does not explain side effects, such as whether cancellation is irreversible, what state the execution transitions to, or any required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and every phrase adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple cancellation tool but lacks important context: no mention of irreversibility, relationship to 'ouroboros_cancel_job', or expected outcome. Without an output schema or annotations, these gaps are notable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to explain parameters. The description mentions 'execution exists' which ties to execution_id, but adds no extra meaning beyond the schema. The baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Cancel a running or paused Ouroboros execution') with a specific resource and scope. However, it does not differentiate from the sibling tool 'ouroboros_cancel_job', which could be confused with cancellation of a job rather than an execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use when execution is running or paused, and it implies not to use when in a terminal state. It does not explicitly mention alternatives or exclusions, but the context is sufficient for basic guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It mentions 'briefly' and 'wait', but the crucial default behavior (immediate snapshot when timeout_seconds is 0) is only described in the schema parameter documentation, not in the main description. 'Briefly' is vague and arguably misleading without the schema, but the schema does compensate, and there is no direct contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short, information-dense sentences with no filler. Every word earns its place: 'wait', 'briefly', 'background job', 'change state', 'conversational polling', 'after a start command'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the schema is rich, the description alone omits important context such as the default no-wait behavior, what 'change state' covers (e.g., progress, terminal status), and how this relates to job_status/job_result. There is no output schema, so the response format is unstated. The description orients the user but is not complete for a tool with 6 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all 6 parameters, including defaults like timeout_seconds=0 and options for wait_for and stream. The main description adds no parameter-specific meaning, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb 'Wait' and a clear resource 'background job to change state', which distinguishes it from sibling status/result tools. The second sentence adds useful context about use after a start command, though it doesn't explicitly name alternatives like job_status or job_result.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when the tool is useful: 'conversational polling after a start command'. This gives clear context, but it doesn't provide exclusions or mention alternative tools, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the weighted formula (goal drift 50%, constraint drift 30%, ontology drift 20%) and the return behavior (drift metrics, analysis, suggestions conditional on threshold). This is valuable beyond the schema, though it omits side effects and error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the primary purpose and following with formula and output. Every sentence adds value, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters and no output schema. The description explains the return type at a high level (metrics, analysis, suggestions) but lacks detail on output structure and edge cases like threshold definition. It is adequate but incomplete for fully understanding expected results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented in the schema. The description adds context about the weighting components but does not further explain individual parameters or how they map to the calculation. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool measures drift from the original seed goal, with a specific verb and resource. It also describes the calculation components and output, making the purpose clear. However, it does not explicitly differentiate from sibling tools like ouroboros_evaluate or ouroboros_session_signal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: when you need to measure drift from a seed goal. It does not provide explicit when-to-use vs. when-not-to-use guidance or mention alternative tools. There are no exclusion criteria or context about prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses 'read-only' up front, which is a key behavioral trait. However, it lacks additional context such as failure modes, result format, or prerequisites beyond what the parameter schema already provides. The read-only designation is valuable but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core action and scope. Every word contributes meaning, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple with no output schema or annotations, and the description covers the primary purpose. However, it does not describe the shape of the projection, potential failure conditions, or how it relates to the sibling query tool, leaving some gaps for an agent to discover.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description itself adds no parameter information; all semantics come from the schema's detailed descriptions of limit, seed_id, session_id, and execution_id. The schema does the heavy lifting, so no credit is lost or gained beyond baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Build' and the specific resource 'read-only Run/Stage/Step projection' from persisted events for a session or execution aggregate. This distinguishes it from sibling tools like ouroboros_query_events, which likely returns raw events rather than a structured projection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context ('for a session or execution aggregate') but does not explicitly state when to use this tool over alternatives or when not to use it. No exclusions or alternative tool mentions are provided, leaving the agent to infer when a projection is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the background execution, immediate job_id return in non-plugin runtimes, delegation in plugin mode, and the five stopping conditions. It does not describe side effects or required permissions, but for a background loop tool this is substantial transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three dense sentences that front-load the purpose, then efficiently cover runtime behavior and termination conditions. Every clause adds value, with no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high parameter count (19), no output schema, and no annotations, the description provides strong contextual grounding: it explains the loop lifecycle, job_id usage for follow-on tools, and plugin-mode behavior. It could mention prerequisites (e.g., lineage existence) or clarify 'first-class', but overall it is well-rounded for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description itself adds no parameter-specific meaning, but the schema already provides thorough details for each of the 19 parameters, including ranges, defaults, and runtime enforcement nuances.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool starts a background Ralph loop and details the loop's termination conditions. However, it does not explicitly differentiate from the similarly named ouroboros_start_ralph sibling, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The implied usage is clear: use this to start a full Ralph loop that runs evolve_step iteratively. Yet there is no explicit guidance on when to prefer this over ouroboros_start_evolve_step, ouroboros_auto, or other siblings, and no exclusions or alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It clearly discloses the three-stage process and the consensus trigger, which is meaningful about how the tool behaves. However, it stops short of stating whether the operation is read-only or what side effects or return format to expect, preventing a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the main verb and resource, and each sentence earns its place by explaining one stage of the pipeline. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is thorough about the evaluation process but omits what the tool returns or how to interpret the output. With no output schema present, this is a notable gap. The rich parameter descriptions compensate for some context, but the main description alone is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The main description adds no parameter-specific meaning beyond the schema, but it does not need to because every parameter is already well documented. The pipeline overview subtly relates to trigger_consensus but adds no new semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Evaluate') with a clear resource ('an Ouroboros execution session') and adds a concrete three-stage pipeline. It distinguishes this as the evaluation tool among many ouroboros sibling tools by describing the exact stages, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for evaluating execution sessions but does not explicitly state when to use it over siblings like ouroboros_start_evaluate or ouroboros_qa. The stage-level detail provides context but no explicit exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses key behaviors: background execution, immediate job ID return, and plugin-mode delegation with job_id=None. Yet it does not cover potential side effects, failure modes, or what happens to lineage state, leaving notable gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and contains no filler. Every clause adds useful information about behavior or plugin mode, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 16 parameters and no output schema, the description provides essential async behavior and plugin caveat but omits other return-value details and broader workflow orientation. It references job_status/job_result for polling but does not explain other possible response fields or prerequisites, leaving moderate gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 16 parameters, so the baseline is 3. The description itself adds no parameter-specific meaning beyond what the schema already provides, so it neither improves nor harms.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource: 'Start one evolve_step generation in the background and return a job ID immediately'. It clearly distinguishes this background tool from synchronous siblings like ouroboros_evolve_step and from status/result tools by emphasizing immediate return and later polling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you want background execution and a job ID to poll later, contrasting with plugin mode where results appear in the Task pane instead of being pollable. However, it does not explicitly name alternatives or provide exclusions, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description adds some behavioral context: the A-grade gate blocks execution until quality is met, and all loops are bounded. However, it does not detail side effects, runtime expectations, or interaction with resume/attach options, leaving a gap for such a complex tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose and followed by a key safety guarantee. It is appropriately concise, leaving parameter details to the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (20 parameters, nested options) and no output schema, the description gives the essential pipeline overview but omits broader context like resume/attach/reconciliation workflows. However, the schema covers parameter details thoroughly, so the combination is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented in the schema. The description itself does not elaborate on any parameters, providing no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Run') and names the resource/pipeline (full-quality ooo auto). It enumerates the key steps (interview, generate A-grade Seed, execute after gate) which distinguishes it from simpler siblings like execute_seed or start_auto.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys a clear context: this is the complete automatic pipeline with a quality gate. It does not explicitly mention alternatives or exclusions, but the workflow description implies when to use it (for full auto runs).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive, but the description adds critical failure semantics: identity conflicts, projection failures, and exceed limit returns no partial record. It also clarifies reconstruction from persisted events, which is useful beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, followed by concise behavioral caveats. Every word earns its place, with no repetition of schema or annotation content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, annotations covering safety, and 100% parameter documentation, the description sufficiently conveys the tool's core behavior and failure conditions. It lacks usage comparisons, but that gap is covered by the usage_guidelines dimension, not completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds a slight nuance by referencing 'limits below the complete population' which aligns with the limit parameter's documented behavior, but it does not provide extra semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly names the verb ('resolve', 'rebuild') and resource ('project identity', 'complete read-only run status'), which is specific and self-contained. It distinguishes from sibling status tools by focusing on project run status rebuilt from persisted session events, not lineage, session, or job status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the many sibling status tools (e.g., ouroboros_lineage_status, ouroboros_session_status). The description does not mention alternatives or exclusions, leaving the choice to the agent to infer from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. It does disclose key runtime behavior: the tool runs in the background, returns immediately, and delegates to a Task pane in plugin mode with job_id=None. However, it does not state whether the operation is mutating, what side effects or permissions are required, or how idempotency_key interacts beyond the schema. This is partial disclosure, not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each serving a distinct purpose: core action, monitoring pointers, plugin exception, and shell alias warning. It is front-loaded with the primary behavior and uses no filler words. This is exemplary economy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 15 parameters and no output schema, the description covers the most important context: the async job model, where to find progress/output, the plugin-mode behavioral shift, and the relationship to the 'ooo' shell command. It does not explain return value structure, but no output schema exists and the job_id/None behavior is disclosed. It is complete enough for a high-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each of the 15 parameters having meaningful descriptions in the input schema. The tool description itself adds no parameter-specific semantics—it stays at the level of execution mode and monitoring. Per rubric, this hits the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Start a seed execution in the background and return a job ID immediately,' clearly identifying the verb (start), resource (seed execution), and immediate outcome (job ID). It also notes it is the handler for 'ooo run' commands, which distinguishes it from a shell command but does not explicitly contrast it with sibling tools like ouroboros_execute_seed. This implicit differentiation prevents a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs users to 'Use ouroboros_ac_tree_hud for live progress snapshots and ouroboros_job_result for terminal output,' providing clear alternatives for post-start actions. It also warns 'do NOT run ''ooo'' in the shell; call this MCP tool instead,' a concrete when-not instruction. The plugin-mode caveat further clarifies when job polling is unavailable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the mutating successor ownership requirement and the phase ordering, but omits details like idempotency behavior, whether updates are allowed, or what happens on duplicate decision IDs. It mentions 'audited' but doesn't explain traceability features.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action, followed by essential constraints. Zero filler; every clause adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite high schema coverage, the tool has 16 parameters and a multi-phase state machine. The description provides only a high-level phase sequence and one precondition, lacking an overview of how the decision record relates to successor execution or the two-successor budget. It is minimally viable but leaves gaps for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 16 parameters have schema descriptions (100% coverage), so baseline is 3. The description adds lifecycle context for 'phase' and a constraint for 'engine_ownership_state' that goes beyond the schema. It does not discuss the other parameters, but the schema covers them adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Record an audited Active Conductor decision.' The verb 'record' and resource 'Active Conductor decision' are specific, and the phase lifecycle distinguishes it from related tools like ouroboros_auto or ouroboros_execute_seed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains the temporal usage: record phase=selected before an action, then completed/failed/declined after the outcome. It also states a precondition: 'Mutating successors require engine_ownership_state=closed.' However, it does not explicitly name alternative tools or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explains the two runtime modes: non-plugin returns job_id immediately for polling, while plugin mode delegates and returns job_id=None with status='delegated_to_plugin', noting results are not pollable. This goes beyond a simple 'starts a loop' and covers key behavioral outcomes, though it omits details like error handling or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single opening clause states the core purpose, followed by two sentences detailing behavioral modes. Every sentence earns its place, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the complexity (19 parameters, nested objects, no output schema), the description covers the most critical aspects: fire-and-forget nature and mode-specific return behavior. However, it omits details about the response structure beyond job_id/status, potential error conditions, and any prerequisites like lineage_id, which might be expected given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter-specific semantics beyond what the schema already provides; it only mentions job_id and status which are return values, not parameters. Therefore, it neither enhances nor detracts from schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function as a 'Fire-and-forget alias for ouroboros_ralph' that 'Starts the same runtime-owned Ralph loop.' This gives a specific verb ('starts'), a resource ('Ralph loop'), and its nature as an alias, distinguishing it from the synchronous ouroboros_ralph sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: for fire-and-forget invocation when immediate job_id is needed, contrasted with plugin mode delegation. It does not explicitly name alternatives like ouroboros_ralph for synchronous use, but the 'alias' framing implies the distinction. No explicit exclusions are given, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly states the destructive action ('Truncates all generations after the target'), the emitted event, and the continuation capability. This is strong for a mutation tool, though it omits any mention of error handling or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core purpose. Each sentence adds meaningful behavioral information (truncation, event, continuation) with no filler or unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation tool with no output schema, the description covers the key aspects: the action, the destructive scope, the event emitted, and that evolution can resume. Minor gaps like prerequisites or error conditions are not required for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for lineage_id and to_generation (inclusive). The description adds no parameter-specific details beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Rewind an evolutionary lineage to a specific generation.' It also explains the effect (truncating generations after the target) and a distinguishing event (emits lineage.rewound), which differentiates it from forward-stepping tools like ouroboros_evolve_step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: rewinds to a generation, truncates subsequent ones, and allows the lineage to continue. It does not explicitly discuss alternatives or exclusions, but the behavior is well enough described to infer when to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the output format ('structured verdict with score, differences, and actionable suggestions') and the intended iterative loop usage. However, it does not mention side effects like session creation when qa_session_id is omitted, which is a behavioral nuance in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loads the main purpose, then explains the output and usage context. Every sentence adds value with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters and no output schema, the description adequately summarizes the return shape and intended usage context without needing to describe every parameter. It could offer slightly more detail on threshold/iteration history, but schema covers these, so this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema by mentioning artifact types and quality bar, but it does not clarify parameter formats or edge cases beyond what parameter descriptions already state.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Evaluates') and resource ('any artifact type'), enumerating examples like code, API responses, documents, screenshots, and custom artifacts. It also specifies the output ('structured verdict with score, differences, and actionable suggestions'), distinguishing it from general-purpose helpers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says it is 'General-purpose' and 'Designed for iterative loop usage', giving a clear context for when to use it. It lists supported artifact types but does not explicitly mention alternatives or exclusions, so it misses the top level of guidance by not naming when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It reveals that execution is asynchronous ('in the background'), non-blocking ('return ... immediately'), resumable, and that the final state must be read via other tools. It does not cover failure modes, cancellation, or resource implications, but the key behavioral traits are communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and return values, and every clause provides essential workflow information. No filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the complete high-level flow: start, resume, poll, and read result, which is sufficient for a 20-parameter tool with 0 required params and comprehensive schema descriptions. It does not describe all possible parameter interactions, but the schema already provides field-level detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so every parameter already has a description. The tool description adds no parameter-level semantics beyond noting that a returned auto_session_id can be used for resume, which indirectly supports the resume parameter. Baseline 3 is appropriate since schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Start ooo auto in the background' and specifies the immediate return values ('auto_session_id + job_id'). This distinguishes it from siblings like ouroboros_auto by emphasizing the background/asynchronous nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for use: launch in the background and get immediate IDs. It also provides a follow-up workflow ('Resume with the returned auto_session_id; poll with ouroboros_job_status / ouroboros_job_wait and read final state via ouroboros_job_result'), though it does not explicitly contrast this tool with ouroboros_auto or list exclusion scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses plugin-mode behavior (delegation receipt, OpenCode Task pane, real session_id returned there), which is a valuable trait. It lacks disclosure of normal-mode return values or persistence side effects, preventing a higher score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two focused sentences, front-loaded with the core purpose and then the plugin-mode caveat. Every sentence contributes value, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters and no output schema, the description is not fully complete. It explains plugin-mode returns but not standard-mode responses, error conditions, or the overall interaction loop. The parameter schema helps, but the main description leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with rich per-parameter text, so the baseline is 3. The main description adds meaning by mapping parameters to actions (initial_context for start, session_id for resume, answer for recording), which goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Interactive interview for requirement clarification,' providing a specific verb and resource. It clearly distinguishes itself from sibling tools like ouroboros_pm_interview by specifying its focus on requirement clarification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly describes three invocation modes—start with initial_context, resume with session_id, or record an answer—giving clear context for usage. However, it does not compare directly to alternative tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden and does add useful behavior: it is a single-step operation, state is reconstructed from events in later generations, and ontology_stable is a non-success handoff requiring a rerun with execute=true. It does not explicitly state side effects such as event/checkpoint writes or system modifications, which would make it fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the primary purpose; every clause adds operational information (generation rule, return values, next-action enum, ontology_stable handoff). No filler or repetition of schema-only content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 16-parameter tool with no output schema and no annotations, the description covers the core loop semantics, input requirements, return summary, and next-action vocabulary. It does not provide detailed return shape or failure handling, but the rich schema plus this workflow narrative is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds generation-specific semantics beyond the schema by telling the caller which parameters are relevant for Gen 1 vs Gen 2+ and by explaining that execute=true is used to move past ontology_stable. This enriches the meaning of lineage_id, seed_content, and execute.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action: 'Run exactly ONE generation of the evolutionary loop,' which names both the verb and resource. It also segments Gen 1 vs Gen 2+ usage, making the tool's distinct role among evolve/auto siblings clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit input requirements per generation ('Gen 1: provide lineage_id and seed_content', 'Gen 2+: provide lineage_id only') and how to handle the ontology_stable handoff with execute=true. It does not explicitly contrast with sibling tools like ouroboros_auto or ouroboros_start_evolve_step, so it stops short of full alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the seed is immutable, generation is gated by ambiguity_score, and force=true bypasses the gate. It does not cover all side effects, but the critical gate behavior and immutability are transparently stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: purpose, output content, and gating condition. No fluff or repetition; it is concise and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params, no output schema, no annotations), the description explains the essential behavior and gate. It omits potential error cases or return value details, but this is acceptable as the seed generation step is well-contextualized by the completed interview session and sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% so the baseline is 3. The description adds value beyond the schema by explaining the interaction between ambiguity_score and force, i.e., the threshold and bypass mechanism, which is not evident from individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Generate an immutable Seed from a completed interview session.' It specifies the action (generate), the resource (Seed), and the source (completed interview), distinguishing it from siblings like execute_seed which consumes seeds.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: after an interview session is complete and when ambiguity is low (<=0.2) or when force=true is passed. It does not explicitly mention alternatives or exclusions, but the context is unmistakable and the condition adds practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does a good job: it explains plugin-mode execution, the delegation receipt (status=delegated_to_subagent), where the real session_id is returned, and that action can be auto-detected. It also mentions that brownfield context is loaded from DB. These are meaningful behavioral details beyond the schema, though it does not cover every edge case like error handling or persistence side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description packs a wealth of information into two dense sentences. It front-loads the purpose and then logically explains the three usage modes with clear parameter references. Every clause serves a purpose; the plugin-mode caveat is included succinctly. No filler or redundant restatement of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no output schema, and no annotations, the description plus rich parameter descriptions provide a solid understanding. The description covers the core interaction patterns and the important plugin-mode exception. It lacks explicit details on response formats (beyond the delegation receipt) and failure conditions, but given the complexity, it is reasonably complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 7 parameters are documented), so the baseline is 3. The description adds value by explaining the workflow: initial_context starts, session_id+answer resumes, and action='generate' produces a PM seed. This explicitly ties parameters to usage modes and clarifies auto-detection, going beyond the individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'PM interview for product requirements gathering,' which clearly states a specific verb (interview) and resource (product requirements). It distinguishes this tool from siblings like ouroboros_interview by focusing on PM/product requirements scope and its multi-step workflow. The description also enumerates distinct usage modes, leaving no ambiguity about what the tool accomplishes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit instructions on how to interact: 'Start with initial_context, continue with session_id + answer, or generate PM seed with action='generate'.' This is clear when-to-use guidance for each parameter combination. It also notes the plugin-mode delegation behavior, which is an important operational context. However, it does not explicitly compare against alternative tools or state when not to use this tool, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral transparency burden. It discloses that advertised modes are valid direct requested modes, explains the one allowed fallback path (redirect with fallback_mode=after_turn only when after_turn is advertised), and states that shipped adapters do not support redirect/replace and that other unsupported requests fail closed. This gives an agent a clear understanding of the tool's behavior and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but each sentence adds essential information: the primary purpose, the validity of advertised modes, the explicit fallback path, and the failure behavior for unsupported requests. It is front-loaded with the main purpose and maintains a logical flow, though it is slightly longer than strictly necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description fully conveys what the tool returns (a list of active AC attempts with their SessionSignal capabilities), and it goes beyond basic expectations by explaining fallback semantics and unsupported-request behavior. Given the tool's complexity (one parameter, discovery-oriented), the description is adequately complete for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a clear description for the single parameter execution_id ('Execution ID returned by run/auto/evolve/ralph start or its job observer'), and the tool description does not add further parameter-level detail. With schema description coverage at 100%, the description does not need to compensate, and the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'List exact active AC attempts and each attempt's live SessionSignal capabilities for one execution before sending a signal,' which clearly states a specific action (List), resource (AC attempts and their SessionSignal capabilities), and scope (for one execution). This explicit verb+resource+scope structure distinguishes it from sibling tools like ouroboros_session_signal (sending signals) and ouroboros_session_status (session status).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'before sending a signal' clearly indicates when to use this tool, and the description provides detailed context around valid fallback paths and unsupported requests, guiding when to ask the user for clarification. However, it does not explicitly name alternative tools or state when not to use this tool, so it just misses the highest bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It discloses a critical behavioral trait: fanning out to multiple personas runs them in parallel as separate Task panes with independent LLM contexts and no cross-contamination. This goes beyond the schema and is essential for the agent to understand side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences with no filler. The second sentence is dense but packs in essential details about parallel dispatch and independent contexts. It is appropriately sized for the complexity, though a touch run-on.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has six parameters (two required) and no output schema. The description covers the main workflow well, including the persona list and parallel behavior. However, it does not mention the stagnation_pattern parameter's role in auto-suggesting a persona or explicitly describe the return format, leaving minor gaps that the schema alone fills.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and every parameter already has a clear description. The tool description adds useful context about parallel execution and persona use, but largely restates schema information (e.g., 'personas' precedence is already in the schema). Thus the description adds only marginal semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Generate' with the resource 'alternative thinking approaches' and enumerates five distinct personas (hacker, researcher, simplifier, architect, contrarian). This clearly differentiates the tool from sibling tools that manage jobs, seeds, or sessions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use this tool when stuck on a problem to get fresh perspectives'—a clear trigger condition. It also explains how to select a single persona or fan out with 'all' or 'personas', and notes that 'personas' takes precedence, giving actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels: it discloses that shipped adapters only advertise/apply inform and after_turn, that redirect and replace are reserved, that redirect has one explicit fallback path, that unsupported requests fail closed, and that 'A queued result does not mean the signal was applied.' This is comprehensive behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded with the core purpose, but it is relatively long and consists of a single block of text. Every sentence contributes valuable constraint information, so length is justified, but it would benefit from clearer structural separation (e.g., bullets).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 13-parameter tool with no output schema, the description covers the tricky mode logic, fallback, failure behavior, and a prerequisite query. It does not explain the response shape (though it warns about queued results), which is a minor gap given no output schema, but overall it is sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed per-parameter descriptions, so the baseline is 3. The tool description reinforces mode/fallback semantics but does not add new parameter-level meaning beyond what is already in the schema; it is contextual rather than parameter-specific.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Send one audited Ouroboros Synapse intent signal to an exact active AC session attempt.' This clearly distinguishes it from sibling tools like ouroboros_session_signal_targets, which is referenced for querying capabilities, and from other session/execution tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use and when-not-to-use guidance: it directs the agent to 'Query ouroboros_session_signal_targets for the selected exact attempt's live capabilities before sending,' details the sole fallback path for redirect (fallback_mode=after_turn and attempt advertising after_turn), and states that 'All other unsupported requests fail closed.' This goes beyond vague context and names a specific alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the async job behavior, the None job_id delegation to an OpenCode Task pane in plugin mode without auto_evolve, and how auto_evolve keeps evaluation pollable for Ralph rejection. This goes well beyond the schema's basic parameter descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences of dense, useful content with no filler. It front-loads the core action, then provides alternative selection, polling workflow, and edge-case behavior, earning every sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, so the description must explain the return contract, which it does: immediate job ID, None in certain plugin mode, and verdict via ouroboros_job_result. It also covers the key behavioral branches (plugin mode, auto_evolve), making it complete for a 10-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with each parameter already having a rich description. The top-level description does not add parameter-specific meaning; it focuses on workflow and alternatives, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Start an evaluation in the background and return a job ID immediately.' It explicitly distinguishes from the sibling ouroboros_evaluate by positioning itself as the background variant for long-running pipelines, making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to prefer this over ouroboros_evaluate (when the three-stage pipeline is expected to exceed the MCP timeout) and names the exact sibling tools for polling and result retrieval (ouroboros_job_status, ouroboros_job_wait, ouroboros_job_result). It also covers plugin-mode and auto_evolve-specific usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the exact input contract (one {key, content} per child, key equals correlation field, undispatched sentinel), the 'never invent output' rule, the `status=partial` error condition for missing keys, and the return artifact envelope with explicit fetch instructions. This is exceptional behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense yet efficiently structured, front-loading the purpose and then providing necessary protocol details. Every sentence earns its place: correlation key mapping, undispatched handling, missing-key behavior, and envelope retrieval. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with no output schema, the description explains the prerequisite (spawned subagents with meta), the exact payload format, partial submission behavior, and how to fetch the result artifact. It leaves little ambiguity about the workflow, making it complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond the schema by explaining how `key` maps to the correlation field, how `results` entries should be structured, and the retry requirement for partial submissions. It doesn't fully compensate for the schema because the schema is already descriptive, but it enhances understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Submit correlated results from a subagent fan-out back to Ouroboros,' using a specific verb ('submit') and a clear resource (correlated results). It distinguishes itself from sibling tools like ouroboros_auto or ouroboros_session_signal by its unique role in the fan-out submission flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to call: 'After spawning the advisory/persona/investigation subagents declared by a prior tool's meta... call this tool with one {key, content} per child output.' It also provides guidance on handling undispatched children and missing keys. However, it does not explicitly name alternative tools or exclusions, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Q00/ouroboros'
If you have feedback or need assistance with the MCP directory API, please join our Discord server