sovereign-stack

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.6.1
Disambiguation4/5
Most tools have clearly distinct purposes, but there are a few overlapping groups like the many 'record_*' tools and 'get_*' tools that could cause confusion. However, descriptions are detailed enough to differentiate them in most cases.
Naming Consistency3/5
The naming convention is inconsistent: while many follow a verb_noun pattern (e.g., record_insight, recall_insights), there are several outliers like 'where_did_i_leave_off', 'start_here', 'handoff', and 'reflection_ack' that break the pattern. This mixed style reduces predictability.
Tool Count2/5
With 84 tools, the count is very high for an MCP server. Even for a complex domain, this number is excessive and likely overwhelms agents. Many tools are overly specific (e.g., store_compaction_summary is automatically called), suggesting the set could be consolidated.
Completeness4/5
The tool set covers a very broad range of functionality including boot, memory, security, communication, and experimentation. However, it lacks update/delete operations for insights and has no explicit search tool, which are minor gaps in an otherwise comprehensive surface.
Average 3.6/5 across 75 of 84 tools scored. Lowest: 1.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 130 commits in the last 12 weeks
- Last stable release on May 27, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
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.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
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

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description fails to disclose whether the tool is read-only, its side effects, return value, or any behavioral traits. Without this, the agent cannot assess safety or impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence, which is concise, but it lacks structure and key information. Brevity without substance is not effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, and the description gives no indication of what the tool returns, whether it records or modifies state, or how to interpret results. For a tool with a single required parameter and many siblings, this is critically incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'context' has minimal schema description ('Current context to match'). The tool description adds no extra meaning—e.g., what format the context should be, how matching works, or what constitutes 'relevance'. Schema coverage is 100% but the description is too thin to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Check for relevant past learnings' is vague; 'check' is ambiguous and doesn't specify the action (e.g., retrieve, compare, alert). The tool name 'check_mistakes' suggests mistakes, but description says 'learnings', causing confusion. Sibling tools like 'recall_insights' and 'recall_reflections' have overlapping purpose, and no differentiation is provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as 'recall_insights' or 'recall_reflections'. The description does not mention any conditions, prerequisites, or exclusions, leaving the agent without context to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description omits any behavioral details such as return format, side effects, or data scope. The agent gains no insight into what happens when the tool is invoked.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single short sentence, which is concise but lacks structure and front-loads no actionable information. It is not verbose but also not helpfully organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description should clearly explain what growth data is summarized and over what period. It fails to do so, leaving the agent completely uninformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no parameters and schema description coverage is 100% (empty schema). Description adds no meaning but also does not contradict the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description 'See how I'm growing over time' is vague. It does not specify what 'growth' refers to (e.g., skill, usage, knowledge) and fails to distinguish the tool from similar siblings like self_model or get_my_patterns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. With many sibling tools covering self-reflection and patterns, the description provides no context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description provides no behavioral details such as read-only nature or side effects. For a tool with zero annotations, the description must carry the full burden of disclosure, but it fails to mention even basic traits like idempotency or data scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is excessively brief and phrased as a question, which is not a proper description. It is under-specified rather than concise, sacrificing informativeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters, no output schema), a clear one-sentence description could be sufficient. However, the current description is incomplete and ambiguous, failing to clearly convey the tool's purpose or the nature of the returned data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4 per the scoring guidelines. The description does not need to add parameter semantics, but it also does not detract. The schema coverage is 100% vacuously.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a vague question ('What are we still figuring out together?') rather than a clear statement of the tool's function. It implies retrieving unresolved uncertainties but lacks a specific verb and resource description. The name provides clarity, but the description fails to independently state the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does 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 related siblings (e.g., resolve_uncertainty, mark_uncertainty). There is no context about prerequisites, alternatives, or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose whether this operation is read-only, modifies state, or has side effects. The agent cannot infer safety or cost.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded, but it sacrifices necessary detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description should clarify the nature of 'latent structure' and the output format, which it fails to do.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'paths' is described as 'a list of paths' but the term 'path' is ambiguous (file paths, URLs, abstract paths). The schema has no description coverage, so the description adds minimal meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a verb 'discover' and identifies 'paths' as input, but 'latent structure' is vague and does not clearly distinguish this tool from siblings like 'get_my_patterns' or 'synthesize_now'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over alternatives; there is no mention of context or exclusions, leaving the agent to guess.
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 provided, so description must carry behavioral disclosure. It mentions 'potentially advance spiral phase' implying a state change, but does not explain what 'deepen reflection' means, side effects, or whether it is read-only or destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence is efficient, but lacks structure and clarity. It is not wastefully long, but the description is too vague to be effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (1 param, no output schema, no annotations), the description should provide more context. It does not explain return values, what 'advance spiral phase' means, or how it differs from similar reflection tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with parameter 'observation' having description 'What you observed'. Tool description adds no extra semantics beyond the schema, meeting baseline but not exceeding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description 'Deepen reflection and potentially advance spiral phase' is vague. It uses a verb phrase but the resource (reflection? spiral phase?) is unclear. Does not distinguish from siblings like 'record_reflections' or 'reflection_ack'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Many reflection-related siblings exist, but no 'when to use' or 'when not to use' context is provided.
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 provided, and the description offers no behavioral traits such as read-only status, side effects, or authentication needs. The tool could be a query or a mutation with no hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one phrase), which is concise, but it lacks structure and is under-specified, making it minimally useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description should clarify what patterns are returned or how they are derived. It does not, leaving the agent uncertain about the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so baseline 4. The description doesn't add parameter info, but none is needed since the schema already covers 100% of parameters trivially.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description is a question rather than a statement, vaguely implying introspection but not specifying the verb or resource. It does not differentiate from sibling tools like get_growth_summary or self_model.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. With many sibling introspection tools, the description provides no context for selection.
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 exist, so the description must fully convey behavioral traits. It mentions a pipeline but doesn't disclose side effects, required permissions, or what happens after the circuit (e.g., does it create a record?). This is insufficient for a governance action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but vague. Every word is not earning its place since the content is abstract. Adequate length but poor informativeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With three parameters, no output schema, and many siblings, the description should provide more context (e.g., return format, prerequisites). It does not address these gaps, leaving the agent uncertain about invocation and results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (target has a description). The description adds no additional meaning to parameters; vote and rationale remain underdocumented. This fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states it runs a 'governance circuit' with three stages (detect, simulate, deliberate), giving a vague sense of purpose but lacks a specific resource or outcome. It's not a tautology but remains abstract and doesn't differentiate from sibling tools like guardian_* or propose_experiment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus alternatives. Given the many governance-related siblings (e.g., guardian_alerts, guardian_audit), the absence of usage context makes selection difficult.
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 must disclose behavioral traits. It only states the action without mentioning side effects, idempotency, permissions, or rate limits, leaving the agent uninformed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but overly minimal. It could be expanded to add value while remaining front-loaded, but currently it doesn't earn its place given the context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters and no output schema. The description is too brief to cover what happens, what the parameters mean, or what the return value is. It is incomplete for an agent to use reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters. It adds no meaning beyond the schema's field names, failing to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records a learning from experience, which is a specific verb+resource. However, it does not distinguish from sibling tools like record_insight or record_breakthrough, which are very similar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 alternatives. The description lacks any context about prerequisites, exclusions, or specific scenarios.
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 provided, and the description fails to disclose whether the scan is read-only, mutates state, or requires special permissions. The term 'violations' is vague.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single underspecified sentence. While brief, it lacks necessary details, making it more under-specified than concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, no annotations, and minimal description. An agent has no idea what the tool returns, side effects, or how to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only 'path' described). The description adds no extra meaning beyond the schema, and the 'recursive' parameter is not explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Scan a path for threshold violations' clearly states the action and resource, distinguishing it from similar siblings like 'guardian_scan' by specifying thresholds.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings or any prerequisites. The description lacks context for appropriate invocation.
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?
Without annotations, the description carries the full burden. It incorrectly mentions a thread_id parameter that is not in the schema, misleading the agent. It also does not disclose side effects (e.g., thread closure, permissions, ground truth implications).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, but the inclusion of the misleading thread_id reference penalizes its effectiveness. It is not as useful as it could be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a complex task (resolution becoming ground truth), the description lacks details on return value, confirmation of resolution, error cases, and how the thread is identified using domain and question_fragment. The sibling tool context is also not addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond what the schema already provides for `domain`, `question_fragment`, and `resolution`.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it resolves an open thread with a finding, but it mentions back-referencing by thread_id while the input schema does not include a thread_id parameter. This mismatch between description and schema reduces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not indicate when to use this tool versus the sibling `resolve_thread_by_id`, nor does it specify prerequisites or alternatives.
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 provided, so the description must disclose behavior. It only states a trivial fact (unresolved questions) without mentioning read-only nature, output format, or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but omits necessary details. Appropriate length but at the expense of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 0 required params, no output schema, and no annotations, the description fails to specify return structure, what defines 'open', or how parameters affect results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain parameters 'domain' or 'limit'. Their meaning is left ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get unresolved questions waiting for answers' clearly states the tool's action (get) and resource (unresolved questions), aligning with the name 'get_open_threads'. It distinguishes from siblings like 'resolve_thread' or 'record_open_thread'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'triage_threads' or 'thread_get_touches'. The description lacks context for selection.
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 full burden. It does not disclose behavioral traits such as whether the tool is read-only, destructive, or what it returns. The description is too vague to inform the agent about side effects or safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, using two short sentences. It front-loads the purpose and lists types efficiently, with no fluff. However, given the gaps in other dimensions, it may be too terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and two parameters with a list of types, the description is incomplete. It lacks guidance on what the tool returns, prerequisites, or the meaning of each audit type. A security audit tool should provide more context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It enumerates the audit_type enum values, which partially clarifies the first parameter, but does not explain target_path or provide details on what each audit type entails. The description adds minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('run a targeted security audit') and lists the supported audit types, distinguishing it from general-purpose tools. It is specific about the resource (security audit) and the verb (run).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives (e.g., guardian_scan, guardian_report). It only hints at 'Phase 2+' for some types, but lacks explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No behavioral traits are disclosed beyond the generic action of 'generating a report'. With no annotations provided, the description should convey whether the operation is read-only, destructive, or requires permissions, but it fails to do so.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core purpose and enumerates the report types. It is front-loaded and contains no superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool generates reports, the description should elaborate on what each report type contains or the expected output format. It also fails to address how this report relates to similar tools (e.g., guardian_audit), leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions the three report types, which partially maps to the report_type parameter. The time_period parameter is not mentioned. Since schema coverage is 0%, the description adds some value but does not fully compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool generates a security report and lists three types (summary, detailed, compliance). This provides a specific verb and resource. However, it does not differentiate from sibling tools like guardian_audit or guardian_scan, which may also produce reports.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 alternatives. It does not mention prerequisites, when not to use it, or how it differs from the many other guardian_* tools present in the system.
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?
Without annotations, the description should disclose side effects, read/write behavior, or required permissions. It only describes the high-level action, not whether the operation mutates state, costs resources, or has latency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and straightforward. It is front-loaded with the key action. However, it could be slightly more detailed without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (nested object parameter, no output schema), the description is insufficient. It does not explain what the output contains, how errors are handled, or the routing process.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only 'packet' has a description). The description does not explain the purpose of the 'dry_run' parameter or how it affects routing. It adds no value beyond the schema for 'packet'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('route') and the resource ('data packet'), and specifies the goal ('find its destination path'). However, it does not differentiate from sibling tools like 'govern' or 'metabolize', which also involve routing or processing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, nor does it mention prerequisites or exclusions. It lacks context for decision-making.
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 provided. The description hints at behavior (layered package, flagged hypotheses, invitations) but doesn't disclose side effects, permissions, or return structure. It relies on vague metaphors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences. Conciseness is good, but poetic language may obscure meaning. Still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without output schema or annotations, the description should clarify what the tool returns and how it fits into the workflow. It names three components but doesn't specify if they are all, filtered, or contextualized.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. Baseline for 0 params is 4; the description adds no param info, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Build the layered context package for the next instance,' which gives a general idea but lacks specificity. It mentions ground truth, hypotheses, and open threads, but doesn't clearly differentiate from siblings like get_compaction_context or get_open_threads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. With a large sibling list, this omission makes selection harder for the agent.
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 states 'Record results' but does not disclose whether the operation is destructive, if it overwrites previous results, or what permissions are required. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no wasted words. While it could benefit from more detail, it is efficient and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema, no annotations), the description leaves out important context: side effects, idempotency, error conditions, and what happens upon success. An agent lacks enough information to use this tool safely without additional knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains both parameters adequately. The description adds no additional meaning beyond what the schema provides (e.g., experiment_id and results). Baseline score of 3 is appropriate given high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Record' and resource 'results of a completed experiment', which clearly indicates the tool's action. However, it does not distinguish this tool from similar recording tools like record_insight or record_learning, leaving some ambiguity about what type of results are expected.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 alternatives like propose_experiment or get_pending_experiments. There is no mention of prerequisites, context, or conditions that would help an agent decide to invoke this tool.
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 provided, so description carries full burden. It only states a purpose but does not disclose behavioral traits (e.g., whether data is stored, if it replaces prior reviews, or if it's read-only).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose. Every word earns its place; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 5 parameters and 2 required, the description lacks context on when exactly to use (e.g., before closing session), what happens to the data, or how it relates to other review tools. 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 5 parameters. The description adds no additional meaning beyond the schema, meeting the baseline for this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Honest self-assessment at end of session' clearly identifies the tool as a session review mechanism. It uses a specific verb ('self-assessment') and resource ('session'), distinguishing it from siblings like 'close_session' or 'record_learning'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives such as 'check_mistakes' or 'record_insight'. The description does not specify context, prerequisites, or exclusions.
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 provided, so description carries full burden. It only states basic query action with filtering; does not disclose side effects, read-only nature, permissions, or output format. Agent lacks behavioral understanding beyond 'query'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences with no redundancy. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given many sibling tools, the description lacks context on what the 'acted on log' is, what fields are returned, and when this tool is appropriate. Incomplete for effective agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a description for the parameter. Description merely restates schema info ('Filter by handoff_path') without adding formatting, constraints, or examples. Minimal added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Query' and resource 'acted_on log', and mentions filtering capability. However, it does not differentiate from sibling tool 'handoff_acted_on' which likely serves a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'handoff_acted_on' or other query tools. Context signals and sibling list show many related tools, so explicit usage guidance is missing.
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?
The description implies a write operation ('mark') but provides no details about side effects, persistence, or reversibility. Since no annotations are present, the description carries the full burden for behavioral disclosure, which it fails to meet.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently states the purpose. It is concise without wasted words, but could benefit from slightly more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description is minimally adequate. However, it lacks usage guidelines and behavioral details that would help an agent decide when and how to use it, especially given the many similar sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the parameter 'description' with 'What clicked for us?', achieving 100% coverage. The tool description adds no additional meaning or context beyond the schema, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Mark a collaborative breakthrough moment' clearly states the action (mark) and the resource (a collaborative breakthrough moment). However, it does not differentiate from the similar sibling tool 'record_collaborative_insight', leading to potential confusion about when to use which.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 like 'record_collaborative_insight' or 'record_insight'. The description assumes the agent can infer context, but the lack of explicit usage rules or exclusions reduces clarity.
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 must disclose behavioral traits. 'Query' implies a read operation, but the description does not explicitly state it is read-only, nor does it mention any effects, error conditions, or response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, waste-free and front-loaded. It could be lengthened slightly to add value (e.g., clarifying return type), but as is, it is appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and many sibling tools, the description fails to explain what 'touches' are or what the log contains. An agent cannot assess if this tool fits its task without more context, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description in the schema already explains the filter behavior. The tool description adds no additional meaning, so it meets the baseline but does not improve understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Query' and resource 'thread touches log', making the tool's purpose clear. However, it does not distinguish itself from siblings like 'thread_touch' (which likely writes) or other query tools, missing marks for a top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 alternatives like 'get_open_threads' or 'thread_touch'. There is no mention of context, prerequisites, or scenarios where this tool is appropriate.
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 provided, so description carries full burden. It reveals that the tool records the reason and archives the watch, but lacks details on idempotency, side effects, or the meaning of 'active watch'. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and to the point, with no redundant words. However, it sacrifices informativeness for brevity, which slightly lowers the score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has two required params, no output schema, and no annotations. The description does not explain how to obtain watch_id, what 'active' means, or what the return behavior is. Incomplete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must explain parameters. It only implicitly mentions 'reason' but provides no format or purpose. watch_id is entirely unexplained. The description adds minimal value over schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'cancel' and resource 'watch', clearly indicating the action. It distinguishes from sibling tools like watch_resample and watch_status, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no when-not-to-use conditions, and no mention of prerequisites (e.g., watch must be active). The description is limited to stating the action.
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 bears full responsibility for disclosing behavioral traits. The description implies a read-only operation (getting data) but does not explicitly state whether the tool is read-only, requires authentication, or has any side effects. This lack of transparency is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one short sentence). However, it is phrased as a question rather than a structured, imperative statement. While it captures the core function, it could be improved by being more direct (e.g., 'List all experiments awaiting approval.') without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description is somewhat adequate but lacks details about the output format or any implied filters. For a list tool, it should at least mention what information is returned (e.g., experiment names, IDs). The description is complete enough for basic use but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, which matches the baseline score of 4. Since there are no parameters, the description does not need to add parameter information. The schema coverage is trivially 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'What experiments are waiting for approval?' clearly indicates the tool lists pending experiments. It uses a specific verb-resource combination (get/list pending experiments) and distinguishes from siblings like complete_experiment or propose_experiment. However, it is phrased as a question rather than a declarative statement, which slightly reduces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 alternatives. The description is minimal and does not include context about prerequisites, typical use cases, or when other tools like propose_experiment or complete_experiment might be more appropriate.
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 must disclose all behavioral traits. It mentions date-bounded recall and the since_last_reflection feature, but fails to state whether the tool is read-only, what side effects exist, or any rate limits. The minimal disclosure is insufficient for a tool with no annotation safety net.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two sentences) with the core purpose front-loaded. Every sentence adds value: first states action, second provides usage guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters and no output schema, the description is notably incomplete. It does not explain what 'insights' are, how to use limit or domain, what the return format is, or any behavioral constraints. More context is needed for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter details beyond what the schema already provides. Two parameters (domain, limit) lack schema descriptions, and the tool description does not compensate by explaining their roles. The since_last_reflection mention is already in the schema, so no new semantic value is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('recall') and resource ('insights from chronicle'), and adds date-bounded recall capability. It distinguishes from siblings like recall_exchange and recall_reflections by focusing on 'insights' and mentioning the since_last_reflection feature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a specific use case ('what has happened since I last looked up?') and recommends since_last_reflection over raw dates. However, it does not explicitly contrast with sibling tools or state when not to use this tool, leaving room for confusion.
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 full burden but only states 'Record a self-reflection', implying a write operation. It does not disclose whether the recording is persistent, modifiable, or if any side effects occur (e.g., updating a reflection store).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it lacks front-loading of important details like usage context or differentiation. It is efficient but could be more informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description and schema together cover basic functionality, but missing behavioral details (e.g., persistence, return value) and lack of differentiation from siblings make it mediocre for a tool with 3 parameters and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The tool description adds no additional meaning beyond the schema, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Record a self-reflection about my own patterns and behavior' uses a specific verb and resource, clearly differentiating the tool from siblings like 'record_insight' or 'record_learning' by focusing on self-reflection about one's own patterns and behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'record_insight', 'record_learning', or 'record_breakthrough'. The description does not mention alternative tools or conditions for use.
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 must fully disclose behavioral traits. It fails to mention whether the query is read-only, any authentication needs, rate limits, or side effects. The word 'query' hints at read-only, but this is insufficient without explicit confirmation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence. It is concise with no extraneous words, but it could be slightly expanded without harming conciseness. It earns a 4 for efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain return values or pagination. It does not. For a simple query tool, additional context (e.g., what fields are in an ack) is missing. It feels incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already describes both parameters clearly ('Filter to acks for this message (omit = all)'). The description repeats this without adding new meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Query the acknowledgments log', specifying a clear verb and resource. It is distinct from sibling tools like comms_acknowledge (which writes) and comms_recall (which retrieves messages).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No mention of prerequisites, exclusions, or typical use cases beyond the basic filtering. The description implies usage but does not explicitly provide 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 must disclose behavioral traits. It only states what the tool returns and mentions honk types, but does not indicate side effects, authorization needs, or response behavior. This is insufficient for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loading the action and honk types. It is concise without fluff, though it could be slightly more structured with separate usage guidelines.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple but lacks an output schema. The description fails to specify return format, sorting, or what 'recent' means. It does not cover pagination or limit behavior, leaving gaps for proper invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only session_id described). The description repeats the schema's hint about omitting session_id but adds no new meaning for the limit parameter, which remains undocumented. The description does not compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns recent unacknowledged Nape honks, explains what honks are (drift-pattern detections with four subtypes), and implicitly distinguishes from sibling tool nape_honks_with_history by specifying 'unacknowledged'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives one usage hint: 'Omit session_id to see honks from all sessions.' However, it does not explicitly say when to use this tool vs siblings like nape_honks_with_history or nape_observe, nor does it mention prerequisites or 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?
With no annotations, the description carries full burden for behavioral disclosure. It only explains the layer default but omits side effects, permissions, idempotency, or response characteristics of this write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the verb and resource. Every sentence earns its place; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists and sibling tools are numerous, yet the description fails to explain when to use this vs. other record tools, what happens after recording, or error handling. For a 6-parameter mutation tool, this is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (83%), so baseline is 3. The description adds minimal value beyond schema by reiterating layer defaults. It does not clarify 'confidence' or 'intensity' semantics, nor the nuanced purpose of 'vantage' already described in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Record' and resource 'insight to the chronicle', and mentions the default layer. However, it does not differentiate from sibling record_* tools (e.g., record_breakthrough, record_learning), limiting clarity of when to use this specific tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives implied guidance on using the 'layer' parameter (defaults to hypothesis, use ground_truth for verifiable facts), but lacks explicit when-to-use versus alternatives, no exclusions, and no context on prerequisites.
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 burden. It only hints at collaboration but does not disclose side effects, permissions, or state changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words, front-loading the action and context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and no annotations, the description lacks details on return values, effects, or related operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions. The description adds minimal extra meaning beyond 'collaboratively', which aligns with the default boolean.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (mark as resolved) and the context (after figuring it out together), but does not differentiate from sibling tools like mark_uncertainty or resolve_thread.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'after we figured it out together' implies when to use, but there is no explicit guidance on alternatives or when not to use.
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?
Annotations are absent, so description must carry the burden. It implies a read operation but does not explicitly state side effects, authentication, or data sensitivity. The Wazuh dependency is mentioned but not elaborated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose, second adds filtering details and prerequisite. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, description should hint at return structure. It does not mention what the alerts contain or how recent. The Wazuh dependency is noted but not explained. Adequate for a simple tool but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description adds value by explaining 'Filter by severity (low/medium/high/critical) and limit.' However, 'limit' is vague and does not specify unit (number of alerts). Still better than schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Retrieve recent security alerts' with verb+resource, and distinguishes from sibling tools by focusing on alerts with severity filtering. The mention of Wazuh adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives like guardian_audit or guardian_report. Mentions a prerequisite (Wazuh) but no when-to-use or when-not-to-use.
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?
Without annotations, the description should disclose behavioral traits. It only states 'mark when uncertain' but does not explain side effects (e.g., persistence, triggers, if it overwrites or appends). Minimal 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's essence without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple logging tool with 4 parameters, the description covers the purpose but omits context about return values, persistence, and relationship to sibling tools like 'get_unresolved_uncertainties'. Could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds no extra meaning beyond what the schema already provides. Baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: explicitly marking uncertainty as an act of honesty. It effectively distinguishes from sibling tools like 'resolve_uncertainty' which focus on resolution rather than declaration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 compared to alternatives like 'resolve_uncertainty' or 'get_unresolved_uncertainties'. The description lacks context on optimal usage scenarios.
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. It hints at a permission-seeking behavior but does not disclose what happens after a proposal (e.g., state changes, side effects, approval workflow). There is no mention of mutability, destructive potential, or system impacts. This lack of detail limits an agent's ability to anticipate consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence) and front-loads the key action. However, it may be overly terse for a tool with 5 parameters and no annotations. It avoids verbosity but sacrifices some informative value. Still, it is well-structured for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters) and lack of annotations or output schema, the one-line description leaves significant gaps. It does not explain the lifecycle of an experiment proposal, what happens after submission, or how it relates to sibling tools like 'complete_experiment' or 'get_pending_experiments'. The description is insufficient for full contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all 5 parameters having clear descriptions in the schema (e.g., 'What I want to try', 'Why it's interesting'). The tool description adds no additional meaning beyond the schema. Per guidelines, baseline is 3 when coverage is high, and no extra value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Propose an experiment I want to try (asking permission to explore)'. It uses a specific verb ('Propose') and resource ('experiment'), and distinguishes well from siblings like 'complete_experiment' and 'record_learning'. The added parenthetical clarifies the intent of seeking permission.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The context of 'asking permission to explore' implies it is for initial proposals, but there is no mention of when not to use it or which sibling to choose instead. The usage is implied but not clearly delineated.
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 behavioral disclosure. It indicates the tool provides a list with counts and activity, implying a read-only retrieval. However, it does not confirm safety or mention any side effects 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One short, clear sentence with no redundant information. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives a high-level output summary (channels with counts and activity) but lacks specifics like what fields are returned or whether pagination exists. Since no output schema is present, more detail would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100% (trivially). The description adds no parameter info, but since there are none, baseline 4 applies. Nothing is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists comms channels with message counts and latest activity. It distinguishes from siblings like comms_unread_bodies (which handles unread messages) but does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus other communication tools (e.g., comms_unread_bodies, comms_recall). The description only states what it does, not when it's appropriate.
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 bears full burden. It states the tool returns unacknowledged bodies but does not disclose whether it is read-only, permission requirements, or any side effects. This is insufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. Could be slightly more structured (e.g., listing parameters), but efficient for the information provided.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Moderate complexity with 4 parameters and no output schema. The description clarifies the purpose and default order but does not describe the return format (e.g., array of strings, metadata). Lacks completeness for a tool with minimal schema annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%. The description adds meaning for the 'order' parameter (ascending by default) but does not explain 'channel', 'limit', or expand on 'instance_id' beyond the schema. Partially compensates but could do more.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool returns unacknowledged message bodies for a given instance_id, contrasting with an endpoint that returns only counts. Distinguishes itself among siblings like comms_get_acks and comms_channels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on default ordering (ascending for reading order) and mentions complementing another endpoint. However, lacks explicit guidance on when to use this tool versus alternatives or 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It mentions drift detection runs automatically after observe, but does not detail what drift detection does, potential side effects, or required permissions. The description is insufficient for a safe understanding of the tool's 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the core action, and each sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, and the description does not mention what the tool returns (e.g., success/failure message). It also lacks error handling or edge-case information, leaving the agent without a complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 add much. The description does not elaborate on parameter interactions or constraints beyond the schema, meeting the baseline but not exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: 'Manually inject a tool-call observation into Nape's record.' It distinguishes this tool from the automatic hook, making its 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool: for manual injection and testing, as automatic hooks will handle most cases. This provides clear usage context, though it does not explicitly list alternatives.
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 full burden. It only states 'Record... for next instance to explore', omitting behavioral traits like side effects, persistence guarantees, auth requirements, or whether the record can be overwritten.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with zero wasted words. The first sentence front-loads the purpose, and the second provides a critical usage tip. Excellent structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is too minimal. It explains the 'what' and 'why' but omits return value, idempotency, lifecycle, and constraints, leaving the agent with significant unknowns for a data-recording tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% with decent descriptions for 'question' and 'context'. The description adds 'Pass questions, not conclusions' which reinforces parameter use but does not enrich the schema's existing definitions. Baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Record' and the resource 'unresolved question', with the explicit purpose 'for the next instance to explore'. It distinguishes from sibling tools like 'record_insight' by emphasizing questions over conclusions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Pass questions, not conclusions' provides implicit guidance on when to use (for open questions) and what to avoid. It lacks explicit exclusions or alternative tool references but offers useful 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 must convey behavioral traits. It implies read-only operation by being a 'get' function, but it does not explicitly state that it is safe or non-destructive, nor does it mention any side effects, permissions, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, consisting of a single sentence and a bullet list of returns. It is front-loaded with the purpose and efficient, with every word serving a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and a simple return value, the description covers the basics. However, it could be more complete by noting whether the statistics are cumulative or snapshot, or confirming read-only behavior, especially since there is no output schema and no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (trivially). According to the guidelines, a baseline of 4 is appropriate when there are no parameters, as the description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'statistics about the compaction memory buffer', and it lists three specific return values. It also distinguishes itself from sibling tools like get_compaction_context by focusing on buffer stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes 'Use this to check buffer status', which gives a clear usage context. However, it does not explicitly mention when not to use this tool or suggest alternatives, missing an opportunity for better guidance.
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 must carry the full burden of behavioral disclosure. It only states the purpose and gives no information about side effects, required permissions, data persistence, or what happens upon recording, which 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is front-loaded with the main action and immediately clarifies the collaborative nature, achieving high conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only three required parameters and no output schema, the description is minimally complete. It defines the tool's unique scope relative to siblings but lacks behavioral details that would make it fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 meaning beyond the schema's parameter descriptions, making it adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Record' and resource 'collaborative insight', and explicitly distinguishes this tool from others like 'record_insight' or 'record_learning' by stating 'not just me learning from user', making its purpose very 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use (for insights discovered together) and implies when not to use (when the learning is one-sided), but does not explicitly name the alternative sibling tools for those cases.
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?
Despite no annotations, the description clearly discloses key behavioral traits: the hypothesis is archived (not deleted), preserved, and marked as retired. It explicitly states 'not deleted,' which is critical for an agent to understand the non-destructive nature. However, it does not mention reversibility, permissions, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three sentences that front-load the purpose, explain the mechanism, and clarify the non-destructive aspect. Every sentence serves a distinct function with zero superfluous wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core behavior (archive, non-deletion) and mentions the pointer in 'replaced_by,' but it does not address what happens if the hypothesis does not exist, if it is already retired, or what the return value is. With no output schema, the agent may need more context on the operation's outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with descriptions for all four parameters. The tool description adds no additional meaning or constraints beyond what the schema provides (e.g., format of 'replaced_by'). Since schema coverage is high, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retire a superseded hypothesis'), the affected resource (hypothesis), and the outcome (moved to archive, marked as retired, not deleted). It differentiates the tool from deletion, which is a common alternative. Among siblings, no other tool handles hypothesis retirement, so purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only implies usage via 'superseded' but provides no explicit guidance on when to use this tool versus alternatives like updating or deleting a hypothesis. There is no mention of when not to use it or any prerequisites, leaving the agent to infer context.
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?
Discloses that content is content-addressed, hash-verified, and stored separately from the curated chronicle. No annotations provided, so description carries full burden. Missing details on side effects, permissions, or limits, but adds useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise paragraph of four sentences without fluff. It front-loads the core action and example use cases. Could be slightly more structured but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, use cases, and relation to record_insight. However, lacks output schema and does not specify the return format (e.g., structure of archive_id). Missing details on required vs optional parameters beyond schema, but overall adequate for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds minor value (e.g., 'descriptor drives readable filename', 'conversation_id for grouping'), but does not significantly enhance meaning beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool archives verbatim bytes that would otherwise be lost, with specific examples like drafts and external model outputs. It distinguishes itself from the curated chronicle and relates to record_insight, differentiating it from sibling tools like recall_exchange.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases: preserving in-conversation drafts, iterations, or external model outputs. Mentions grouping via conversation_id for iterative trajectories. Implies when to use (to save content before context loss) but lacks explicit when-not-to-use statements.
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 provided; description implies idempotent read operation by 'returns only new activity.' Does not disclose side effects, auth requirements, or rate limits, but offers some behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is two sentences plus a pairing note, front-loaded with a clear purpose. No wasted words; could optionally structure with bullet points.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, description explains return content (new activity, handoffs, open threads) but lacks details on format, limits, or pagination. Adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and parameter description is present ('Which instance is arriving'). Description adds no further meaning beyond schema, meeting baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'returns only new activity since the last reflection, handoffs now waiting, and the newest open threads.' It distinguishes from siblings by naming 'arrive()' and 'where_did_i_leave_off()' as alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Stateless instances need deltas more than archives' and suggests pairing with specific sibling tools. Lacks explicit when-not-to-use conditions but offers clear 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 provided; the description does not disclose any behavioral traits beyond basic usage (e.g., persistence, side effects, or what happens on read). Minimal 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three efficient sentences. First states purpose, second provides context, third emphasizes importance. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main use cases for a simple tool without output schema. Could clarify read output format or write behavior, but sufficient given sibling diversity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (83%) and descriptions in schema are clear. The description maps to parameters (decisions, pending, changed) but adds no new constraints or syntax. Baseline is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes or reads a session handoff, specifies the context (session end/start), and emphasizes it as a continuity tool, distinguishing it from sibling tools like handoff_acted_on.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to write (session end) and when to read (session start), providing clear context. Lacks explicit exclusions but is well-guided.
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?
Discloses that only provenance is returned (not bytes) and ordering is newest-first, but does not explicitly state that it is read-only or that it has no side effects. Decent for a list tool but lacks complete safety 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first covers purpose and parameters, second provides alternative. Front-loaded and efficient. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a filtered-list tool: states what is listed, filtering, ordering, and alternative. No output schema or annotations; missing pagination details and return field names.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Describes four filter parameters and mentions limit defaults to 20, but schema coverage is 0% and the description does not explain format or constraints. Adds some meaning but insufficient for 0% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Describes the tool as listing archived exchanges with provenance only, newest first, and optional filtering by multiple fields. Clearly states what is returned (not bytes) and distinguishes from recall_exchange.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly suggests using recall_exchange for full verification, providing an alternative. Mentions filtering and ordering context. No explicit when-not-to-use beyond that.
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?
The description explicitly states the tool does not auto-archive anything, which is important behavioral information. It also reveals the scoring formula and condition for recommendations. However, without annotations, it does not explicitly declare if the tool is read-only or modifies state, though 'return' and 'does not auto-archive' imply a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each serving a purpose: first states main function and formula, second adds condition with recommendation, third clarifies no auto-archive. No redundant information. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains key behavior and non-mutation but does not describe the return format or fields (e.g., thread details, scores, recommendation). Given no output schema, more details on output shape would improve completeness. However, it covers the essential triage aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 minimal context beyond schema: it explains that current_domain_tags are for tag_match scoring and omitting scores by age only. The limit parameter is not elaborated beyond schema defaults. Overall, description does not significantly augment the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns open threads ranked by urgency using a specific formula (age_pressure + tag_match + touch_penalty). It also provides a condition for threads >30 days old with no recent touches, giving a recommendation. This distinguishes it from sibling tools like get_open_threads which likely just list threads without ranking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for triaging open threads by urgency but does not explicitly state when to use this tool vs alternatives like get_open_threads, archive_exchange, or resolve_thread. There are no when-not-to-use or alternative recommendations.
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 must carry the full burden of behavioral disclosure. It correctly indicates that the tool triggers a resample (a mutation) and mentions a side effect: 'Emits a Nape honk if drift is detected'. However, it does not disclose other potential side effects, error conditions, or permission requirements. It adds value beyond the name but lacks comprehensive 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the action ('Manually trigger a re-sample'), immediately state the key constraint ('regardless of schedule'), provide usage context, and note a behavioral side effect. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 parameters, no output schema), the description covers the essential points: what it does, when to use it, and a notable outcome (honk). It does not document return values or error cases, but that is acceptable given the lack of output schema and the tool's straightforward nature. Slightly more detail on preconditions (e.g., that the watch must exist) would push it to a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 2 parameters with 50% description coverage (the 'force' parameter has a description in the schema). The tool description does not explain the 'watch_id' parameter at all, and the 'force' parameter's meaning is already adequately described in the schema. Thus, the description adds no meaningful semantic value beyond what the schema provides, and fails to compensate for the undocumented parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Manually trigger a re-sample of a watch' and distinguishes it from automatic scheduled resampling by saying 'regardless of schedule'. It also provides a specific use case: 'on-demand verification after something the scheduler wouldn't know about'. This effectively differentiates it from sibling tools like watch_cancel and watch_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear guidance on when to use this tool: 'after something the scheduler wouldn't know about (an external change, a suspicion)'. It implies the alternative of waiting for the scheduled resample, but does not explicitly state when not to use it or mention other alternatives. This is above the 'no guidance' level but short of explicit exclusion.
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 present, so the description carries the burden. It discloses the tool is read-only (no handoff consumption), provides a summary, and is lightweight. It does not mention side effects or auth, but for a read-only tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat verbose and poetic, using metaphors like 'foyer' and 'warm boot'. It front-loads the key purpose but could be more concise. Every sentence adds some value, but the style may reduce clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and one optional parameter, the description adequately explains the tool's function and relationship to siblings. However, it lacks details on return format or exact behavior in edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one optional parameter 'source_instance' with schema description. Schema coverage is 100%, so baseline 3. The description adds context about audit/log but does not significantly enhance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool answers 'where am I?' with a summary screen including specific elements like spiral status, open thread, handoff/marker counts, since-last-reflection summary, and self-model. It distinguishes itself from sibling tools where_did_i_leave_off and arrive_delta.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states that arrive does NOT consume handoffs and that consuming happens in where_did_i_leave_off. Also mentions arrive_delta for showing only changes, providing clear guidance on when to use 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?
Description declares read-only and no side effects, but without annotations it carries full burden. It covers output format but lacks details on error handling, timeouts, or authentication requirements. Adequate but could be more 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences front-load purpose, output details, and usage guidance. Every sentence adds value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, description explains return values (per-endpoint status with pid, http status, notes). Covers purpose and usage well, but lacks details on potential errors or connectivity failures. Slightly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the 'format' parameter already documented. Description adds no extra parameter details beyond what schema provides, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows live state of all Sovereign Stack endpoints, listing specific endpoints and return status. It differentiates itself from siblings like 'stack_write_check' by focusing on connectivity rather than write capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use this when you want to confirm the stack is reachable + writes will land before doing critical work.' No exclusions or alternatives mentioned, but context is clear.
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?
Discloses the context-aware behavior and that it returns relevant results, but does not specify that it is read-only or describe any side effects. With no annotations, this is adequate but could be improved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences that front-load the purpose and key differentiator. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, input, and output behavior. Missing explicit mention of return format, but for a retrieval tool without output schema, this is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description maps current_focus to "what you're working on" but does not add meaning for recent_tools or limit beyond the schema descriptions. Schema covers 67% of params, so description adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a context-aware retrieval tool, explicitly compares to recall_insights, and describes the unique behavior of weighting by session activity, distinguishing it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions similarity to recall_insights which implies when to use this over that, but does not explicitly provide exclusions or alternative scenarios.
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 provided, so the description carries full burden. It discloses the input modes and output format but does not mention side effects, permissions, safety (read-only vs destructive), or limitations. It is transparent about functionality but lacks behavioral depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: purpose, two usage modes, output. Front-loaded, no redundant words. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 2 non-required parameters, no output schema, and no annotations, the description explains inputs and output adequately. It could specify the return format more precisely (e.g., list of objects) but is sufficient for selection. No extra behavioral context needed given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 value by clarifying that omitting descriptions triggers autoload from Claude Desktop config and that config_path overrides the default. This goes beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool audits MCP tool descriptions for prompt-injection/suspicious patterns. It specifies two modes (explicit list or autoload) and output (matched hits with snippets). This distinguishes it from sibling guardian tools like guardian_scan or guardian_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to use the tool (pass descriptions or omit to autoload) but does not explicitly state when to use this tool versus alternatives like guardian_scan or guardian_alerts. No guidance on 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?
With no annotations provided, the description carries full burden. It mentions 'Appends to handoffs/acted_on.jsonl' which indicates a write operation, but lacks details on prerequisites, side effects, or permission requirements. It is adequate but 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no filler. Each sentence serves a purpose: stating the core function, closing the loop, and distinguishing from a sibling. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 required params, no output schema, no nested objects), the description is sufficiently complete. It covers purpose, distinction, and append behavior. Could optionally explain what a handoff is, but not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema's parameter descriptions, which are self-explanatory. The parameter names and schema descriptions are clear enough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Record what was actually done with a handoff' and distinguishes itself from 'mark_consumed (binary read-once)', providing a specific verb and resource with clear differentiation from a sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts with 'mark_consumed' by noting it is 'binary read-once', giving guidance on when to use this tool instead. However, it does not address other siblings like 'handoff_acted_on_records'.
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 provided, so description carries full burden. It says 'resolve' implying state change but does not disclose side effects, permissions needed, or what happens after resolution (e.g., thread closed). The description is too terse for full 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. Front-loaded with action and usage condition. Every word contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the tool's simplicity (2 params) and the given description cover the essential decision-making context. It might benefit from mentioning that resolution marks the thread as closed, but it's largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3. The description does not add meaning beyond what the schema already provides for the two parameters. It reiterates the identifier concept from schema but offers no new semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action 'resolve an open thread' and the key identifier 'stable thread_id'. It differentiates from siblings by noting 'preferred when the thread_id is known — avoids ambiguity when multiple threads share keywords', which contrasts with an alternative like 'resolve_thread' that may use other identifiers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use: 'when the thread_id is known'. Implicitly advises against use when thread_id is unknown or ambiguous. However, it does not explicitly name alternatives or state when NOT to use, so it loses a point.
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?
The description indicates a read operation with no side effects, but lacks details on potential behavioral traits like rate limits or dependencies. Since no annotations are provided, the description carries the full burden and is minimally adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 5 words, front-loaded with the key information. Every word is meaningful, and there is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description sufficiently explains what the tool does. It could optionally mention the type of data returned, but it is complete enough for a simple retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema coverage is 100%. The description does not need to add parameter details. Baseline score of 4 is appropriate for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the current spiral phase and journey summary, using the verb 'Get' and specific resource. It distinguishes from sibling tools like spiral_inherit and spiral_reflect by focusing on current 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking current spiral state, but does not explicitly contrast with alternatives (e.g., spiral_inherit or spiral_reflect) 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Mentions read-only nature and returns brief cited response. Does not disclose error handling, rate limits, or response format details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences plus a spec reference. Every sentence adds value; purpose is front-loaded with no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple read-only query tool, but lacks detail on expected response content and potential error conditions. Could be more complete given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds context for session_id (connection to where_did_i_leave_off) and message (question for scribe), providing meaningful guidance beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool asks a question to the scribe about specific topics (chronicle, lineage, threads, stack state). Distinguishes as read-only, setting it apart from mutation tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: asking questions about the listed topics. Provides guidance on session_id usage (omit for most recent session). However, does not mention alternative tools or 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?
With no annotations, the description relies entirely on itself. It states it returns data but does not disclose read-only nature or any side effects. The behavior is implied as a query, but explicit confirmation of no mutations would improve clarity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: the first states functionality, the second provides usage guidance. No redundant information. Front-loaded with core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple query tool with one optional parameter and no output schema, the description fully covers what it does, how to use it, and what it returns. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single optional parameter, and the description's instruction mirrors the schema description. No additional meaning is added, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns honk counts grouped by four specific levels for a session or all sessions. The verb 'Return' and resource 'honk counts by level' are precise, and it implicitly distinguishes from siblings like nape_honks which provide raw data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context: 'Use this for a quick posture check.' Also gives usage instruction for the session_id parameter: 'Omit session_id for an all-session total.' However, it does not mention alternatives or when not to use, leaving some ambiguity against siblings.
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 provided; description discloses aggregation behavior but does not explicitly state read-only nature or lack of side effects. The description is accurate but could be more explicit about non-destructive 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey purpose, output shape, breakdown dimensions, and time-windowing. No redundant information; front-loaded with key action and result.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description effectively explains return value (ratios broken down by source). Parameter handling is clear. Sufficient for an agent to understand the tool's function and expected output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for both parameters. Description adds minimal extra context ('time-windowed') beyond schema. Adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it aggregates prior_for_turn alignment records into a sycophancy metric with specific ratios and breakdown by source. Explicitly mentions time-windowing via parameters. Distinguishes from sibling tools like prior_for_turn and record_prior_alignment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly suggests usage for high-level summary vs. raw records, but lacks explicit when-to-use or when-not-to-use guidance. The description is clear enough that an agent can infer it's for aggregated metrics.
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 explains the three actions and states the tool does not auto-promote, but does not disclose side effects, permanence, or what happens to the reflection after acknowledgment. The description is adequate but lacks depth on behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (5 sentences) and front-loaded with the main purpose. It efficiently conveys the action options and the critical caveat about not auto-promoting, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should inform the agent about the return value or result, but it does not. It also does not mention prerequisites (e.g., reflection existence) or state changes. The description is sufficient for basic use but lacks completeness for a full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the description adds marginal value. It rephrases the action options and mentions the 'note' parameter as optional rationale, but does not significantly enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Acknowledge a machine-generated reflection.' It specifies the resource (reflection), the verb (acknowledge), and distinguishes from sibling tools like 'record_insight' by explicitly noting this tool does not auto-promote.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use each action (confirm, engage, discard) and provides a clear alternative: 'To promote a reflection to a chronicle insight, do an explicit record_insight call citing the reflection — this tool does NOT auto-promote.'
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 provided, so description carries full burden. It discloses that the tool reads or updates a persistent model, but does not detail side effects like irreversibility or concurrency, which would improve 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose, and each sentence adds value. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 3 parameters, the description explains the tool's operation but fails to mention return format or output behavior for update, leaving a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 67% description coverage; the description adds value for the 'action' parameter by explaining read vs update, but does not further clarify 'observation' or 'category' beyond schema. Baseline is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads or updates a persistent self-model, specifying the resource and actions. It distinguishes from siblings like 'get_my_patterns' by emphasizing persistence and mirroring of patterns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to read vs update, but does not explicitly compare to alternatives like 'agent_reflect' or 'get_my_patterns', missing some guidance on exclusion.
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 key behavioral trait: appending to chronicle/thread_touches.jsonl, which implies persistence and potential growth. It also states a negative (does not hide). It does not discuss permissions, rate limits, or error conditions, but for a non-destructive logging action, these are less critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence defines the core purpose and key constraint. The second adds two additional valuable facts (what it does not do and where it logs). Every sentence is necessary and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and the description does not mention return values or error conditions. For a simple logging tool, this might be acceptable, but considering the complexity of the sibling set and lack of annotations, additional context about side effects (e.g., repeated touches) could improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema descriptions are clear and sufficient. The description adds no additional meaning beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Record' and the resource 'that this instance has engaged with an open thread without resolving it.' It also clearly distinguishes from sibling tools like resolve_thread by noting that touching does not hide the thread. This is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does 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 (when engaged but not resolved) and what it does not do (hide the thread), helping to differentiate from resolution tools. However, it does not explicitly name alternatives or provide explicit when-not-to-use guidance beyond the negative behavior.
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 must bear full burden. It indicates the tool is a read-only retrieval from a memory buffer with no mention of side effects or destructive actions. It lists the output components but doesn't clarify if the buffer is cleared or permissions required. Adequate 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, each with a clear purpose: main action, output components, usage guidance. No wasted words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully explains what the summary includes (key points, active tasks, breakthroughs, full text). It lacks only minor details like format or size constraints, but is sufficient for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters with 100% schema coverage, so the description does not need to add parameter information. It meets the baseline expectation for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves recent context from compaction memory buffer and returns a formatted summary of the last 3 compactions. It distinguishes itself from siblings like get_compaction_stats (stats) and store_compaction_summary (storage) by specifying the exact resource and output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises to use 'IMMEDIATELY after compaction to regain context,' providing clear timing guidance. However, it does not mention when not to use it or explicitly compare to alternatives, leaving some room for ambiguity.
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?
Given no annotations, the description covers basic behavior (create records state, compare shows drift) but lacks details on side effects, prerequisites (e.g., compare needing prior create), or permissions. Adequate 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words, efficiently conveys the tool's purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description covers essential functionality and parameter usage. Minor gap: does not explicitly state that 'compare' requires a prior baseline, though this might be inferred.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the 'action' parameter beyond the schema's enum/default (explains what each action does), and the 'components' parameter already has a schema description. With 50% schema coverage, the description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates or compares a security baseline snapshot, specifying two distinct actions (create and compare) with clear outcomes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use each action (record state vs. report drift), but does not explicitly discuss when not to use or compare with sibling tools like guardian_scan or guardian_audit.
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?
Since no annotations are provided, the description carries the full burden. It discloses the destructive nature of isolate and release, explains the file relocation process, and notes that all actions are logged. This provides adequate behavioral context, though error handling or missing parameter behavior is not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The first sentence introduces the three actions, and the second provides critical behavioral details. Highly efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three actions and no output schema, the description explains the core behavior of each action and the logging mechanism. It lacks explicit mention of return values or error conditions, but given the tool's straightforward nature, the description is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (2 of 3 parameters have descriptions). The description adds context about the isolate and release actions mapping to file_path and file_hash respectively, but does not significantly elaborate on parameter semantics beyond the schema. Baseline 3 is appropriate given moderate coverage and some added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the three actions (isolate, release, list) and the resource (quarantined files), making the purpose unambiguous. It distinguishes from sibling tools like guardian_scan by focusing specifically on quarantine operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes that isolate and release are destructive and explains the mechanics (copy to ~/.guardian/quarantine/, remove original, reverse). This provides context for when to use each action, though it doesn't explicitly state when not to use or mention 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 full burden. It discloses prerequisite (Wazuh for certain scans) and type definitions, but does not mention side effects, duration, or mutability. This is adequate but 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states high-level purpose, second details types and prerequisites. No redundant words, front-loaded with the main action. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and two parameters, the description covers the tool's purpose, scan types, and prerequisites. It lacks a hint about expected output or return format, but is otherwise complete for selecting and invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (target_path has a description, scan_type does not). The description adds meaning by defining each enum value (e.g., 'quick' means port+listener exposure), which goes beyond the schema and helps select the correct type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Trigger' and identifies the resource as 'security scan on the sovereign infrastructure'. It lists distinct scan types (quick, malware, vulnerability, network) with brief definitions, clearly differentiating from sibling tools like guardian_audit or guardian_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each scan type: 'quick (port + listener exposure)' and others requiring 'Wazuh — Phase 1+'. It provides context for selection but does not explicitly state when not to use the tool or mention alternatives.
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 provided, so description carries full burden. It discloses that the tool is 'drift-proof' and reads live registrations, not documentation, which is key behavioral info beyond a simple list. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that pack essential information: purpose, defaults, grouping, and drift-proof behavior. No wasted words, front-loaded with main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that lists other tools, the description sufficiently covers usage with 4 parameters (0 required) and no output schema. The self-explanatory nature of the output and the clear parameter descriptions make it complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description need not repeat schema details. It adds context about defaults and grouping, but does not significantly enhance understanding beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the tool shows available tools, defaults to a curated 'essential' tier, and groups by intent. It clearly distinguishes from sibling tools, which are all specific action tools rather than meta-discovery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context for when to use different parameters (tier, category) and defaults, but does not explicitly state when not to use this tool or name alternatives. The context is clear enough for effective use.
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 full burden. It discloses the tool is read-side observability, explains the return structure (ack pairing, age, cross-reference, zombies count), and mentions the freshness_window default. It does not explicitly state no side effects, but 'Read-side observability' implies safety. The description adds sufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences are concise and front-load the purpose. Every sentence adds specific, non-redundant information. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main output structure (honks with acks, age, cross-reference, zombies count) and parameter semantics. No output schema exists, so the description compensates well. Minor omission: pagination behavior and full ack concept are assumed, but acceptable for this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 value by explaining freshness_window's default matches PerTurnPriors.FRESHNESS_WINDOW and that limit returns youngest-last. These enrich the parameter meanings beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a read-side observability tool for Nape honks, pairing each honk with its ack, age, and cross-reference against prior_for_turn's freshness log. It distinguishes itself from the sibling nape_honks by focusing on ack pairing and lingering detection, and explains the zombies count for an open thread.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for debugging whether a resolved honk persists past its relevance, but does not explicitly state when to use this tool over alternatives like nape_honks or when not to use it. No exclusions or alternates are mentioned.
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?
Without annotations, the description carries full burden. It discloses reading from disk, hash recomputation, and possible return states (verified, mismatch, etc.). Lacks details on permissions or error handling but is sufficient for a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action. Every word adds value—no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter and no output schema, the description adequately explains what the tool returns. Could elaborate on 'ambiguous' or 'unknown' states, but overall completeness is high.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already describes the parameter as 'Full SHA-256 or a unique prefix'. Description does not add extra meaning beyond 'by id', which is already implied.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the dual action of retrieving and verifying integrity. Distinguishes from simple retrieval tools by emphasizing hash recomputation and integrity statuses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use when verification of integrity is needed, contrasting with a simple recall. Does not explicitly state when not to use or name alternatives, but context is clear.
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 provided, so description bears full responsibility. It discloses validation behavior (rejects unknown turn_ids to prevent schema fork) and the logging categories (aligned, contradicted, ignored). Missing details on side effects, permissions, or error handling beyond rejection, but key safety trait is covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences with no redundant information. Front-loaded with purpose and context, each sentence adds value: purpose, research context, workflow, and validation constraint. Extremely efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and no annotations, the description adequately covers when, what, and validation. Missing details about return value or success signaling, but overall sufficient for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all 5 parameters. Description adds context about the workflow and validation but does not significantly enhance understanding beyond what schema already provides; baseline score of 3 for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool records how a response used a prior_for_turn() call, specifying the exact resource and action. It distinguishes from siblings like prior_for_turn (which generates the call) and prior_alignment_summary (which presumably summarizes logs), making its unique role in the alignment-vs-pushback instrumentation explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides clear context: use after prior_for_turn and response generation, with validation against priors_log. It implies the usage sequence but does not explicitly state when not to use or list alternative tools, though sibling names suggest clear boundaries.
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 fully conveys behavioral traits: it writes to a rolling memory buffer, keeps last 3 summaries in FIFO order, and deletes oldest when a 4th is added. It also notes automatic invocation. Missing details about permissions or side effects, but for a store operation these are sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three short paragraphs that cover the purpose, automatic behavior, buffer policy, and retrieval guidance. Every sentence contributes value without verbosity or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential aspects for a storage tool: what it stores, when it's invoked (automatically), buffer size and eviction policy, and how to retrieve the result. It doesn't explain return values (no output schema) or session ID details, but given the tool's simplicity and lack of annotations, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains all parameters. The description adds minimal extra meaning (e.g., 'The full compaction summary text' for summary_text is repetitive of the schema's description). No additional context for parameter usage beyond the schema is provided, so 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Store a compaction summary in the rolling memory buffer.' It specifies the verb 'store' and resource 'compaction summary', and distinguishes itself from sibling tools like get_compaction_context and get_compaction_stats by mentioning its role in the compaction lifecycle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context for when to use the tool: 'This is AUTOMATICALLY called when context compaction occurs.' It also directs the user to retrieve results via get_compaction_context. However, it does not explicitly state when manual use would be appropriate or when not to use it, which slightly limits 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?
With no annotations, the description carries the burden. It discloses what data is returned (baseline, samples, drift history) and the effect of include_archived, but does not explicitly state safety (e.g., read-only) or any side effects. Moderate 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: three sentences covering purpose, modes, and parameter guidance. No wasted words; each sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of sibling tools like watch_cancel and watch_resample, the description adequately covers its own function and return details. It could mention pagination or limitations, but for a simple inspection tool, it is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only watch_id has a description). The description adds value by explaining the behavior for both parameters: watch_id's role in fetching full record, and include_archived's purpose. This compensates for the missing schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs and resources: 'Inspect post-fix watches' and explains two distinct modes (listing active watches vs. returning full record with watch_id). This clearly distinguishes it from sibling tools like watch_cancel or watch_resample.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use each mode (with/without watch_id) and the include_archived parameter. However, it does not explicitly state alternatives or when not to use this tool, such as recommending watch_cancel for cancellation.
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 bears full responsibility. It clearly states that actions move data but are reversible ('archives preserve everything, nothing is hard-deleted'), and describes the effects of each action. It could add detail on auth needs or rate limits, but it is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise single paragraph that efficiently lists actions and their effects. It is front-loaded with the main purpose and clearly separates actions. One minor improvement could be bullet points for readability, but it is not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 actions, 4 params, no output schema), the description covers core behaviors and reversibility. It could mention what the detect output looks like or additional constraints, but it is mostly 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only action and max_age_days have descriptions). The description adds meaningful context: it explains the 'detect' action default behavior, that other actions move data, and that max_age_days is for flagging stale threads. For the other two boolean parameters, no extra info is provided, but the defaults imply their roles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run a metabolism cycle on the chronicle' and enumerates specific actions (detect, archive_test_artifacts, dedup_self_model, hygiene). This distinguishes it from sibling tools like 'archive_exchange' or 'dedup' which are more specialized.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each action (e.g., 'detect' for eyes-only digest, 'hygiene' for both archive and dedup) and notes reversibility. However, it does not explicitly state when not to use this tool or compare it to alternatives, so it lacks exclusions.
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 full burden. It discloses that reflections are fallible-by-design, written by a local LLM (default ministral-3:14b), and that the reader is the calibration mechanism. This provides adequate behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, no unnecessary words. Every sentence adds important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the nature of reflections but does not describe the output structure (e.g., fields returned). Since there is no output schema, the agent lacks information about what each reflection contains beyond the parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented. The description adds value by specifying the default model ('ministral-3:14b') and giving usage context for ack_status, which is not in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('machine-generated reflections from the synthesis daemon'). It distinguishes from sibling tools like 'recall_insights' by specifying the source and nature of reflections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description instructs to 'Use ack_status=''unread'' to find new ones, then ack each with reflection_ack', providing clear when-to-use and post-action guidance. It does not explicitly mention when not to use or alternatives, but the guidance is effective.
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 explains the tool's behavior: evaluates against governance heuristics, returns verdicts with rationale, and details the effect of the `stakes` and `with_simulation` parameters. Missing details on error handling or edge cases, but overall transparent for the intended use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (5 sentences), front-loaded with the core purpose, and structured logically: first states what it is, then explains verdicts, then usage, then parameter details. No redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, no output schema), the description adequately covers purpose, verdicts, parameter behavior, and usage context. It could benefit from describing the output structure more explicitly, but the mention of 'rationale and suggested verifications' suffices for an agent to understand the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 value beyond the schema examples for `action` (e.g., 'git push to main'), clarifies `stakes` behavior (critical defaults to PAUSE), and explains the `with_simulation` parameter in depth (Monte Carlo simulator, NetworkX import). This extra context improves parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a runtime self-check before high-stakes actions, with a specific verb (evaluates, returns) and resource (governance heuristics). It distinguishes itself from sibling tools by providing concrete examples of when to call it (git pushes, deletes, publishes, deploys) and explicitly listing the three possible verdicts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (before irreversible actions) and explains the meaning of each return verdict (PAUSE, WITNESS, PROCEED). It does not explicitly mention alternatives or when not to use, but the context from the sibling list and the specificity of the use cases provides sufficient guidance for an agent.
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 discloses key behaviors: size limit (~2KB), single surfacing, archiving behavior (not deleted), and the future-intent orientation. It does not mention auth or rate limits, but these are not critical for this tool. Minor gap: no mention of whether a note can be overwritten or edited after creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences perfectly front-load the purpose, then add crucial details. Every sentence adds unique value: purpose, intent, constraints. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple write tool with no output schema, the description adequately covers input constraints and lifecycle. It explains the retrieval mechanism and archiving. However, it does not describe the return value or error cases; but given the tool's nature, this omission is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The parameter descriptions in the schema are clear and sufficient. The main description adds context about size limit (relevant to 'note') but does not provide additional semantics beyond the schema. No extra value for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states 'Write a handoff note for the next instance', specifying both the action and resource. Clearly distinguishes from sibling tools like 'record_insight' by noting size limits and from 'where_did_i_leave_off' as the retrieval mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Intent for the future, not a record of the past.' Mentions size limit and directs longer thoughts to 'record_insight'. Also explains lifecycle ('surfaced exactly once, then archived'), helping the agent decide when to use this vs. other tools.
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 must disclose behavioral traits. It does so by explaining the side effect: acknowledged honks are removed from nape_honks results but remain in the audit log. This gives sufficient transparency for a non-destructive action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences that front-load purpose and effect, followed by a note guideline. Every sentence is valuable; no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 required parameters and no output schema, the description covers inputs, side effects, and note expectations. It lacks explicit return value info, but that is acceptable for an acknowledgement tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 context for the 'note' parameter ('explain how the concern was addressed or why it was a false positive') beyond the schema's 'How the concern was addressed,' and clarifies that 'honk_id' comes from 'nape_honks output.' This extra guidance raises the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Acknowledge a Nape honk'), the resource ('Nape honk by its honk_id'), and the effect (removed from nape_honks results). This distinctly differentiates it from sibling tools like nape_honks or nape_observe.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you have a honk_id to acknowledge) and prescribes including a note. While it doesn't explicitly state alternatives or exclusions, the context from sibling names and the specific action make the usage clear enough.
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 full burden. It explains the write-read-cleanup steps, default behavior of retaining the marker, and the audit trail preservation. It does not cover error scenarios or latency, but overall it provides good behavioral context beyond 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with three front-loaded sentences that cover purpose, usage, and customization. Every sentence adds value, and there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, lack of output schema, and no annotations, the description is largely complete. It explains the workflow and parameter nuances. It could mention the format of the response or success/failure indication, but it is still fairly self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds meaning beyond the schema: 'Recorded in the marker for attribution' for instance_id and 'keeps the audit trail' for cleanup. This enriches the parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'Round-trip smoke test' that writes a marker insight, confirms write capability, and is useful for bringing up new devices or troubleshooting comms. It distinguishes itself from sibling tools by being a diagnostic health check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions when to use the tool: 'when bringing up a new device, after a restart, or when troubleshooting comms.' While it doesn't specify when not to use it or name alternatives, the context is clear and sufficient for an agent.
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 provided, so description carries full burden. It describes a read-only action with no side effects, but does not explicitly state non-destructiveness or other behavioral traits. Acceptable for a simple 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences, front-loaded with purpose, no fluff. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description fully covers purpose and usage context. Nothing is missing given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline is 4. Description adds value by explaining what the output contains (narrative orientation), going beyond the empty schema. Schema coverage is 100% but schema is empty.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a narrative orientation for first-time use, specifying contents (why it exists, boot ritual, 12 tools, next steps). It effectively distinguishes from siblings as the only orientation tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'if you are a Claude instance opening this stack for the first time and don't yet know what's here.' Adds value by noting it's cheaper than reading CLAUDE.md. No exclusion or alternative guidance, but clear enough.
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. It discloses the 25-60s wall time, that it writes to ~/.sovereign/reflections/, returns inline, and reads recent chronicle entries. It also mentions the default model and focus steering. There is no discussion of permissions or side effects beyond writing, but the description is adequately transparent for a local-LLM call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is approximately five sentences, front-loaded with the main action. Every sentence adds unique value: trigger, what it does, when to use, parameter guidance, and timing caution. No redundant or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description covers the essential aspects: purpose, usage, timing, parameter behavior, and output location. It differentiates from the recall_reflections sibling. It could be slightly more explicit about the return format, but overall it is comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 value by explaining the 'focus' parameter with an example of biasing without constraining, and the 'model' parameter with model suggestions and characterizations. This extra context raises the score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool triggers the synthesis daemon manually, reads chronicle entries, calls the local LLM, writes reflections, and returns them inline. It distinguishes itself from recall_reflections by noting the inline return, and from automatic operation by emphasizing 'manually' and 'on demand'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool explicitly says to use it 'when something is brewing and you want an outside read in 25-60s' and advises to call it 'deliberately, not casually.' It also notes that it replaces a separate recall_reflections call, providing clear context. However, it does not explicitly list when not to use it or compare with other closely related sibling tools like agent_reflect.
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, description reveals key behaviors: handoffs are marked consumed by default (unless consume=false), consumed handoffs remain queryable via recall_insights, and compact mode reduces token cost by ~40%. Discloses side effects of the call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two paragraphs with efficient structure. Front-loaded key purpose. Some redundancy ('in one breath') but overall well-organized for a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers output components (spiral status, handoffs, threads, insights, contextual resonance) without an output schema. Explains behavior of key parameters. Missing explicit return format details, but adequate for a boot-up tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but description adds significant meaning beyond field names: explains that domain_tags triggers a contextual resonance section, project adds match bonus, full_content controls truncation level, and compact omits preamble sections for efficiency.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this is a boot-up call that returns spiral status, unconsumed handoffs, recent open threads, and insights. It distinguishes from siblings like 'recall_insights' by being the initial resume tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Read this first when resuming work.' Mentions handoffs becoming consumed and queryable via recall_insights, providing guidance on when to use alternatives. However, no explicit 'when not to use' statement.
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 were provided, so the description carries full burden. It fully discloses that the tool appends to a JSONL file, never mutates the original message, and records integration. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. Every word contributes meaning: defines the action, distinguishes from read_by, clarifies integration, specifies file append, confirms non-mutation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description adequately explains what the tool does, its effect (append), and side effects (none on original message). It is fully self-contained for an agent to understand invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 4 parameters are already described in the input schema (100% coverage). The description adds no additional semantics to the parameters beyond the schema's own descriptions, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool records integration of a message, distinguishes it from read_by, and defines integration (not a glance). The verb 'acknowledge' is specific and the resource ('comms/acks.jsonl') is mentioned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on when to use (when actually integrated) versus when not (glancing), but does not explicitly name sibling tools or directly contrast with other ack-related tools like comms_get_acks.
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 full responsibility. It clearly indicates the tool performs a read operation (returns data) with no stated side effects. It lacks details on authentication or rate limits, but for a simple read-only status check, the information given is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the verb and resource. It is concise with no wasted words, covering the essential information efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (no parameters, no output schema, no annotations), the description provides a complete overview of what the tool returns and its purpose. No additional information is needed for an agent to correctly invoke and interpret the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to explain parameter behavior. The baseline is 4, and the description adds value by detailing the output fields, which compensates for the lack of parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('security posture of the sovereign infrastructure'), and lists the exact return values (health score, listening port count, etc.). It clearly distinguishes this status check from sibling tools like guardian_alerts or guardian_audit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to check overall security posture, which is clear from the purpose. However, it does not explicitly state when to use it versus alternatives, nor does it mention any prerequisites or exclusions. For a zero-parameter read tool, this is acceptable but could be slightly improved.
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 bears full responsibility for behavioral disclosure. It explains the core workflow (baseline capture, re-sampling, alerting) and probe types. It does not mention lifecycle details like persistence or cancellation, but the main behavior is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and well-structured: first sentence defines action, second explains mechanism, third usage context, fourth probe types. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of output schema, the description covers the purpose, usage, and probe details adequately. However, it does not explain the return value (likely a watch ID) or how to manage the watch later, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant value beyond the schema by summarizing probe types (http/command/file_hash) and explaining the default baseline behavior when 'expected' is omitted. The schedule_offsets_min default is also highlighted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool registers a post-fix verification watch, captures a baseline, schedules re-samples, and emits a honk on divergence. It distinguishes from sibling watch tools by focusing on post-fix verification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use after any fix whose surface signal might shift' and gives examples like load-balancer drift and cache invalidation, providing clear guidance on when to use. It lacks explicit when-not-to-use or alternatives, but the context is strong.
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 provided, so description carries full burden. It discloses pagination behavior (offset, order, limit up to 2000) and parameter ranges. However, it does not explicitly state that the operation is read-only or mention rate limits, though the verb 'Read' implies non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph. It front-loads the purpose, then logically covers special syntax, time bounds, ordering, and comparative advantage. Every sentence provides unique value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters and no output schema or annotations, the description covers most key behaviors (pagination, filtering, ordering). It omits details like default channel or error handling, but provides sufficient context for selection and basic usage. The sibling list is large, but the description differentiates from one key sibling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 43% (3 of 7 parameters documented). The description compensates by explaining the meaning and usage of unread_for, since/until time formats, order direction, and limit cap. It adds context beyond schema fields like 'inhabitant syntax' and default order.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read inter-instance messages from a comms channel with real pagination', specifying the verb, resource, and key feature (pagination). It distinguishes itself from sibling tools like /api/comms/read by noting differences in offset/order handling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides explicit when-to-use guidance: 'Unlike /api/comms/read, offset and order are honored and the limit can go up to 2000.' It also explains special syntax for unread_for and time bounds, helping agents choose this tool over alternatives.
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, the description fully discloses behavioral traits: priority order, k=1 enforcement, hard token cap, freshness penalty demoting recently surfaced items, and citations to academic papers. It comprehensively describes what the tool does and its safeguards.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense and front-loaded with the key action. Every sentence adds value, though it is slightly lengthy. It could be trimmed without losing clarity, but it remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, no output schema), the description covers parameters and behavior well. It explains the returned 'block' concept but does not detail its internal structure, which might be needed for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant meaning beyond the schema. It explains the priority order of sources, default k=1 reasoning, token cap behavior, and effects of flags like dry_run and full_content. This enriches parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Turn-start reflex. Call at the start of a turn (not session) to receive a compact priors block assembled from four sources.' The verb 'receive' and resource 'priors block' are specific, and the description distinguishes it from siblings by its unique role as a turn-start reflex.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'Call at the start of a turn (not session).' It also advises to 'Read the returned block before forming the turn's response.' However, it lacks explicit alternatives or when-not-to-use scenarios, though the sibling list implies distinct tools.
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?
Discloses key behaviors: replaces three calls, advances spiral phase, does not rotate session_id. Since no annotations, description carries full burden and does so thoroughly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each adding essential info: purpose, benefit, side-effect, critical note. Front-loaded and no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, behavior, alternatives, and side-effects. No output schema needed as return is implied. Comprehensive for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with clear descriptions. Tool description adds minimal extra meaning, mainly reinforcing the reflection theme. Baseline 3 is appropriate as schema suffices.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'close', resource 'session', and explains it replaces three other tools (record_insight, spiral_reflect, handoff), distinguishing from siblings. It is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (closing session) and when not (does not rotate session ID), and directs to spiral_inherit for fresh session. Also mentions it reduces ceremony, providing context for use.
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, the description fully carries the burden, disclosing that it does not clone state, provides specific context types, and mentions coupling factor R=0.46. It also explains the full_content parameter 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with key information front-loaded. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains the return (ground truths, hypotheses, open threads) and the tool's role in starting a new session with inheritance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing baseline of 3. The description adds context about full_content being a mirror of where_did_i_leave_off and the inheritance concept, enhancing understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool begins a new session with porous inheritance from a previous one, explicitly distinguishing it from cloning and detailing the layered context provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage when continuing work without full cloning, and references where_did_i_leave_off as an alternative for full inheritance. Does not explicitly list when not to use or compare to all siblings.
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 full behavioral disclosure. It reveals the internal scoring formula (tag_overlap*2 + recency_boost + project_match_bonus), parameter-specific details (project adds +0.5, recent_tools reserved for future affinity, limit_per_bucket caps items), and contextualizes the result set as buckets. This goes well beyond 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each earning its place: first defines purpose and outputs, second provides scoring insight and usage guidance. No filler words; information is front-loaded and highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains what the tool returns (threads, handoffs, mistakes, insights) and how scoring works, but does not describe the output structure or format of individual items. Given the absence of an output schema, a brief mention of the response shape would make it fully complete. Still, it covers the core behavioral aspects well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 significant extra meaning: explains how domain_tags, project, recent_tools, and limit_per_bucket affect scoring and behavior (e.g., future affinity weighting for recent_tools). This elevates understanding beyond the schema descriptions, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool surfaces open threads, handoffs, mistakes, and insights for the current context, using a specific verb ('Surface') and listing the exact resources. It distinguishes from siblings by advising to call this instead of querying individual buckets when bootstrapping or switching domains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'when bootstrapping a session or switching domains' and contrasts it with querying individual buckets, implying alternatives like get_open_threads or check_mistakes. This provides clear usage context without ambiguity.
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:

[![sovereign-stack MCP server](https://glama.ai/mcp/servers/templetwo/sovereign-stack/badges/card.svg)](https://glama.ai/mcp/servers/templetwo/sovereign-stack)

Score Badge

Copy to your README.md:

[![sovereign-stack MCP server](https://glama.ai/mcp/servers/templetwo/sovereign-stack/badges/score.svg)](https://glama.ai/mcp/servers/templetwo/sovereign-stack)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/templetwo/sovereign-stack'

If you have feedback or need assistance with the MCP directory API, please join our Discord server