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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.